---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# StateManagementScriptableApi - Global

# StateManagementScriptableApi - Global {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read

The StateManagementScriptableApi provides a set of methods for manipulating configuration item (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) {#ariaid-title2}

Add a CI action to a list of CIs.
{#SMSA-addBulkCIAction_S_S_S_S_S__table_g5l_w4s_px__entry__3}

| 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 1. Parameters]

{#SMSA-addBulkCIAction_S_S_S_S_S__table_g5l_w4s_px} {#SMSA-addBulkCIAction_S_S_S_S_S__table_h5l_w4s_px__entry__2}

| 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. {#SMSA-addBulkCIAction_S_S_S_S_S__ul_ewf_5vl_px} |
[Table 2. Returns]

{#SMSA-addBulkCIAction_S_S_S_S_S__table_h5l_w4s_px}

## StateManagementScriptableApi - extendCIActionLease( String requestorId, String ciSysId,
String ciActionName, String leaseTime) {#ariaid-title3}

Extend the CI-action-lease time for the registered user. If the previous lease has
expired, the new lease time starts now.
{#SMSA-extendCIActionLease_S_S_S_S__table_f24_j3s_px__entry__3}

| 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 3. Parameters]

{#SMSA-extendCIActionLease_S_S_S_S__table_f24_j3s_px} {#SMSA-extendCIActionLease_S_S_S_S__table_g24_j3s_px__entry__2}

| 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. {#SMSA-extendCIActionLease_S_S_S_S__ul_ewf_5vl_px} |
[Table 4. Returns]

{#SMSA-extendCIActionLease_S_S_S_S__table_g24_j3s_px}

## StateManagementScriptableApi - getCIActions(String ciSysId) {#ariaid-title4}

Returns a list of active CI actions for the specified CI.
{#SMSA-getCIActions_S__table_ql1_fws_px__entry__3}

| Name | Type | Description |
|-|-|-|
| ciSysId | String | Sys_id of the CI. |
[Table 5. Parameters]

{#SMSA-getCIActions_S__table_ql1_fws_px} {#SMSA-getCIActions_S__table_rl1_fws_px__entry__2}

| Type | Description |
|-|-|
| String | A JSON formatted string with name-value pairs. Possible values: * ciActions - Comma-separated list of active CI actions for the CI, or no_active_action. * errors - List of errors. {#SMSA-getCIActions_S__ul_ewf_5vl_px} |
[Table 6. Returns]

{#SMSA-getCIActions_S__table_rl1_fws_px}  
The following example shows how to get active actions for a list of configuration
items.

    // Store sys_ids of configuration items for which to get data
    var CIArray = ["a9c0c8d2c6112276018f7705562f9cb0","0c43bc4fc61122750182c132411702f2","46bbf419a9fe1981009802288c1eb79d","46a4381ca9fe1981005c3e99af3cd164","0c43bcbdc61122750182c132e9b6565d"];

    var output = '';

    // looping above array to fetch each sys_id and passing to method
    for(var i=0; i < CIArray.length; i++) {

      // passing sys_id of CI stored in array to method
      output = SNC.StateManagementScriptableApi.getCIActions(CIArray[i]);

      // print a JSON formatted string with name-value pairs
      gs.print(output);
    }

Output:

    {"ciActions":["no_active_action"],"result":true}
    {"ciActions":["no_active_action"],"result":true}
    {"ciActions":["no_active_action"],"result":true}
    {"ciActions":["no_active_action"],"result":true}
    {"ciActions":["no_active_action"],"result":true}

## StateManagementScriptableApi - getOperationalState(String ciSysId) {#ariaid-title5}

Returns the operational state of the CI.
{#SMSA-getCIOperationalState_S__table_n5f_1ns_px__entry__3}

| Name | Type | Description |
|-|-|-|
| ciSysId | String | Sys_id of the CI. |
[Table 7. Parameters]

{#SMSA-getCIOperationalState_S__table_n5f_1ns_px} {#SMSA-getCIOperationalState_S__table_o5f_1ns_px__entry__2}

| Type | Description |
|-|-|
| String | A JSON formatted string with name-value pairs. Possible values: * ciActions - String choice values of the operational_status field, or UNKNOWN. * errors - List of errors. {#SMSA-getCIOperationalState_S__ul_ewf_5vl_px} |
[Table 8. Returns]

{#SMSA-getCIOperationalState_S__table_o5f_1ns_px}  
The following example shows how to get the operational states of a list of specified
configuration items.

    // Store sys_ids of configuration items for which to get the operational state.
    var CIArray = ["0c43bc4fc61122750182c132411702f2","46bbf419a9fe1981009802288c1eb79d","46a4381ca9fe1981005c3e99af3cd164","0c43bcbdc61122750182c132e9b6565d","a9c0c8d2c6112276018f7705562f9cb0"];

    var output = '';

    // Loop the array to fetch each sys_id and pass to the method.
    for(var i=0;i<CIArray.length;i++) {
      // Pass sys_id of CI stored in array to the method  
      output = SNC.StateManagementScriptableApi.getOperationalState(CIArray[i]); 

      // prints a JSON formatted string with name-value pairs
      gs.print(output);
    }

Output:

    *** Script: {"operationalState":"Operational","result":true}
    *** Script: {"operationalState":"Operational","result":true}
    *** Script: {"operationalState":"Operational","result":true}
    *** Script: {"operationalState":"Operational","result":true}
    ci_state_management                        : INVALID_SYS_ID: Invalid sys_id [a9c0c8d2c6112276018f7705562f9cb0]: no thrown error
    *** Script: {"errors":[{"error":"INVALID_SYS_ID","message":"Invalid sys_id [a9c0c8d2c6112276018f7705562f9cb0]"}],"operationalState":"unknown","result":false}

## StateManagementScriptableApi - isCompatibleCIAction(String actionName, String
otherActionName) {#ariaid-title6}

Determines if the two specified actions are compatible.
{#SMSA-isCompatibleCIAction_S_S__table_fkl_v1t_px__entry__3}

| Name | Type | Description |
|-|-|-|
| actionName | String | A CI action name |
| otherActionName | String | A CI action name |
[Table 9. Parameters]

{#SMSA-isCompatibleCIAction_S_S__table_fkl_v1t_px} {#SMSA-isCompatibleCIAction_S_S__table_gkl_v1t_px__entry__2}

| Type | Description |
|-|-|
| Boolean | Returns true if the two specified CI actions are compatible. |
[Table 10. Returns]

{#SMSA-isCompatibleCIAction_S_S__table_gkl_v1t_px}

## StateManagementScriptableApi - isLeaseExpired(String requestorId, String ciSysId, String
ciActionName) {#ariaid-title7}

Determines if the lease has expired for the requestor of a specified CI
Action.
{#SMSA-isLeaseExpired_S_S_S__table_ot5_v5r_px__entry__3}

| 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 11. Parameters]

{#SMSA-isLeaseExpired_S_S_S__table_ot5_v5r_px} {#SMSA-isLeaseExpired_S_S_S__table_pt5_v5r_px__entry__2}

| 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. {#SMSA-isLeaseExpired_S_S_S__ul_ewf_5vl_px} |
[Table 12. Returns]

{#SMSA-isLeaseExpired_S_S_S__table_pt5_v5r_px}

## StateManagementScriptableApi - isNotAllowedAction(String ciType, String opsLabel, String
actionName) {#ariaid-title8}

For a type of CI, determine if a CI action is not allowed for an operational
state.
{#SMSA-isNotAllowedAction_S_S_S__table_lzz_cxs_px__entry__3}

| Name | Type | Description |
|-|-|-|
| ciType | String | The CI type |
| opsLabel | String | The operational state |
| actionName | String | The CI action name |
[Table 13. Parameters]

{#SMSA-isNotAllowedAction_S_S_S__table_lzz_cxs_px} {#SMSA-isNotAllowedAction_S_S_S__table_mzz_cxs_px__entry__2}

| Type | Description |
|-|-|
| Boolean | Returns true if the action is not allowed on the specified CI type in the specified operational state. |
[Table 14. Returns]

{#SMSA-isNotAllowedAction_S_S_S__table_mzz_cxs_px}

## StateManagementScriptableApi - isNotAllowedOpsTransition(String ciType, String opsLabel,
String transitionOpsLabel) {#ariaid-title9}

For a type of CI, determine if an operational state transition is not
allowed.
{#SMSA-isNotAllowedOpsTransition_S_S_S__table_erm_mys_px__entry__3}

| 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 15. Parameters]

{#SMSA-isNotAllowedOpsTransition_S_S_S__table_erm_mys_px} {#SMSA-isNotAllowedOpsTransition_S_S_S__table_frm_mys_px__entry__2}

| Type | Description |
|-|-|
| Boolean | Returns true if specified operational state transition is not allowed on the specified CI type. |
[Table 16. Returns]

{#SMSA-isNotAllowedOpsTransition_S_S_S__table_frm_mys_px}

## StateManagementScriptableApi - isValidRequestor(String requestorId) {#ariaid-title10}

Determines if the specified requestor is a valid active workflow user or a registered
user.
{#SMSA-isValidRequestor_S__table_dr5_5sr_px__entry__3}

| Name | Type | Description |
|-|-|-|
| requestorId | String | Sys_id of a workflow context or the GUID returned from the registerOperator() method. |
[Table 17. Parameters]

{#SMSA-isValidRequestor_S__table_dr5_5sr_px} {#SMSA-isValidRequestor_S__table_er5_5sr_px__entry__2}

| Type | Description |
|-|-|
| String | JSON formatted name-value pairs. Possible values: * result - true if the requestorId is valid. * errors - list of errors. |
[Table 18. Returns]

{#SMSA-isValidRequestor_S__table_er5_5sr_px}  
This example show how to use the isValidRequestor() method to check if
an operator is a registered user.

    var output = SNC.StateManagementScriptableApi.registerOperator();
    var jsonUtil = new JSON();
    var result = jsonUtil.decode(output);
    var requestorId = result.requestorId; // Fetching requestorId

    output = SNC.StateManagementScriptableApi.isValidRequestor(requestorId);
    gs.info(output);

Output:

    {"result":true}

## StateManagementScriptableApi - registerOperator() {#ariaid-title11}

Registers an operator for a non-workflow user.
{#SMSA-registerOperator__table_l5c_hvl_px__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 19. Parameters]

{#SMSA-registerOperator__table_l5c_hvl_px} {#SMSA-registerOperator__table_m5c_hvl_px__entry__2}

| 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. {#SMSA-registerOperator__ul_ewf_5vl_px} |
[Table 20. Returns]

{#SMSA-registerOperator__table_m5c_hvl_px}  


    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) {#ariaid-title12}

Removes a CI action for a list of CIs.
{#SMSA-removeBulkCIAction_S_S_S__table_iz1_2vs_px__entry__3}

| 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 21. Parameters]

{#SMSA-removeBulkCIAction_S_S_S__table_iz1_2vs_px} {#SMSA-removeBulkCIAction_S_S_S__table_jz1_2vs_px__entry__2}

| 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. {#SMSA-removeBulkCIAction_S_S_S__ul_ewf_5vl_px} |
[Table 22. Returns]

{#SMSA-removeBulkCIAction_S_S_S__table_jz1_2vs_px}

## StateManagementScriptableApi - setBulkCIOperationalState(String requestorId, String
sysIdList, String opsLabel, String opsStateListOld) {#ariaid-title13}

Set the operational state for list of CIs.
{#SMSA-setBulkCIOpState_S_S_S_S__table_hgf_5ks_px__entry__3}

| 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 23. Parameters]

{#SMSA-setBulkCIOpState_S_S_S_S__table_hgf_5ks_px} {#SMSA-setBulkCIOpState_S_S_S_S__table_igf_5ks_px__entry__2}

| 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. {#SMSA-setBulkCIOpState_S_S_S_S__ul_ewf_5vl_px} |
[Table 24. Returns]

{#SMSA-setBulkCIOpState_S_S_S_S__table_igf_5ks_px}  

    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) {#ariaid-title14}

Unregisters an operator for non-workflow users.
{#SMSA-unregisterOperator_S__table_pwv_2xl_px__entry__3}

| Name | Type | Description |
|-|-|-|
| requestorId | String | Sys_id of a workflow context or the GUID returned from the registerOperator() method. |
[Table 25. Parameters]

{#SMSA-unregisterOperator_S__table_pwv_2xl_px} {#SMSA-unregisterOperator_S__table_qwv_2xl_px__entry__2}

| Type | Description |
|-|-|
| String | JSON formatted name-value pairs. Possible values: * result - true if successfully unregistered * errors - list of errors. |
[Table 26. Returns]

{#SMSA-unregisterOperator_S__table_qwv_2xl_px}  
This example show how to use the unregisterOperator() method to
unregister a registered user.

    var output = SNC.StateManagementScriptableApi.registerOperator();
    var jsonUtil = new JSON();
    var result = jsonUtil.decode(output);
    var requestorId = result.requestorId; // Fetching requestorId

    output = SNC.StateManagementScriptableApi.unregisterOperator(requestorId);
    gs.info(output); 

Output:

    {"result":true}