This article shows how to leverage HaloPSA API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into a HaloPSA deployment as Tickets, and syncing both systems.

Requirements

• A HaloPSA 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 HaloPSA. 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 traffic to the following hosts. These are required for the operation of this integration:

• <INSTANCE>.halopsa.com
• defender.lumu.io

HaloPSA gives you a subdomain within halopsa.com, save it for the integration configuration file

Prepare HaloPSA for Lumu integration

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

Identify your Halo PSA instance

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

Create an API Account

To create an API account, log in to your HaloPSA console. Go to Configuration > Integrations > HaloPSA API

From the API Details window, save the Tenant name, it will be used for the integration.

Now, click on the View Applications button. Click on the New button to add an application. Fill in the requested information following these directions:

• Give your application a distinctive name
• Select Client ID and Secret (Services) as the Authentication Method.
• Copy the Client ID and Client Secret values.
• Select Agent from the Login Type drop-down list fields. Choose the agent associated with the API client.
• On the Permissions tab, check read:customers, read:tickets, and edit:tickets.
• Save your application.

Remember to copy the Client ID and the Client Secret. These will be required later.

Select the ticket type for Lumu incidents

All HaloPSA tickets must belong to a ticket type. A ticket type is a template that defines all the fields, values, and rules needed for your operation. To select the ticket type to be assigned to Lumu-related tickets, use your HaloPSA console and go to Configuration > Tickets > Ticket Types option.

We strongly recommend you use the default  Incident ticket type from HaloPSA. You can use a different one or create one according to your operation needs.

If you decide to create a custom ticket type for Lumu-related incidents, identify all the required fields and check the next steps accordingly.

Identify the ticket statuses to match Lumu states

To achieve a bi-directional integration, you need to identify which ticket statuses will match with Lumu incidents’ states. Based on your previous selection of the ticket type, using your HaloPSA console, go to the Configuration > Tickets > Ticket Statuses option. In this section are listed the status names that a ticket can have.

Check the status names and verify they match in the Map key of the YAML configuration file companies.template.yml in the integration package. Normally, you don’t have to modify the mapping in the YAML file, if the mapping does not match just change it for the right names in the YAML according to the identified states.

Example of the YAML config File Map Key:

Map:
        StatusAction:
          "In Progress": "unmute"
          "Approved": "unmute"
          "Awaiting Approval": "mute"
          "On Hold": "mute"
          "Closed": "close"
        StatusEvent:
          IncidentClosed: "Closed"
          IncidentMuted: "On Hold"
          IncidentUnmuted: "In Progress"

The StatusAction group maps HaloPSA statuses with Lumu incident states. If you need to make changes, modify the key with the name of HaloPSA ticket status that will match with Lumu incident state. The StatusEvent group maps Lumu incident states with specific HaloPSA ticket status. If you need to make changes, modify the values of its keys accordingly.

In the StatusAction map, you need to define at least one record per Lumu status (unmute, mute, closed). In the StatusEvent map, you need at least one record for IncidentClosed, IncidentMuted, and IncidentUnmuted. The integration will crash if you don’t follow these rules.

Identify the Organization

Check if you need to associate an Organization to the integration tickets. To collect its exact name, use your HaloPSA console and go to Configuration > Organization. Copy the exact name and save it for later use.

Identify the Client

Besides the HaloPSA organization, check if you need to identify the client associated with it. To identify and collect the client’s name, use your HaloPSA console and go to the Customer > Clients section. Identify and collect the name of the client you want to associate Lumu incidents.

HaloPSA uses the words Client or Customer. Have this in mind when you are selecting the Client/Customer.

Identify the Client’s Site

For HaloPSA, a Client can have operation in one or multiple sites. If you need to associate the ticket created by the integration with a specific site, you need to identify and select the site under the client configuration. To identify the site, use your HaloPSA console and go to the Customer > Sites section. Identify and collect the name of the client’s site you want to associate Lumu incidents.

Define the ticket reporting user

If you need, you can define the user who will be used as the reporter of the ticket. To identify the user you want to use, use your HaloPSA console and go to the Customer > Users section. Identify and collect the name of the user you want to use as the reporter of the ticket.

Collect complementary information

The integration requires this complementary information:

• Priority
• Category
• Urgency
• Impact

Define the ticket priority

Priority is bound to an SLA, and the SLA is bound to the Ticket type, then a ticket has to have a priority associated. If you need to add priority to the Lumu-related tickets, first identify the SLA applicable to the HaloPSA ticket type, then check the priorities available for the SLA.

Define the Category

You need to select a Category for Lumu-related tickets. To do so:

Take note of the selected category name. This value will be required to configure the integration.

Define the Urgency

You need to select an Urgency for Lumu-related tickets. To do so, check the Urgency levels available in your environment. To check the urgency levels, go to the Configuration > Advanced Settings option. There, look for and click on the Lookup Codes button. Select Urgency Level from the drop-down list.

Take note of the selected urgency level. This value will be required to configure the integration.

Define the Impact

You need to select an impact for Lumu-related tickets. To do so, check the Impact levels available in your environment. To check the impact levels, go to the Configuration > Advanced Settings option. There, look for and click on the Lookup Codes button. Select Impact Level from the drop-down list.

Take note of the selected impact level. This value will be required to configure the integration.

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 in the web console, in case the status name has changed, then update the YAML fields and values related.

• 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 you want to assign to the HaloPSA Service Desk based on your environment configuration, if the status name remains stale do not change the default mapping of Map Field.
• The Map.StatusAction and Map.StatusEvent maps must match between HaloPSA and Lumu status

Inside the integration package, you will find a sample configuration file named companies_template.yml. Copy it and modify it based on your deployment.

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.

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: halopsa_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 HaloPSA 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, you will see the Lumu-related tickets (incidents) in the Service Desk > Tickets section. Select a view to filter the tickets if needed.

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

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