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 is based on using the distribution moc-configuration for helm. If you do not have the distribution moc-configuration, please request download instructions here.

Before configuring, the Jira instance will need a service account created and configured to use an API token. A service account is a user account specifically created to handle service requests and can be created like any other user. Be sure to limit permissions to only those needed. 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".

Also, ensure that attachment attachments are enabled: https://support.atlassian.com/jira-cloud-administration/docs/configure-file-attachments/ or https://confluence.atlassian.com/adminjiraserver/configuring-file-attachments-938847851.html

For instructions on installing helm, see: https://helm.sh/docs/intro/install/

moc-configuration Jira Configuration

The configuration properties for Jira are located in application.yaml. Edit the following properties:

modelop:
  moc-center-url: # this should be the external name of MOC; this url will be the base for urls from jira back to moc center entities
  jira-url:       # this should be the external name of Jira
  jira-user:
  jira-password:

As an example, this these properties might look as follows:

modelop:
  moc-center-url: foo1.us-east-2.elb.amazonaws.com:8090
  jira-url: https://foo.atlassian.net
  jira-user: jira@modelop.com
  jira-password: apitoken

where foo1.us-east-2.elb.amazonaws.com:8090 is the external URL to the gateway, https://foo.atlassian.net is the Jira URL, jira@modelop.com is the user name, and apitoken is the apitoken.

Next, ensure the configuration is active in the fleet.

• If using sscs backed by git, commit the changes and refresh the actuator or restart mlc-manager

• If using a configmap, run helm upgrade, restart sccs, and refresh the actuator or restart mlc-manager

Jira Task Monitor Configuration

The Jira task monitor is a background task that periodically queries the state of tickets in a Jira and reacts appropriately to that state. The Jira worker task monitor comes with defaults but values can be configured to meet customer needs.

The default Jira Task Monitor Configuration is located in mlc-service.yaml and is defined as follows:

  jira-task-monitor:
    poll-rate: 5000
    user: ${modelop.jira-user}
    password: ${modelop.jira-password}
    url: ${modelop.jira-url}
    retry-config:
      - retry: 4
        retry-timeout-millis: 60000
      - retry: 3
        retry-timeout-millis: 300000

The available configuration properties, not already discussed, are defined discussed below.

poll-rate - The amount of time in milliseconds between checking the status of Jira tickets.

retry-config - A list defining the retries and retry timeouts when an error occurs. The list is evaluated in order where retry is the number of retries and retry-timeout-millis is the length of time to wait between retries on that level. If retry-timeout-millis is less than poll-rate then poll-rate will take precedence. In the default configuration above the Jira task monitor will retry 4 times with 1 minute between each retry. After those retries are exhausted the task monitor will then retry 3 times with 5 minutes between retries. When all retry levels are exhausted an incident will be raised. After the retries on each level are exhausted a dashboard notification is created indicating the error.

minumim-elevated-priority - (Not shown in default config; default: “High”) The minimum priority in Jira that is considered elevated priority in ModelOp Center. The priority ordering scheme is intended to match that used in Jira: https://confluence.atlassian.com/adminjiraserver/associating-priorities-with-projects-939514001.html. If the value is not an actual priority in Jira, then no tickets are considered elevated priority.

cache-refresh-minutes - (Not shown in default config; default: 60) The number of minutes between pulling and caching Jira system data. Currently this data consists of the priority ordering of statuses.

After setting these properties ensure the configuration is updated in the fleet as described above.

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 SCCS config, 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. (To create a new project see https://support.atlassian.com/jira-software-cloud/docs/create-a-new-project/)

JIRA_ISSUE_TYPE - The name of the issue type to use for the new ticket. (To manage issue types see https://support.atlassian.com/jira-cloud-administration/docs/add-edit-and-delete-an-issue-type/)

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. (For more details on the rest API payloads see https://developer.atlassian.com/server/jira/platform/rest-apis/)

JIRA_EXIT_STATUS - A comma separated 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. The statuses for a Jira ticket are managed by the projects workflow. For more information about managing a projects project's workflow see https://support.atlassian.com/jira-software-cloud/docs/what-are-jira-workflows/.

UPDATE_STORED_MODEL_FIELDS - A map from Jira field name to beanutil expression 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. This is a powerful feature that allows for importing information/metadata from Jira into the model’s metadata in ModelOp Center for visibility and auditability.

UPDATE_DEPLOYABLE_MODEL_FIELDS - A map from Jira field name to beanutil expression 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. Again, this is a powerful feature that allows for importing information/metadata from Jira into the model snapshot’s metadata in ModelOp Center for visibility and auditability.

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.

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.

Simplified Approach

In order to keep Model Life Cycles visually simple, the three steps of this the above 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.

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.