Use the Java API

Make Backbone your own by extending its functionality using the public Java API in your custom app.

Backbone's public Java API enables you to add your custom ways how fields should be synchronized. In more detail, you can:

Add outgoing field mappings which export the data from a Jira issue
Add incoming field mappings which import the data into a Jira issue

By uploading your app to the same Jira, Backbone will detect all field mappings implemented in your app and will make them available in the Backbone UI to configure synchronizations.

Examples

Backbone's Java API are e.g. helpful in these situations:

You implemented a custom field in your own app and want to synchronize this field with Backbone.
You want to synchronize third party custom fields Backbone does not support (yet).
You want to further customize the transformation logic between two fields.

Background Information

In order to get the full potential out of your custom field mapping, we strongly suggest to carefully read the following information.

Concept

The way Backbone Issue Sync for Jira Server synchronizes Jira issues works like the following:

In the picture above, you can see two Jira projects which are synchronized with Backbone. No matter if the projects are on the same or different instances, the synchronization behavior is the same.

The synchronization process consists of multiple steps:

As soon as Backbone detects a change of an issue in project A, the outgoing queue exports these changes from the Jira issue to an issue synchronization message.
Backbone sends the issue synchronization message from the outgoing queue of project A to the incoming queue of project B.
The incoming queue in project B imports the changes from the issue synchronization message to the Jira issue.
Both issues are up to date.

Since users can configure a synchronization in both directions, each project has one outgoing queue and one incoming queue.

With a (custom) field mapping you are able to hook into the process of adding the issue data into the issue synchronization message (in the outgoing queue) or from the issue synchronization message into the issue (in the incoming queue).

These processes are further explained below.

Outgoing queue

The outgoing queue is periodically executed and performs these steps:

Detects issue changes based on a JQL query.
Analyzes the issue history and detects which issue fields have changed.
- In case of a new issue, these will be all fields.
- In case of a resync, the fields depend on the selection of the user in the resync dialog.
Calls all the outgoing field mappings for which a change has been detected and collects their output data.
Creates an issue synchronization message based on the output data.
Sends the message to the incoming queue of the other connector.

Issue synchronization message

The issue synchronization message contains the data for each field relationship between A and B. This data is mapped between A and B by using a unique id which has been set in Backbone's configuration. Backbone takes care of resolving the relationships.

Incoming queue

The incoming queue starts as soon as a new message arrives and performs these steps:

Retrieves issue synchronization message.
Determines if the issue is new or already exists.
If the issue is new:
- Calls all field mappings for the fields which are on the create screen for that project.
- Creates the issue with the result data of the field mappings.
Calls all remaining field mappings. Custom field mappings are always applied in this step even though the fields they are configured for might be on the create screen.
Updates the issue with the result data of the remaining field mappings (if necessary).

Get Started

Now you have all the background knowledge you need to know. In order to get started with your own field mapping, you can either

start with our step-by-step tutorial to implement your first mapping
or explore our example project and adapt it to your needs
or learn how to add the Java API to your existing app

Share Your Extension

We are excited to see what you're building and which custom field's you are supporting now. Please reach out to us via support@k15t.com and let us know.

Feedback & Help

In case you have any suggestions, questions or problems about our API, feel free to reach out to our support team. We're happy to help with any questions about our API.

If you have general questions about Jira app development, please also have a look at Atlassian's developer community.