{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":710,"path":"api-reference/server-api-reference/CIActionScopedAPI.md","title":"CIActionEngine - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# CIActionEngine- Scoped\n\nThe 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.\n\nThe 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.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## CIActionEngine - execute\\(\\)\n\nExecutes any action on a CI with the configured action parameters.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\naction\n\n\n\nString or Glide Record\n\n\n\nSys\\_id or GlideRecord of the Action \\[sn\\_cimaf\\_action\\] table.\n\n
\n\nci\n\n\n\nString or Glide Record\n\n\n\nSys\\_id or GlideRecord of the CMDB \\[cmdb\\_ci\\] table on which the Action needs to be executed\n\n
\n\nactionParams\n\n\n\nObject\n\n\n\nOptional. Map of Action parameter names and values.\n\n ```\n{\n “”: \n}\n```\n\n **Note:** Parameter values should be of the type defined in the Action parameter \\[sn\\_cimaf\\_action\\_parameter\\] table.\n\n
|Type|Description|\n|----|-----------|\n|String|Sys\\_id of the new or existing duplicate in-progress Action Request.|\n\nThe following example shows how to kill a process on a CI.\n\n```\nvar actionSysId = \"6303db0d53b99910ae50ddeeff7b121e\";\t \n//Sys_id of the Action – End Process \nvar ciSysId = \"b4fd7c8437201000deeabfc8bcbe5dc1\"; //Sys_id of the CI \nvar actionParams = { \n process_id: 23342 //Process id of the process to be killed \n}; \n \nvar ciActionEngine = new sn_cimaf.CIActionEngine(); \nvar actionRequestId = ciActionEngine.execute(actionSysId, ciSysId, actionParams); \n \ngs.info(\"Action Request Id: \" + actionRequestId);\n```\n\nOutput:\n\n```\nAction Request Id: e34e3a199d16a510f877a45cc5e8a492\n```\n\n## CIActionEngine - getActionRequestOutput\\(\\)\n\nGets the status and action outputs of an action execution request.\n\n|Name|Type|Description|\n|----|----|-----------|\n|actionRequest|Glide Record|GlideRecord of the Action Request \\[sn\\_cimaf\\_action\\_request\\] table.|\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nObject contains the status and list of the action outputs of the provided action request.```\n{ \n “sys_id”: “String”, \n “state”: “String”, //Possible values: completed, in_progress, failed \n “sn_cimaf_action_output”: [ \n { \n “sys_id”: “String”, \n “action_command”: “String”, //Sys_id of the Action Configuration Step table \n “payload”: “String”, \n “state”: “String”, //Possible values: completed, in_progress, failed, validation_failure \n “request_id”: “String” //Unique id returned by Provider on executing action_command \n } \n ] \n} \n```\n\n
The following example shows how to get status and action outputs for any action request.\n\n```\nvar actionRequestGr = new GlideRecord('sn_cimaf_action_request'); \nactionRequestGr.get('e34e3a199d16a510f877a45cc5e8a492'); \n \nvar ciActionEngine = new sn_cimaf.CIActionEngine(); \nvar actionRequestOutput = ciActionEngine.getActionRequestOutput(actionRequestGr); \ngs.info(\"Action Request Output: \" + JSON.stringify(actionRequestOutput, null, 2));\n```\n\nOutput:\n\n```\n{\n \"sys_id\": \"e34e3a199d16a510f877a45cc5e8a492\",\n \"state\": \"completed\",\n \"sn_cimaf_action_output\": [\n {\n \"sys_id\": \"405ef2599d16a510f877a45cc5e8a41e\",\n \"action_command\": \"b0e43efb53259510ae50ddeeff7b129b\",\n \"payload\": \"{\\\"output\\\":\\\"SUCCESS: The process with PID 23342 has been terminated.\\\\r\\\\n\\\",\\\"cmd\\\":\\\"taskkill /pid 23342 /f\\\"}\",\n \"state\": \"completed\",\n \"request_id\": \"cc5ef2599d16a510f877a45cc5e8a41d\"\n }\n ]\n}\n```\n\n## CIActionEngine - isAuthorized\\(\\)\n\nChecks the authorization of the signed-in user before they can execute an action according to specified configurations.\n\nThe 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.\n\n**Note:** By default, if there is no configuration present in any of these tables for the Action, the authorization fails.\n\n|Name|Type|Description|\n|----|----|-----------|\n|action|Glide Record|GlideRecord of the Action \\[sn\\_cimaf\\_action\\] table.|\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nBoolean\n\n\n\nFlag that indicates the success of the user's authorization.\n\n Valid values:\n\n- true: User is authorized to execute the action.\n- false: User is authorized to execute the action.\n\n
The following example uses the isAuthorized\\(\\) method to check a user's authorization to execute any action on a CI.\n\n```\nvar actionSysId = \"6303db0d53b99910ae50ddeeff7b121e\" //Sys_id of the Action \nvar actionGr = new GlideRecord('sn_cimaf_action'); \nactionGr.get('6303db0d53b99910ae50ddeeff7b121e'); \n \nvar ciActionEngine = new sn_cimaf.CIActionEngine(); \nvar isAuthorized = ciActionEngine.isAuthorized(actionGr); \ngs.info(\"Is user authorized: \" + isAuthorized);\n```\n\n```\nIs user authorized: true\n```\n\n"}}