Add a state to the state model

You can add a new state to the existing state model for different change types based on the requirements of your organization.

Before you begin

Role required: script_include_admin, ui_policy_admin, ui_action_admin, or admin

About this task

The State model plugin is activated by default. For more information about base system states for change requests, see State model and transitions.

Procedure

1. Navigate to All > Change > Create New and complete the following steps to add a choice to the choice list.
   1. Right-click the State field and click Configure dictionary.
   2. In the Choices related list, run a filter for [Table] [is] [change_request].
   3. Click New and add the new state with the following information.
      • Table: Change Request [change_request]
      • Label: name of your new state
      • Value: numerical value that is not already assigned to an existing state choice
      • Sequence: number corresponding to the location for it to appear in the list of states. If you assign it the same sequence number as another choice, it appears below the other choice.
   4. Click Submit.
2. Navigate to System definition > Script includes.
   Script include records that contain SNC in the name are read-only. As you complete the following steps, ensure that you are selecting the correct script include to modify. For example, modify ChangeRequestStateHandler not ChangeRequestStateHandlerSNC.

   Note:

   Extended script includes (without SNC) include all of the functionality of their SNC counterparts. If you modify a base script include (appended with SNC), it is no longer updated during system upgrades.
3. Open the ChangeRequestStateHandler script to perform the following edits.
   • Update the statehandler constants section at the start of this script include to include values for the newly added state. For example:

     ChangeRequestStateHandler.MY_NEW_STATE = "mynewstate";

   • Update the STATE_NAMES map at the end of the initialize function to include the numeric value for the newly added state. For example:

     this.STATE_NAMES["-6"] = ChangeRequestStateHandler.MY_NEW_STATE;

     Note:

     The STATE_NAMES map provides a mapping between the numeric values that are stored in the State field on a change request under a memorable name. This mapping enables the memorable name to be used in the state model script includes.
4. Edit the appropriate script include to incorporate the new states into the model for the relevant change request types.
   Each type of change request has a corresponding script include named ChangeRequestStateModel_<type> where <type> is the value of the change request type. For example, ChangeRequestStateModel_normal defines the state model for change requests with a type of normal.

   Each state model script include defines objects that specify the following information.

   • Which states are available.
   • The next state or states for each available state.
   • Functions for each state transition to decide whether that transition is available (canMove) along with a function to be executed as part of moving to that state (moving).

   The following example is from the ChangeRequestStateModel_normal script include.

   

5. Create a UI action to provide a button to progress the change request to the new state.
   1. Use Insert and Stay to make a copy of one of the default UI actions, such as implement.
   2. Update the following fields on the form.

      Field name	Update
      Name	Update to match the name of the new state.
      Action name	Replace the state at the end of the name with the new state.
      Hint	Update the text to refer to the new state.
      Onclick	Rename the function to match the new state.
      Condition	Update the call to the isNext function with the new state.
      Script	Update the function name to match the one specified in the Onclick field. Update the line that starts with ga.addParam(“sysparm_state_name”,… to enter the name of the new state as the second parameter of the addParam function. Update the line starts with gsftSubmit and modify the third parameter of this function call to match the value entered in the Action name field.

      The following example uses the Implement UI action to show the values to update.

      

      The ChangeRequestStateHandler script include contains two functions that are used to determine if a UI action is displayed based on the current state of the change request.

      • isNext(stateName): This function only checks if the stateName passed as a parameter is available as a next state for the current state of the change request.
      • canMoveTo(stateName): This function performs the same check as the isNext function. However, it also checks the result of calling the appropriate canMoveTo function for the transition from the current state to the stateName passed as a parameter. This function is used if there are additional checks in the canMove functions such as checking that a field contains a particular value.
6. Complete the following steps to update the process flow configuration to incorporate the new change state.
   The process flow is displayed at the top of the Change Request form and is configured in various process flow records.

   

   1. Navigate to System UI > Process Flow module and filter for [Table] [is] [change_request].
   2. Open a record and use Insert and Stay to make a copy.
   3. Update the following fields on the form.

      Field name	Update
      Name	Update to match the name of the new state.
      Label	Update to match the name of the new state. This value is included in the process flow at the top of the Change Request form.
      Order	Update this number so that the new state is in the correct sequence with the existing process flow records for other states.
      Condition	Update the filter to match the new state.

   4. Click Update.

What to do next

To ensure that the new state works as expected, review the default workflows. Add the new state to the workflow as necessary.

Review default workflows

Any modification to the state model may impact the default workflows for change requests.

Before you begin

Role required: admin

About this task

Each change type has a default workflow. To ensure that any change to the state model has not adversely impacted workflows, you must review each of the default workflows.

Procedure

Review the workflow for each ChangeRequestStateModel_<type> script include that has been modified.

Table 1. Change request default workflows

Change type	Script include name	Workflow
Normal	ChangeRequestStateModel_normal	Change Request - Normal
Standard	ChangeRequestStateModel_standard	Change Request - Standard
Emergency	ChangeRequestStateModel_emergency	Change Request - Emergency

Modifications to the default workflow for each change type depend on where the new state is added in the sequences of states.