Public API tutorial

This tutorial introduces you to using Backbone's public Java API. You will develop two simple field mappings for text fields which will add a prefix to the values.

Before you get started, be sure you have experience with the Atlassian SDK and building a Project as well as using Spring and Maven. This tutorial doesn't focus on the structure of the app, but on the implementation code.

Create an app skeleton

First, create a new project for your app. Create an app skeleton using the Atlassian SDK with the following command:

atlas-create-jira-plugin

Please note that not all generated files are needed, feel free to remove unused files and code from the skeleton if you're already familiar with Atlassian apps.

Add the Java API

Next, add the Java API to your project. The Java API contains interfaces that enables you to implement your own field mappings.

Once the dependency is imported into your IDE, you can browse and use the Java API.

Implement your field mappings

Now, you can start to implement your field mappings.

1. Create a new class which implements the interface CustomIncomingFieldMapping


   JAVA

   public class PrefixStringIncomingMapping implements CustomIncomingFieldMapping {
   
   }

2. Define a name and identifier for this field mapping.
   The name will be shown in the Backbone UI when you configure a field mapping. The identifier is the internal key to select this mapping during the synchronization.

   JAVA

   @Override
   public String getName() {
       return "Incoming Prefix String Mapping";
   }
   
   
   @Override
   public String getIdentifier() {
       return "incomingPrefixStringMapping";
   }

3. Define the data types this field mapping handles.
   These data types are used so that Backbone can offer the correct fieldmappings when someone adds a field mapping.
   The Jira field type corresponds to the schema part of the fields rest endpoint. The class StandardJiraFieldTypes contains some useful constants for that. We go with a usual textfield for now. You can see an example for custom field types in our example project.
   The message field type defines the type of the data which is in the issue synchronization message.

   JAVA

   @Override
   public JiraFieldType getJiraFieldType() {
       return StandardJiraFieldTypes.STRING_TEXTFIELD;
   }
   
   
   @Override
   public JiraFieldType getMessageFieldType() {
       return StandardJiraFieldTypes.STRING_TEXTFIELD;
   }

4. Implement the actual mapping logic
   The field parameter contains the content for this field from the issue synchronization message. You can apply your custom logic, we add a prefix to the value now. In order to tell Backbone that the value should be updated, the result needs to be wrapped inside a FieldMappingResponse object.

   JAVA

   @Override
   public FieldMappingResponse mapIn(SimpleIssueBean simpleIssueBean, Field field, Map<String, Object> context) {
       if (field != null) {
           return new FieldMappingResponse("PREFIX_" + field.getValue());
       }
   
       return null;
   }

Declare your mappings

In order to export your field mappings so that Backbone is able to detect them, you have to declare them in your atlassian-plugin.xml.

• key: Unique key of this mapping across this atlassian-plugin.xml
• name: A name to identify this mapping in Atlassian's plugin manager. This is not the name how the mapping will appear in Backbone's UI.
• class: The fully qualified class name of this mapping.

<backbone-incoming-field-mapping key="incoming-prefix-string-mapping"
                                 name="Incoming Prefix String Mapping"
                                 class="com.k15t.example.api.PrefixStringIncomingMapping"/>

Try it out

Now the app is complete, try it out:

1. Package your app via mvn package
2. Start Jira
3. Install Backbone
4. Install your app
5. Create a synchronization
6. Configure the issue type & the required fields
7. Configure your field mapping
8. Publish your configuration and start the synchronization
9. Create a new issue & define a value for the field you mapped with your field mapping
10. Check the remote issue. It should contain the value you entered during issue creation including your prefix.

Congratulations on completing this tutorial!

You can have a look at the example project for further example field mappings.