Long Running Containers

You can use long running containers to run specific processes in an integration forever.

Getting Started#

Prerequisites#

Demisto v5.0 or later.
The integration must be written in Python.

Enable the longRunning property#

To make an integration long running, you need to enable the longRunning property:

You will then have the Long running instance parameter:

If you check the checkbox, the server will launch a long running container each time an instance is enabled. When the checkbox is unchecked or the instance is disabled, the container will die. You can distinguish it from the rest of the containers by its name:

Implementation#

When the container runs, it calls a dedicated command in the integration, much like fetch-incidents. The command is called long-running-execution You'll have to implement it in your integration code. In order to run this code forever, you will need it to never stop executing, for example - a never ending loop (while True).

Interaction with the server#

Since the long running container does not run in a scope of an incident, it has no standard place to output results into. For that we have dedicated functions to interact with the server:

addEntry - Adds an entry to a specified incident War Room. For more details, see the API reference.
createIncidents - Creates incidents according to a provided JSON. For more details, see the API reference.
findUser - Find a Cortex XSOAR user by a name or email. Useful for creating incidents. For more details, see the API reference.
handleEntitlementForUser - Adds an entry with entitlement to a provided investigation. For more details, see the API reference.
updateModuleHealth - Update the instance status. It's a way to reflect the container state to the user. For more details, see the API reference.
mirrorInvestigation - For chat based integrations, mirror a provided Cortex XSOAR investigation to the corresponding chat module.
directMessage - For chat based integrations, handle free text sent from a user to the chat module and process it in the server.

Manage container states#

One of the most important and useful aspects of the long running process is the integration context: demisto.setIntegrationContext(context) demisto.getIntegrationContext() Use the integration context to store information and manage the state of the container per integration instance. This context is stored in a format of a dict of {'key': 'value'}, where value must be a string. To store complex objects as values, parse them to JSON.

Use logging to notify and report different states inside the long running process - demisto.info(str) and demisto.error(str). These will show up in the server log.

Troubleshooting#

Use updateModuleHealth, info and error to report errors and debug. It's also important to segregate the logic into functions so you'll be able to unit test them.

Best practices#

It's important to maintain a never ending process in the container. That means:

Never use sys.exit() (return_error and friends).
Always catch exceptions and log them.
Run in a never ending loop.

To run multiple processes in parallel, you can use async code. For an example you can check out the Slack v2 or Microsoft Teams integrations.

Invoking HTTP Integrations via Cortex XSOAR Server's route handling#

For more details, see the following article: Invoking Long Running HTTP Integrations via Server's HTTPS endpoint.