Integrate Jira

  • Updated

The Optimizely Content Marketing Platform (CMP) to Jira integration is a bi-directional integration between the CMP and Jira (Cloud) enabling the delegation of work from CMP to Jira.

This integration is purchased separately and requires services to be configured and activated in your instance.

Integration features 

  • Creates a Jira issue from a step within a CMP task workflow and monitor its progress.
  • Transfers data when an issue is created, based on a pre-defined mapping, then allow bi-directional communication via 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 via mapping)
  • Monitors Jira issue status in real-time from the CMP
  • Enables real-time collaboration between a Jira user and a CMP user via 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 makes API calls from CMP to Jira. Actions performed by the integration are tied to the service account user. Create the service account user and use an easily 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.

    integrate-jira-1.png

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

    integrate-jira-2.png

  3. Click Create Webhook. The URL in the webhook will be provided 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 that the integration will use to create issues in.
    • 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 back with CMP.

  • The custom field should be either 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 that will be used when creating the Jira issue

As a result, configure one brief template for each Jira project. Name the brief template to clearly indicate which project it is related to. The brief template needs to contain at least the fields that need to be synchronized to Jira so they can be mapped by the integration. 

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

  • Title
  • Description
  • Jira Issue Type

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

The form can hold an unlimited amount of additional fields that may not be required by the integration.

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

Integrate-jira-c.png

Create a workflow with 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. This occurs at any point after the Jira ticket is created.
  • Attachments can also be sent across via comments from CMP if the comment is added to the external step. 
  • Attachments can also be sent from Jira to CMP. They show up 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).

    integrate-jira-4.png

  2. Click Add external step.

    integrate-jira-5.png

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

    integrate-jira-6.png

  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, a Jira ticket is created in your Jira board. However, if you select Allow User Actions, you must manually initiate the Jira creation process from that step.

    integrate-jira-7.png

  • CMP App – Required for authenticating to 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 navigate to the options:

  1. Select avatar > Apps & Webhooks.

    integrate-jira-9.png

  2. Open the Webhooks tab to access the options.

    integrate-jira-10.png

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

    Integrate-jira-a.png

  4. Select the following events for proper integration:

    Integrate-jira-b.png

Deploy the integration

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

  • Service accounts for both JIRA & CMP
  • Jira instance Domain mapping
  • External step management: Automatic or manual
  • Jira project mapping
  • Jira field mapping (i.e.: Summary, Description, Issue types, Due date, custom fields 7 associated values)

Use the integration

It starts with creating a task. The task must have a Brief which will be responsible for creating the initial JIRA with all the necessary information. It depends on the mapping but some of the common things that are from which you will create a JIRA ticket and collaborate with the external JIRA team for the completion of a project. Below the process is described in a few simple 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.

    Integrate-jira-d.png

  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 a Jira ticket is created, you cannot make updates to your Jira from the brief.

    Integrate-jira-e.png

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

      Integrate-jira-i.png

      Integrate-jira-f.png

      • The Jira ticket can be created when the external step initiated.
      • The Jira ticket has to be created manually by selecting In progress from the step.
      • The Jira ticket has to be closed manually to move to the next step of the workflow.
    • External step selection: Do not allow user action

      Integrate-jira-j.png

      Integrate-jira-g.png

      1. The Jira ticket is created when the step is initiated.
      2. The Jira ticket of external step does not need to be closed to move on to the next setp in the workflow.

      Comment & 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.

        Integrate-jira-h.png

      • Monitor Jira ticket status update from the external step.