Requirements

• A Jira Service Management Cloud subscription and Web access.
• Lumu Defender API key
• To retrieve an API token, please refer to the Defender API document.
• Script host.
• A scripting host is required to deploy the integration. This host must have Internet visibility over Lumu Defender API endpoints and Jira Service Management. According to the deployment model you select, you will need a host with:
• Python 3.10+
  

• A Docker-enabled host.
  
• Script package
  
• Contact the Lumu support team to request the package we created to deploy the required files.
  

Contacted hosts

Allow all the traffic to the following hosts. These are required for the operation of this integration:

• <INSTANCE>.atlassian.net
• defender.lumu.io

Jira Software on Cloud gives you a subdomain within attlassian.net, save it for the integration configuration file

Prepare Jira Service Management for Lumu integration

Before you deploy and implement the Lumu Integration, you need to prepare your Jira SM deployment to ensure the integration works as expected.

Identify your Jira SM Cloud instance

To identify your instance, go to your Web browser and open your Jira console. Check the URL and extract your instance name. Your Jira URL must look like <INSTANCE>.atlassian.net. That is your instance name.

Create an API Account Token

Select a Jira SM Project

The tickets created by the integration will be associated with a project managed in your Jira SM portal. You can select an existing project or create a new one.

If you need to create a new one, under your Jira SM console, click on the Project tab, then on the Create Project button. Configure your new project based on the offered template.

Select a Request type

You need to associate a type for the request created by the integration. Select the request type you want to use from the list under your Project Settings from the left panel and click on Request types.

Extract statuses and transitions from the request type workflow

Jira SM requests operate with workflows. Each Jira workflow is composed of a set of statuses (the state your work can be in) and transitions (how your work moves between statuses). You need to make sure the workflow allows you to change states based on the required transitions. 

You can check this by clicking on the three-dots icon on the left side of the request type. In the drop-down list, click on the View workflow option.

Arrows are Transitions to status, Boxes are status.

From this workflow, identify and classify its transitions into three categories:

• In progress: transitions available in the request type that lead to an “In Progress” (Continue) status
• Pending: transitions available in the request type that lead to a “Pending” (Hold) status
• Done: transitions available in the request type that lead to a “Close” (Done, Resolve) status.

These categories are related to Jira SM statuses. You need to interpret the workflow view to identify to which category each workflow state belongs. Check the color code of the editor.

Here, you see two workflow examples. The first workflow looks as follows

The statuses for this workflow are TO DO, IN PROGRESS, PENDING, and DONE.

The transitions are: Approved, Start, Reopened, In review, and Resolved.

Let’s map each transition in each category:

• In progress: Approved, Start, Reopened
• Pending: In review
• Done: Resolved

Now, you need to identify which status you will use for each Lumu status:

• In progress: Unmute
• Pending: Mute
• Done: Close

Make sure you identify this information for your workflow. This will be used later for setting up the integration script.

Now, let’s analyze the second example:

The statuses for this workflow are WAITING FOR SUPPORT, WAITING FOR CUSTOMER, ESCALATED, IN PROGRESS, PENDING, CANCELED, RESOLVED, and CLOSED.

The transitions are: In progress, Pending, Respond to customer, Resolve this issue, and Cancel request.

Let’s map each transition in each category:

• In progress: In progress, Respond to customer
• Pending: Pending
• Done: Resolve this issue, Cancel request

Now, you need to identify which status you will use for each Lumu status:

• In progress: Unmute
• Pending: Mute
• Resolved: Close
• Closed: Close

Make sure you identify this information for your workflow. It will allow the integration to sync Lumu and Jira tickets, including their statuses. This will be used later for setting up the integration script.

Collect complementary information

The integration requires this complementary information:

• Label
• Organization
• Assignee
• Reporter
• Priority

Define a label

The label is a tag that allows you to easily identify a request within a project. For example, you can use “LumuSecOps” as a label.

Define the Organization

An Organization is an entity that can be used for MSPs to identify groups of customers within a project, e.g. “CompanyEast”

You can skip this step if you don’t have multiple organizations. If you need to assign tickets to an Organization, make sure the Organization exists in the SM project.

Set Assignee and Reporter

If you need to assign or create Lumu tickets to or on behalf of a particular user, you can define the Assignee and the Reporter. You can use its Display name or email.

Define ticket priority

The allowed values are Highest, High, Medium, Low, Lowest

For MSP deployments, it’s recommended to collect and use the parameters above. This will be used for setting up a single integration script to work with multiple Organizations.

Collect the required data from Lumu portal

The integration set-up process needs you to collect this information from Lumu portal:

• Lumu Defender API key
• Company UUID

Log in to your Lumu portal and run the following procedures to collect these data.

Collect the Lumu Defender API key

To collect the Lumu Defender API key, refer to the Defender API document.

Collect your Lumu company UUID

To collect your Lumu company UUID, log in to your Lumu portal. Once you are in the main window, copy the string below your company name.

Deploy the integration

There are 2 environment options to deploy the script, select the one that best fits your current infrastructure.

• Run it as a Python script executing the install.sh bash file
• Creates a Python virtual run time and its dependencies for you
• Installs the crontab line in the host
• Run it as a Docker container.

Whichever alternative you select, you need to first unpack the integration package shared by our Support team.

Unpack the deployment package provided by Lumu in your preferred path/folder. Keep in mind this location, as it will be required for further configurations. From now on, we will refer to this folder as <app_lumu_root>.

If you use the install script, use the uninstall.sh bash file to remove the integration from the host

Set up the configuration file

To set up the integration, you need to add and edit a configuration file. This file contains all the parameters needed to run properly. The configuration file looks as follows:

Before completing the Map section of the YAML file check the right names of each Status and Transitions on the Jira Project Workflow.

Each project may have differents Status and Transitions one and another, then, each project should have each unique Mapping, unless the projects have the same Workflow

-
  lumu:
    uuid: "<COMPANY-UUID>"
    defender_key: "<DEFENDER-KEY>"
    include_muted_updates: false # Boolean: true | false
  app:
    Priority: "Low" # Highest, High, Medium, Low, Lowest
    Label: "LumuSecOps"
    ProjectName: "<PROJECT-NAME>"
    RequestType: "<REQUEST-TYPE-NAME>"
    Organization: "<PROJECT-ORGANIZATION>" # DisplayName | null
    Assignee: "<ASSIGNEE>" # DisplayName | email Address | null (without quotation)
    Reporter: "<REPORTER>" # DisplayName | email Address | null (without quotation)
    days: 60  # Filters issues by created field during since x days IN JIRA
    Map:
      TransitionInProgress: [ "Approved", "Start", "Reopened", "Back to in progress", "In progress" ]
      TransitionPending: [ "In review", "Pending" ]
      TransitionDone: [ "Resolved", "Resolve this issue", "Close" ]
      Status: [ "To Do", "In Progress", "Pending", "Done", "Resolved", "Closed" ]
      StatusAction:
        { "In Progress": "unmute", "Pending": "mute", "Done": "close", "Resolved": "close",  "Closed": "close" }

    api:
      username: "<EMAIL|USERNAME>"
      password: "<TOKEN>"
      hostname: "<INSTANCE.atlassian.net>"
-
  COMPANY 2
-
  COMPANY 3
-
  ...

Replace the values according to your environment based on the collected data from previous steps, using these indications:

• The values tagged inside angle brackets must be replaced with the values collected in previous steps
• The values in the Map section must be filled out with the status and transitions you want to assign to the Jira SM Request based on your environment configuration.
• The Map.StatusAction maps should match between Jira Request Workflow and Lumu status to not expect weird behavior when the status of the request/incident is updated.

For instance, the above Map Sections on YAML config template were filled out based on the following workflows:

Inside the integration package, you will find a sample configuration file named companies_template.yml. Copy it and work on it accordingly.

For MSP deployments, you can add multiple instances of this configuration block in your configuration file.

Deploy integration as script

To deploy the integration as a script, you need to run the install.sh script inside the integration package.

Make sure the install.sh script has the execution permission before running it.

To run the installation script, go to the app_lumu_root folder, then execute this line through CLI.

The installation script will set up the Python environment and an auxiliary cron job.

It’s not recommended to change the default running interval of the cron job. This helps the integration script to recover from potential failures.

Main Script details

To use the script, you must locate yourself on the path selected for deployment (<app_root_path>). Use the following command to show the help command line.

Usage: jira_lumu.py [options]

The script will run as a daemon process. To keep this integration working, you need to guarantee the script is running all the time.

The integration will run smoothly if the configuration within the YAML configuration file is correct. If the script gives errors, solve them based on the log output.

Usage examples

Task: basic usage or standard usage

Use the following command to listen to Lumu operational events and manage service tickets in your Jira Service Management instance:

The application will run reading the CONFIG file and keep the preceding HOURS tickets/incidents, by default 720 (30 days)

Task: save script log to file

Use the option --logging=file to store a record of all tasks run by the script. Using this, all the script output will be redirected to a file named lumu.log in the folder where you have deployed the script.

Other tasks

The above samples can be combined according to your needs.

Troubleshooting

To identify failures on the script execution, use the -v flag to activate DEBUG logs. 

The application runs one instance at a time. The script will block multiple attempts to run the same integration if one is already running. If this is the case, the following message appears.

If the integration throws errors, these can be found in errors.log file in the app directory.

Run it as a Docker container

The integration can be deployed in a docker environment. To do so, run the following commands located in the integration folder:

1. Build the Docker image

Do not forget the dot "."

2. Create and run the Docker container

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

To collect integration logs:

Expected results

After running the script, the list of the incidents mapping to requests (Jira issue) are in the Queue -> All Open window in the Service Management Project section.

Any updates and status changes will be reflected in the Details and the Comment section of the Request

The integration only will sync new incidents from the moment you activate the integration. Make sure your integration script is running all the time.