Introduction

ModelOp Center provides the ability for a Model Life Cycle to create tickets within an existing Jira ticket system. A Model Life Cycle can create tickets corresponding to manual steps and tasks required. This includes items such as approvals, reviews, tasks, and other activities in a Model’s Life Cycle. This guide details the steps to enable the integration.

Jira Integration Setup

Prerequisites

This guide assumes moc-builder has been installed. Please request download instructions for moc-builder here. Before configuring moc-builder, the Jira instance will need a service account created and configured to use an API token. To create an API Token, follow the documentation at https://confluence.atlassian.com/cloud/api-tokens-938839638.html. This example assumes that the service account uses the email "jira@modelop.com".

moc-builder Jira Configuration

The integration requires the ModelOp Center Gateway url and the url of the Jira instance to be integrated.

First, determine the external-ip of the Gateway. Set the Kubernetes context to the cluster and namespace that has ModelOp Center deployed. Run the following command:

The command will return an output like this:

The important value is the external-ip and port corresponding to the ModelOp Center Gateway. In this example, it’s foo1.us-east-2.elb.amazonaws.com:8090.

NOTE: If the environment is using ingresses instead of load balancers, run kubectl get ing and obtain the address corresponding to the ingress that points to gateway. Do not append the port number to the end of the address. That is only required if you are using the external IP from a service of type LoadBalancer.

Next, open the application.yaml file within the moc-builder environment directory and navigate to the config.moc-services.gateway section. It will contain something like the following:

Change the value of external-url to the location of gateway from above.

Here is an example of that section of application.yaml:

Find the config.moc-services.supporting-services.jira section. It will contain something like the following:

Change the username to the email associated with the service account and the password to be the API token that was generated by Atlassian in the prerequisites step. Update the url to be Jira url. For this example we use https://foo.atlassian.net.

Here is an example:

Next, run the moc-builder compose and deploy commands to bring up the instance of ModelOp Center integrated with Jira.

Security

As mentioned in Prerequisites we recommend using a service account with an API token for the Jira integration. Limit the access rights of the service account to just those needed for the integration and only use the service account for the integration.

The integration uses Basic Authentication to authenticate REST calls to Jira. The credentials can be set up using Kubernetes secrets, as in the configuration example above, or using Vault.

Jira Ticket Customization

The integration provides a variety of parameters to allow customization of Jira ticket creation and lifecycle management within a Model Life Cycle. Some of these parameters are discussed in more detail below.

JIRA_PROJECT_KEY - The project key for the new ticket. The project must exist.

JIRA_ISSUE_TYPE - The name of the issue type to use for the new ticket.

JIRA_CUSTOM_FIELDS - A JSON string containing any custom fields to send with the creation request. By default the implementation will provide data for a few fields and this parameter allows setting as many fields as needed. The custom fields can also be used to override the value traditionally sent for that field. One exception to the override functionality is the description field. If the description field is overridden, the custom override value will be used as a notification message within the description and the default description template will still be used to ensure that links back to the appropriate entity are included in the description.

JIRA_EXIT_STATUS - A string listing out the exit statuses for the ticket. When the status reaches one of the exit statuses in this parameter the Model Life Cycle will stop watching the ticket and proceed.

UPDATE_STORED_MODEL_FIELDS - A map used to update values in the stored model from fields in the Jira ticket. As an example, a mapping from Model Risk to modelMetaData.modelRisk would update modelRisk to the value of the Jira Model Risk field.

UPDATE_DEPLOYABLE_MODEL_FIELDS - A map used to update values in the deployable model from fields in the Jira ticket. This works the same way as UPDATE_STORED_MODEL_FIELDS but targets a deployable model instead of the stored model.

Raising/Managing Tickets

To use a ticket within a Model Life Cycle a notification must be created and stored and then the ticket created and the lifecycle managed. Examples of how to use the different notifications are provided in mlc-building-blocks. A simple example is shown below.

Open

The Simple Notification requires the following parameters.

NOTIFICATION_MESSAGE - A message to include in the notification. This message will appear on the ModelOp dashboard. It will also appear as part of the summary and in some cases description of the Jira ticket unless those fields are overridden using JIRA_CUSTOM_FIELDS.

NOTIFICATION_SEVERITY - The severity of the notification (INFO, WARN, ERROR, etc.). This will be reflected in the ModelOp dashboard notification.

JIRA_PROJECT_KEY - The project key for the new ticket. (e.g., DEMO)

JIRA_ISSUE_TYPE - The name of the issue type to use for the new ticket. (e.g., Task)

Supplying these parameters correctly will result in a dashboard notification and a Jira ticket being created. After ticket creation, however, the Model Life Cycle will continue on and not wait for any specific status of the ticket. In some cases this is desirable but often waiting for a specific status is the desired behavior. The JIRA_EXIT_STATUS parameter can be used to set the the status to wait for. For example, if set to Done,Rejected then the Model Life Cycle will wait until the ticket's status has reached either the Done or Rejected status before continuing. The final status will be set in the TICKET_STATUS parameter which the Model Life Cycle can use to determine different paths of execution. See Jira Ticket Customization for more parameters for customizing ticket creation, updates, and lifecycle management.

In order to keep Model Life Cycles visually simple the three steps of this sub-process can be combined into a single activity as show below. For this example, all above parameters are moved to the external task (the final step, which could also be renamed) and the first two steps can be removed. An additional parameter of NOTIFICATION_TYPE must be set to PROCESS_NOTIFICATION to indicate the type of notification to create. The create and store steps will be executed as part of the external task. When specifying a NOTIFICATION_TYPE be sure to provide all needed parameters for that notification type.

Open

MLC Example Usages

The Jira integration is present in multiple locations in the DeployWithTestAndJira Model Life Cycle. Some examples are:

• If a requested test run fails a job notification is created. The user can choose to retry the job or exit the process.

• If requested, a model review notification is created to allow the user to review the results of the test.

• If a deployment or unexpected error occurs during processing a model review notification is created to review the error.

Each created notification appears on the Notification dashboard. Notifications also appear on context specific pages (E.g., Model Review Notifications will appear on the snapshot page). The display includes a link to the ticket and displays the ticket’s current status. The status is synced back periodically while waiting on the ticket’s exit status. An example is shown below.