Creating an Active Action Script

General Rules

Active action scripts are universal for both incidents and aggregations. They can be used for single manual execution as well as during status transitions in Workflow as pre-actions and post-actions.

You can create an Active Action script in two programming languages: JavaScript (NodeJS) and Python. To do this, you need to create a script file in the saf-incident-manager/common/actions or $OSD_HOME/config/actions folder.

danger

If scripts are created in $OSD_HOME/config/actions, they will be saved during plugin updates; otherwise, they will be lost during updates.

All scripts must have unique names; otherwise, the desired script may be recognized incorrectly.

Regardless of the chosen language, the following data will be passed to the script when executing an action for an incident:

{
  "currentUser": {
    "backend_roles": [
      // backend roles of the current user
    ],
    "roles": [
      // roles of the current user
    ]
  },
  "incidentId": "zGQt4o8BqXcWBDa4I1DFGDH5", // Incident ID
  "index": ".incident-index-2023.21", // Index where the incident is stored
  "log": "", // Incident logs
  "metadata": {
    "incidentId": "zGQt4o8BqXcWBDa4I1DFGDH5", // Incident ID
    "incidentTitle": "Exchange: anti-spam allowed an email", // Incident name
    "incidentDescription": "Anti-spam allowed an email", // Incident description
    "index": ".sm_incident-2024.23",
    "urlToIncident": "https://safhost.com/incident-manager/...", // Incident URL
    "baseFields": {
      // Basic incident fields set during configuration
    },
    "additionalFields": {
      // Additional incident fields set during configuration, as well as additional fields from the incident itself
    }
  },
  "sideEffects": {},
  "target": "manual", // manual - flag indicating that an active action or new Workflow status is being used
  "workflowId": "my-workflow" // Workflow ID of the incident
}

When executing an active action script for an aggregation, the following parameters will be passed:

{
  "currentUser": {
    "backend_roles": [
      // backend roles of the current user
    ],
    "roles": [
      // roles of the current user
    ]
  },
  "aggregationId": "zGQt4o8BqXcWBDa4I1DFGDH5", // Aggregation ID
  "index": ".incident_of_aggregation_results", // Index where the aggregation is stored
  "log": "",
  "metadata": {
    "aggregationId": "zGQt4o8BqXcWBDa4I1DFGDH5", // Aggregation ID
    "aggregationTitle": "Exchange: anti-spam allowed an emails", // Aggregation name
    "aggregationDescription": "Exchange: anti-spam allowed archive emails", // Aggregation description
    "index": ".incident_of_aggregation_results", // Index where the aggregation is stored
    "urlToAggregation": "https://safhost.com//incident-manager/aggregations-result...", // Aggregation URL
    "baseFields": {
      // Basic aggregation fields set during configuration
    },
    "additionalFields": {
      // Additional aggregation fields set during configuration, as well as comparison fields from the aggregation itself
    }
  },
  "sideEffects": {},
  "target": "manual" // manual - flag indicating that an active action or new Workflow status is being used
}

Note!

Scripts invoked with target "manual" cannot modify the incident or aggregation itself. If you want to perform an action that modifies the aggregation or incident, execute this action as a pre-action in Workflow during the transition to a new status.

Using JavaScript

When creating an active action in JavaScript, you can follow this function template:

/** ! Function for executing active actions
 * @param doc - JSON with active actions
 * @param metadata - metadata of the passed entity (aggregation or incident)
 * @param entities - list of passed incidents (used during bulk editing of Workflow status)
 * @param currentUser - current user
 * @param logger - logging function
 */
export default async (doc, metadata, entities, currentUser, logger) => {
  // function body
};

Parameters are passed directly to the function by calling it during execution. The function should be asynchronous to ensure it executes correctly and completes as planned.

Using Python

When creating an active action in Python, you can use the following template:

import json

class Object:
    # Helper function to convert an object to JSON
    def toJSON(self):
        return json.dumps(self, default=lambda o: o.__dict__, sort_keys=True, indent=1)

""" Function for executing active actions
@param: doc - entity (aggregation or incident),
@param: metadata  - metadata of the passed entity (aggregation or incident)
@param: entities - list of passed incidents (used during bulk editing of Workflow status)
@param: currentUser - current user
"""

def my_func(doc, metadata, entities, currentUser):
    # function code
    print(output.toJSON())  # Output doc data

if __name__ == "__main__":
    _json = input()  # Data is read from the stream via stdin
    res = json.loads(_json)
    my_func(
        doc=res.get("doc"),
        metadata=res.get("metadata"),
        entities=res.get("entities"),
        currentUser=res.get("currentUser"),
    )

Parameters for the active action in Python are passed through the console input stream (stdin). Output parameters, such as the modified incident or aggregation entity (doc), should be passed through the output stream (stdout). This example is not definitive, and you can use any methods and functions that are convenient.