StateManagementScriptableApi - Global

Provides a set of methods for manipulating CI operational states and applying CI actions.

The StateManagementScriptableApi methods adhere to restrictions and allowances specified by not allowed CI actions, compatible CI actions, and not allowed operational transitions. If a method attempts to perform a restricted operation, the operation is blocked, an error is logged, and a task is created if appropriate.

The StateManagementScriptableApi methods are static methods. You access the methods using the SNC.StateManagementScriptableApi global object.

StateManagementScriptableApi - addBulkCIAction(String requestorId, String sysIdList, String ciActionName, String ciActionListOld, String leaseTime)

Add a CI action to a list of CIs.

Table 1. Parameters
Name Type Description
requestorId String A sys_id of a workflow context, or the GUID returned from the registerOperator() method.
sysIdList String A list comma separated list of CI sys_ids.
ciActionName String The CI action name.
ciActionListOld String (Optional) A comma separated list of old CI actions that all CIs should be in.
leaseTime String (Optional) Time duration for which the lease is valid for specified CI Action. In the format HH:MM:SS.
Table 2. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • result - true if the action is set for all CIs in the list; otherwise, false.
  • errors - list of errors.

StateManagementScriptableApi - extendCIActionLease( String requestorId, String ciSysId, String ciActionName, String leaseTime)

Extend the CI-action-lease time for the registered user. If the previous lease has expired, the new lease time starts now.

Table 3. Parameters
Name Type Description
requestorId String A sys_id of a workflow context, or the GUID returned from the registerOperator() method.
ciSysId String The CI's sys_id.
ciActionName String The CI action name.
leaseTime String Time duration for which the lease is valid for specified CI Action. In the format HH:MM:SS.
Table 4. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • result - true if the lease time has been set.
  • errors - list of errors.

StateManagementScriptableApi - getCIActions(String ciSysId)

Returns a list of active CI actions for the specified CI.

Table 5. Parameters
Name Type Description
ciSysId String The sys_id of the CI
Table 6. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • ciActions - a comma separated list of active CI actions for the CI, or NO_ACTIVE_ACTION.
  • errors - list of errors.

StateManagementScriptableApi - getOperationalState(String ciSysId)

Returns the CI's operational state.

Table 7. Parameters
Name Type Description
ciSysId String Sys_id of the CI
Table 8. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • operationalStates - one of the string choice values of the operational_status field, or UNKNOWN.
  • errors - list of errors.

StateManagementScriptableApi - isCompatibleCIAction(String actionName, String otherActionName)

Determines if the two specified actions are compatible.

Table 9. Parameters
Name Type Description
actionName String A CI action name
otherActionName String A CI action name
Table 10. Returns
Type Description
Boolean Returns true if the two specified CI actions are compatible.

StateManagementScriptableApi - isLeaseExpired(String requestorId, String ciSysId, String ciActionName)

Determines if the lease has expired for the requestor of a specified CI Action.

Table 11. Parameters
Name Type Description
requestorId String A sys_id of a workflow context, or the GUID returned from the registerOperator() method.
ciSysId String The CI's sys_id.
ciActionName String Name of the CI action.
Table 12. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • result - true if the user's lease has expired.
  • errors - list of errors.

StateManagementScriptableApi - isNotAllowedAction(String ciType, String opsLabel, String actionName)

For a type of CI, determine if a CI action is not allowed for an operational state.

Table 13. Parameters
Name Type Description
ciType String The CI type
opsLabel String The operational state
actionName String The CI action name
Table 14. Returns
Type Description
Boolean Returns true if the action is not allowed on the specified CI type in the specified operational state.

StateManagementScriptableApi - isNotAllowedOpsTransition(String ciType, String opsLabel, String transitionOpsLabel)

For a type of CI, determine if an operational state transition is not allowed.

Table 15. Parameters
Name Type Description
ciType String The CI type
opsLabel String The label of the beginning operational state.
transitionOpsLabel String The label of the ending operational state.
Table 16. Returns
Type Description
Boolean Returns true if specified operational state transition is not allowed on the specified CI type.

StateManagementScriptableApi - isValidRequestor(String requestorId)

Determine if the specified requestor is a valid active workflow user or a registered user.

Table 17. Parameters
Name Type Description
requestorId String A sys_id of a workflow context, or the GUID returned from the registerOperator() method.
Table 18. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • result - true if the requestorId is valid.
  • errors - list of errors.

StateManagementScriptableApi - registerOperator()

Register an operator for a non-workflow user.

Table 19. Parameters
Name Type Description
None
Table 20. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • requestorid - Registered user GUID that is used to set CI Action/operational states.
  • result - true if successfully registered.
  • errors - list of errors.
var output = SNC.StateManagementScriptableApi.registerOperator();
var jsonUntil = new JSON();
var result = jsonUntil.decode(output);
var requestorId = result.requestorId;

StateManagementScriptableApi - removeBulkCIAction(String requestorId, String sysIdList, String ciActionName)

Removes a CI action for a list of CIs.

Table 21. Parameters
Name Type Description
requestorId String A sys_id of a workflow context, or the GUID returned from the registerOperator() method.
sysIdList String A comma separated list of CI sys_ids
ciActionName String The CI action name
Table 22. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • result - true if the action is removed for all CIs in the list; otherwise, false.
  • errors - list of errors.

StateManagementScriptableApi - setBulkCIOperationalState(String requestorId, String sysIdList, String opsLabel, String opsStateListOld)

Set the operational state for list of CIs.

Table 23. Parameters
Name Type Description
requestorId String A sys_id of a workflow context, or the GUID returned from the registerOperator() method.
sysIdList String A comma separated list of CI sys_ids.
opsLabel String This is the string label of an operational_status choice.
opsStateListOld String (Optional) A comma separated list of old CI states that all CIs should be in.
Table 24. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • result - true if the state is set for all CIs in the list; otherwise, false.
  • errors - list of errors.
var output = SNC.StateManagementScriptableApi.registerOperator();
var jsonUntil = new JSON();
var result = jsonUtil.decode(output);
var requestorId = result.requestorId;

// list of sys_ids to update
var sys_ids;

// Set list of sys_ids's Operational State to 'Repair in Progress'
output = SNC.StateManagementScriptableApi.setBulkCIOperationalState(requestorId, sys_ids,'Repair in Progress');
gs.print(output);

StateManagementScriptableApi - unregisterOperator( String requestorId)

Unregister an operator for non-workflow users.

Table 25. Parameters
Name Type Description
requestorId String A sys_id of a workflow context, or the GUID returned from the registerOperator() method.
Table 26. Returns
Type Description
String A JSON formatted string with name-value pairs for
  • result - true if successfully unregistered.
  • errors - list of errors.