Define custom state model transitions

You can specify custom state transitions for the Incident (Case) table or custom tables. The EntityMetadata.IsStateModelAware property is true for tables that support state model transitions.

Custom state transitions are an optional level of filtering to define which state transitions are valid for a record in a given state. Particularly when you have a large number of combinations for valid states and status values, defining a limited list of options can make it easier for people to choose the correct status for a record.

What is the state model?

Tables that support the concept of state have a pair of columns that capture state model data, as shown in the following table.

The table definitions for the columns define what status values are valid for a given state. For example, for the Incident (Case) table, the default state and status options are shown in the following table.

This data is stored in the StatusOptionMetadata class, which represents the options in the StatusAttributeMetadata class.

To view table definitions for your organization, install the Metadata Browser solution described in Browse table definitions for your organization. You can also browse the reference documentation for table in the Table/entity reference.

Detect valid status transitions

You can modify the statuscode column to define which other status options represent valid transitions from the current status. For instructions, see the Define status reason transitions for the Case or custom tables

When custom state transitions are applied to a table, the EntityMetadata.EnforceStateTransitions property is true. Also, each StatusOptionMetadata within the StatusAttributeMetadata.Options collection has a TransitionData property. This property contains a string value that represents an XML document. This document contains the definition of the allowed transitions. For example, the default Incident (Case) StatusCode column option might have the following TransitionData value.

<allowedtransitions xmlns="https://schemas.microsoft.com/crm/2009/WebServices">  
<allowedtransition sourcestatusid="1" tostatusid="6" />  
<allowedtransition sourcestatusid="1" tostatusid="1000" />   
<allowedtransition sourcestatusid="1" tostatusid="2000" />  
<allowedtransition sourcestatusid="1" tostatusid="5" />  
</allowedtransitions>  

When this data is present and the table EnforceStateTransitions property is true, any incident instance can only be changed to one of the allowed statuscode values. You can use IOrganizationService.Update to set the statuscode OptionSetValue to any of the allowed values that don't represent a change in state. To change the state, use SetStateRequest setting the allowed State and Status property values or the CloseIncidentRequest setting Status property to one of the values allowed for the current statuscode value. Attempting to set an invalid value throws an error.

See also

Sample: Retrieve valid status transitions
Sample: Validate record state and set the state of record
Retrieve and detect changes to table definitions
Define status reason transitions