Connector Create REST API - one-click or automatic Jira Issue creation

This guide will help you configure your Salesforce using the Connector Create REST API so that it has the ability to automatically create a Jira Issue on your Jira instance and also an alternative to the standard way of . configuring a Create Jira Issue button in Salesforce.

The benefits of using this method include not requiring Jira credentials to log in every time a Jira Issue is created as well as providing a one-click experience for the user (allowing the user to bypass selecting Issue Types or Projects).

This method will require writing several Apex Classes, the codes of which will be provided below. Also provided are Unit Test Codes for the Create REST API.

All Apex Class codes provided are also provided on our Bitbucket Repository for your reference.

(warning) This setup can only be used if your Jira instance is NOT behind a firewall.

Writing the Apex Class

This example will guide you on how to call the Create REST API.

Before you write the Apex code that calls the remote URL, you have to allow Salesforce to make a call to the external server.

  1. Log in to Salesforce.
  2. Go to Your Name > Setup > Administration Setup > Security Controls > Remote Site Settings.
  3. Add new remote site.
  4. Enter the name of remote site.
  5. Enter your Jira URL in Remote Site URL, e.g.: http://yourjiraurl.com/
  6. Click Save.

Once you are done, you can start writing the code. Here are the steps to write a Salesforce Apex Class.

  1. Log in to Salesforce.
  2. Go to Setup > App Setup > Develop > Apex Classes > New. (If you have already created this Apex Class, you do not need to do this step).
  3. Now, create another Apex Class (follow the same steps in Step 2) and paste the following code into the field:
     

     global class JIRAConnectorWebserviceCalloutCreate {
    
        @future (callout=true) WebService static void createIssue(String baseUrl, String systemId, String objectType, String objectId, String projectKey, String issueType) {
            try {
                HttpRequest req = buildRequest(baseUrl, JIRA.username, JIRA.password, systemId, objectType, objectId, projectKey, issueType);
                JIRA.sendRequest(req);
            } catch(System.CalloutException e) {
                System.debug(e);
            }
        }
    
        // Constructs request needed to create a JIRA issue from provided parameters.
        @testVisible private static HttpRequest buildRequest(String baseUrl, String username, String password,
                                               String systemId, String objectType, String objectId,
                                               String projectKey, String issueType) {
            HttpRequest req = new HttpRequest();
            String basicAuthHeader = JIRA.authHeader(username, password);
            String endpoint = getEndpoint(baseUrl, systemId, objectType, objectId);
            req.setHeader('Authorization', basicAuthHeader);
            req.setHeader('Content-Type','application/json');
            req.setMethod('POST');
            req.setEndpoint(endpoint);
            req.setBody('{"project":"' + projectKey + '", "issueType":"' + issueType + '"}');
            return req;
        }
    
        // Creates the endpoint to create the issue from provided parameters.
        private static String getEndpoint(String baseUrl, String systemId, String objectType, String objectId) {
            return baseUrl + '/rest/customware/connector/1.0/' + systemId + '/' + objectType + '/' + objectId + '/issue/create.json';
        }
    
    }

    Copying the above code and pasting it directly into the field may result in additional, unwanted characters being included. To avoid this from happening, we recommend pasting the code into a text editor that accepts plain text (e.g. Notepad.exe) and then recopying it again before pasting it into the field.

  4. Click Save.
     

WARNING

Please use this class with care. It can cause an infinite loop of Issue and Case creation if it conflicts with the JIRA Push to Remote System workflow.

Usage of the written class

Now that the class is ready to be used, it can be called in various ways including:

  1. From within a Trigger.
  2. From Create Jira Issue button, as a replacement of Configuring a Jira Issue Creation button.

Trigger

Salesforce Trigger can be used to automate the creation of Jira issue. It is an event-based process similar to Jira workflow, yet more flexible.

In this example, we want to automate Jira Issue creation when a Case is created:

VERY IMPORTANT NOTE:

You will NEED to create a custom profile called "JIRA Agent" in Salesforce to avoid causing an infinite loop. Then assign a user to that profile and block it to execute the trigger.

This way, any cases created from JIRA will not trigger creation of more issues back to JIRA.

First, create a custom profile called "Jira Agent":

  1. Log in to Salesforce.
  2. Go to Setup > Administration Setup > Manage Users Profiles > New Profile.
  3. Choose 'Existing Profile' to be: Custom: Support Profile.
  4. Fill in "Profile Name" with : JIRA Agent.
  5. Click Save.

    "CUSTOM: SUPPORT PROFILE" NOT AVAILABLE?

    Your version of Salesforce may not have the Custom: Support Profile option.

    If so, you can create a new profile or clone from any existing profile. But please make sure that the profile has ReadEdit and Create permissions for the relevant object.

     

Second, assign the created profile to specific user that will be used in the Connector:

  1. Go to Setup > Administration Setup > Manage Users > Users.
  2. Create/Edit the user that is used as JIRA agent.
  3. Use the created profile as profile of the user.
  4. Click Save.
     

    WARNING

    Make sure that this user is used in the Application Links authentication in Jira.

Third, add Trigger code to Case Trigger.

  1. Write Apex Class as described above
  2. Go to Setup > Application Setup > Customize > Cases > Triggers.
  3. Create a New Trigger and replace the code with:
     

     trigger CreateIssue on Case (after insert) {
    
        // Check whether current user is not JIRA agent so that we don't create an infinite loop.
        if (JIRA.currentUserIsNotJiraAgent()) {
            for (Case c : Trigger.new) {
                // Define parameters to be used in calling Apex Class
                String objectType ='Case'; 	// Please change this according to the object type
                String objectId = c.id;
                String projectKey = 'SFDC';	//Please change this according to the JIRA project key
                String issueType = '1';		//Please change this according to the JIRA issue type ID
                // Calls the actual callout to create the JIRA issue.
                JIRAConnectorWebserviceCalloutCreate.createIssue(JIRA.baseUrl, JIRA.systemId, objectType, objectId, projectKey, issueType);
            }
        }
    
    }

    Copying the above code and pasting it directly into the field may result in additional, unwanted characters being included. To avoid this from happening, we recommend pasting the code into a text editor that accepts plain text (e.g. Notepad.exe) and then recopying it again before pasting it into the field.



  4. Change the variables accordingly:
     

    Variables

    Details

    objectType

    Salesforce object that is used in Connection. In our example, it is Case.

    objectId

    The id of the object. It varies in every operation. Therefore, it should be object.id

    projectKey

    Under which JIRA Project you want to create the issue.

    issueType

    standard JIRA issue type values range from '1' to '4' . '1' is for Bug and so on

  5. Click Save.
     

Now you are ready to use the trigger. Try creating a Case in Salesforce as a normal user and check if the Jira Issue is created.

Button

Other than using it as a trigger, you can use the written APEX class for a Jira Issue Creation button. Using this method, you can eliminate some processes, including:

  1. The required log-in page
  2. The prompt page of choosing Project and Issue type.

Step-By Step Guide:

  1. Write the Apex Class as above.
  2. Then, you can follow the steps in Configuring Jira Issue Creation button to create a button. Note the minor changes in Step 8:
     

    Label

    Create Jira Issue

    Name

    Create_JIRA_Issue (this is auto-populated when you add a new label)

    Display Type

    Detail Page Button

    Behaviour

    Execute Javascript

    Content Source

    On Click Javascript

    Content

    {!REQUIRESCRIPT("/soap/ajax/29.0/connection.js")}
    {!REQUIRESCRIPT("/soap/ajax/29.0/apex.js")}
    sforce.apex.execute("JIRAConnectorWebserviceCalloutCreate","createIssue", {baseUrl:"http://jira.example.com", systemId: "1", objectType: "Case", objectId:"{!Case.Id}", projectKey:"SFDC", issueType:"1"});
    window.alert("JIRA Issue should be created.");
  3. Change the variables accordingly:
     

    Variables

    Details

    baseUrl

    Your Jira URL

    systemId

    Your system Id in Connection. You should check this in Jira under Connection

    objectType

    Salesforce object that is used in Connection. In our example, it is Case

    objectId

    The id of the object. It varies in every operation. Therefore, it should be object.id

    projectKey

    Under which Jira Project you want to create the issue.

    issueType

    Standard Jira issue type values range from '1' to '4' . '1' is for Bug and so on.

Now you are ready to test:

  1. Create a new Case in Jira.
  2. Click on Create Jira Issue button.
  3. You should see a pop up window: Jira Issue should be created.
  4. Check your Jira if the issue has been created.

Unit test code for Create Endpoint

Provided below is the Unit Test code for this class.

Do remember to also include the Fixtures and Mock Objects found on the Apex Class Parent Code page before using the following code:

@isTest private class JIRAConnectorWebserviceCalloutCreateTest {

    // Tests createIssue method in JIRAConnectorWebserviceCalloutCreate.
    static testMethod void createIssueTest() {
        Test.startTest();
		Test.setMock(HttpCalloutMock.class, new MockHttpResponseJIRAConnector());
        JIRAConnectorWebserviceCalloutCreate.createIssue(TestFixture.baseUrl, TestFixture.systemId,
                TestFixture.objectType, TestFixture.objectId, TestFixture.projectKey, TestFixture.issueType);
        Test.stopTest();
    }

    // Tests buildRequest method in JIRAConnectorWebserviceCalloutCreate.
    static testMethod void buildRequestTest() {
        HttpRequest req = JIRAConnectorWebserviceCalloutCreate.buildRequest(TestFixture.baseUrl, TestFixture.username,
                TestFixture.password, TestFixture.systemId, TestFixture.objectType, TestFixture.objectId,
                TestFixture.projectKey, TestFixture.issueType);
        System.assertEquals(req.getMethod(), 'POST');
        System.assertEquals(req.getEndpoint(), 'http://jira.com/rest/customware/connector/1.0/1/Case/1/issue/create.json');
    }

}

Unit test code for trigger on CreateIssue

Provided below is the Unit Test code for this class trigger.

Do remember to also include the Fixtures and Mock Objects found on the Apex Class Parent Code page before using the following code:

@isTest public class CreateIssueTest implements HttpCalloutMock {
    private static HttpRequest request;
    private static HttpResponse response;

    public HTTPResponse respond(HTTPRequest req) {
        request = req;
        response = new HttpResponse();
        response.setStatusCode(200);
        return response;
    }

    @isTest static void createIssueTriggerTest() {
        Test.setMock(HttpCalloutMock.class, new CreateIssueTest());
        Case case1 = new Case();

        Test.startTest();
        insert case1;
        Test.stopTest();

        System.assertEquals(JIRA.baseUrl + '/rest/customware/connector/1.0/' + JIRA.systemId + '/Case/' + case1.id + '/issue/create.json', request.getEndpoint());
    }
}