Integrate Jira

The Optimizely Content Marketing Platform (CMP) to Jira integration is a bidirectional integration between the CMP and Jira (Cloud) that enables work delegation from the CMP to Jira.

Integration features 

• Creates a Jira issue from a step within a CMP task workflow and monitors its progress.
• Transfers data when an issue is created based on a pre-defined mapping, then allows bidirectional communication with status, comments, and attachment updates while the Jira external step remains open in the CMP.
• Selects Jira project from the CMP.
• Supports multiple Company Managed Projects or a single Team Managed Project.
• Pre-populates Jira fields on issue creation based on CMP task brief fields.
• Sends CMP assets to JIRA as attachments on Jira issue creation.
• Sets issue due date.
• Selects Issue Type (all types supported through mapping).
• Monitors Jira issue status in real-time from the CMP.
• Enables real-time collaboration between a Jira user and a CMP user with comments and attachments.
• Automates CMP step closure based on Jira issue status.
• Supports create and forget or create and wait from the CMP.

Requirements

• Cloud-based Jira Instance.
• JIRA Service account supporting OAuth 2.0.
• Admin access to Jira.
• Can accept inbound API requests to your Jira instance.

Configure Jira

Service account

Create a service account in Jira with xyz permissions. This is the main account that makes API calls from CMP to Jira and controls the integration's actions. Create the service account user and use an identifiable name, such as CMP Service Account.

Webhook

A webhook needs to be created and configured in Jira to enable the Jira to CMP actions on specific events. Your Jira Admin should be able to configure this for you. See also Webhooks by Atlassian Developer.

1. Go to System settings in Jira.

   

2. Select Advanced > Webhooks and JIRA Standard Integration: Default.

   

3. Click Create Webhook. CMP provides the URL in the webhook during deployment.
4. Enter Jira to CMP Listener in the Listener field.
5. Under Issue related events.
   • Configure the JQL query to contain only the projects the integration will use to create issues.
   • Configure the webhook to be fired only on the following events:
     • Issue modified
     • Comment created
     • Comment modified
     • Attachment created

Create a custom field

Create a custom field to store the callback URL used to communicate with CMP.

• The custom field should be a Text field or URL field. 
• The custom field needs to be active on the Jira screens to be accessible from the API.

Configure CMP

Create a brief

The Jira integration uses a CMP brief to:

• Indicate the Jira project in which the issue should be created
• Hold the data used when creating the Jira issue

As a result, configure one brief template for each Jira project. Name the brief template to indicate which project it is related to. The brief template must contain at least the fields synched to Jira so the integration can map them. 

For the Jira integration to work, the mandatory fields are:

• Title
• Description
• Jira Issue Type

In the following example template, CMP maps values in Title, Description, and Jira Issue Type to the JIRA issues Title, Description, and Issue Type. If your Jira projects have other mandatory fields (such as Due dates, Custom field, and so on), you can add them to the templates. You do not need to add a Status field or a JIRA link field to the templates because those are available in the CMP's external step. 

See Templates and dynamic forms for instructions on how to set up templates.

Create a workflow with an external step

After you create a Jira ticket using briefs, the external step then does the following:

• Comments from CMP can go to Jira if they occur on the external step in CMP.
• Comments from Jira can go to CMP at any point after the Jira ticket is created.
• You can send attachments through comments from CMP if you add the comment to the external step. 
• You can send attachments from Jira to CMP. They appear in the comment section on that external step on the CMP UI.

Here is how to include an external step in your workflow.

1. Go to the Workflow settings page and click Create New Workflow (or edit an existing workflow).

   

2. Click Add external step.

   

3. Select Select external system. In this case, it should be Jira. If it has not already been created, you can create one by clicking Manage External System.

   

4. A workflow can have several steps before or after the external step, and each step can start one after the other. After the external step starts in your workflow, CMP creates a Jira ticket in your Jira board. However, if you select Allow User Actions, you must manually initiate the Jira creation process from that step.

   

• CMP App – Required to authenticate the CMP platform using the API. You can find the requisite details on how to get started with Optimizely Content Marketing Platform Open REST API.

• CMP Webhook – Required to trigger the integration on specific events. Required events are:
  • external_sub_step_started
  • external_sub_step_comment_added
  • external_sub_step_comment_modified

Here is how you can go to the options:

1. Select avatar > Apps & Webhooks.

   

2. Open the Webhooks tab to access the options.

   

3. Click Register Webhook and fill out the required fields.

   

4. Select the following events for proper integration:

   

Deploy the integration

The Optimizely Expert Services team needs to complete the integration deployment. A solution consultant will work with you during onboarding to deploy the integration to your CMP instance. The following things are deployed:

• Service accounts for JIRA and CMP
• Jira instance Domain mapping
• External step management: Automatic or manual
• Jira project mapping
• Jira field mapping (that is, Summary, Description, Issue types, Due date, custom fields, and seven associated values)

Use the integration

It starts with creating a task. The task must have a brief for creating the initial JIRA with the necessary information. It depends on the mapping, but some of the common things from which you will create a JIRA ticket and collaborate with the external JIRA team to complete a project. Below, the process is described in a few steps:

1. Create a task with the campaign that has a brief, which in turn creates the initial Jira ticket. 
2. Assign a workflow with an external step.
3. Set the due date and fill out other information to create the task.

   

4. Select a brief template that is tied to the Jira integration. 
5. Fill out the fields in the brief sections before the external step initiates.
   After creating a Jira ticket, you cannot update your Jira from the brief.

   

6. In the workflow, complete the other steps before initiating the external step.
7. Depending on your workflow setup, a Jira ticket is created when you initiate the external step, or you will have to create it manually.
   • External step selection: Allow User Action

     

     

     • Create the Jira ticket when you initiate the external step.
     • Create the Jira ticket manually by selecting In progress from the step.
     • Close the Jira ticket manually to move to the next step in the workflow.
   • External step selection: Do not allow user action

     

     

     1. Create the Jira ticket when you initiate the step.
     2. You do not need to close the Jira ticket for the external step to proceed to the next step in the workflow.

     Comment and share resources with the Jira users:

     • Use the comment section in the workflow to share or receive updates from the Jira ticket.
     • Upload or get resources from Jira in the comment section.
     • Get notifications in the Notification tray for any updates from Jira. 

       

     • Monitor Jira ticket status updates from the external step.