The CIActionEngine API provides methods that enable you to execute any action on a configuration item (CI), to check the authorization of a user before executing an action, and to get the status and action outputs of any action execution request.

The CI action is associated with the Metrics and CI Actions Framework application. To use this class in a scoped application, use the sn_cimaf namespace identifier. The CIActionEngine API requires the Metrics and CI Actions Framework (com.snc.sn_cimaf) plugin and is provided within the sn_cimaf namespace.

CIActionEngine - execute()

Executes any action on a CI with the configured action parameters.

Table 1. Parameters
Name Type Description
action String or Glide Record Sys_id or GlideRecord of the Action [sn_cimaf_action] table.
ci String or Glide Record Sys_id or GlideRecord of the CMDB [cmdb_ci] table on which the Action needs to be executed
actionParams Object

Optional. Map of Action parameter names and values.

{
 “<parameter name>”: <parameter value>
}
Note: Parameter values should be of the type defined in the Action parameter [sn_cimaf_action_parameter] table.
Table 2. Returns
Type Description
String Sys_id of the new or existing duplicate in-progress Action Request.

Example

The following example shows how to kill a process on a CI.

var actionSysId = "6303db0d53b99910ae50ddeeff7b121e";	 
//Sys_id of the Action – End Process 
var ciSysId = "b4fd7c8437201000deeabfc8bcbe5dc1"; //Sys_id of the CI 
var actionParams = { 
    process_id: 23342 //Process id of the process to be killed 
}; 
 
var ciActionEngine = new sn_cimaf.CIActionEngine(); 
var actionRequestId = ciActionEngine.execute(actionSysId, ciSysId, actionParams); 
 
gs.info("Action Request Id: " + actionRequestId);

Output:

Action Request Id: e34e3a199d16a510f877a45cc5e8a492

CIActionEngine - getActionRequestOutput()

Gets the status and action outputs of an action execution request.

Table 3. Parameters
Name Type Description
actionRequest Glide Record GlideRecord of the Action Request [sn_cimaf_action_request] table.
Table 4. Returns
Type Description
Object Object contains the status and list of the action outputs of the provided action request.
{ 
    “sys_id”: “String”, 
    “state”: “String”, //Possible values: completed, in_progress, failed 
    “sn_cimaf_action_output”: [ 
          { 
                “sys_id”: “String”, 
                “action_command”: “String”, //Sys_id of the Action Configuration Step table 
                “payload”: “String”, 
                “state”: “String”, //Possible values: completed, in_progress, failed, validation_failure 
                “request_id”: “String” //Unique id returned by Provider on executing action_command 
          } 
      ] 
}

Example

The following example shows how to get status and action outputs for any action request.

var actionRequestGr = new GlideRecord('sn_cimaf_action_request'); 
actionRequestGr.get('e34e3a199d16a510f877a45cc5e8a492'); 
 
var ciActionEngine = new sn_cimaf.CIActionEngine(); 
var actionRequestOutput = ciActionEngine.getActionRequestOutput(actionRequestGr); 
gs.info("Action Request Output: " + JSON.stringify(actionRequestOutput, null, 2));

Output:

{
  "sys_id": "e34e3a199d16a510f877a45cc5e8a492",
  "state": "completed",
  "sn_cimaf_action_output": [
    {
      "sys_id": "405ef2599d16a510f877a45cc5e8a41e",
      "action_command": "b0e43efb53259510ae50ddeeff7b129b",
      "payload": "{\"output\":\"SUCCESS: The process with PID 23342 has been terminated.\\r\\n\",\"cmd\":\"taskkill /pid 23342 /f\"}",
      "state": "completed",
      "request_id": "cc5ef2599d16a510f877a45cc5e8a41d"
    }
  ]
}

CIActionEngine - isAuthorized()

Checks the authorization of the signed-in user before they can execute an action according to specified configurations.

The configurations are defined in the Action Role [sn_cimaf_action_role], User Criteria Action Inclusion [sn_cimaf_action_user_criteria_mtom], and User Criteria Action Exclusion [sn_cimaf_action_user_criteria_no_mtom] tables.

Note: By default, if there is no configuration present in any of these tables for the Action, the authorization fails.
Table 5. Parameters
Name Type Description
action Glide Record GlideRecord of the Action [sn_cimaf_action] table.
Table 6. Returns
Type Description
Boolean

Flag that indicates the success of the user's authorization.

Valid values:
  • true: User is authorized to execute the action.
  • false: User is authorized to execute the action.

Example

The following example uses the isAuthorized() method to check a user's authorization to execute any action on a CI.

var actionSysId = "6303db0d53b99910ae50ddeeff7b121e" //Sys_id of the Action 
var actionGr = new GlideRecord('sn_cimaf_action'); 
actionGr.get('6303db0d53b99910ae50ddeeff7b121e'); 
 
var ciActionEngine = new sn_cimaf.CIActionEngine(); 
var isAuthorized = ciActionEngine.isAuthorized(actionGr); 
gs.info("Is user authorized: " + isAuthorized);
Is user authorized: true