Define custom state model transitions

You can specify custom state transitions for the Incident (Case) entity or custom entities. The EntityMetadata.IsStateModelAware property is true for entities 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?

Entities that support the concept of state have a pair of attributes that capture this data, as shown in this table.

Logical Name	Display Name	Description
statecode	Status	Represents the state of the record. For custom entities this is Active or Inactive. The Incident (case) entity uses Active, Resolved, and Canceled. You can’t add more state options but you can change the option labels.
statuscode	Status Reason	Represents a status that is linked to a specific state. Each state must have at least one possible status. You can add additional status options and change the labels of existing options.

The metadata for the attributes defines what status values are valid for a given state. For example, for the Incident (Case) entity, the default state and status options are shown in the following table.

State	Status
Label: Active Value: 0	Label: In Progress Value: 1 State: 0
Label: Active Value: 0	Label: On Hold Value: 2 State: 0
Label: Active Value: 0	Label: Waiting for Details Value: 3 State: 0
Label: Active Value: 0	Label: Researching Value: 4 State: 0
Label: Resolved Value: 1	Label: Problem Solved Value: 5 State: 1
Label: Resolved Value: 1	Label: Information Provided Value: 1000 State: 1
Label: Canceled Value: 2	Label: Canceled Value: 6 State: 2
Label: Canceled Value: 2	Label: Merged Value: 2000 State: 2

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

To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also browse the reference documentation for entities in the Entity Reference.

Detect valid status transitions

You can modify the statuscode attribute to define which other status options represent valid transitions from the current status. For instructions, see the Customization Guide topic: Define status reason transitions

When custom state transitions are applied to an entity, the EntityMetadata.EnforceStateTransitions property will be true. Also, each StatusOptionMetadata within the StatusAttributeMetadata.Options collection will have a new TransitionData property. This property will contain a String value that represents an XML document. This document contains the definition of the allowed transitions. For example, the default Incident (Case) StatusCode attribute option may 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>

Note

When this data is retrieved in unmanaged code from the web service, for example when using JavaScript, it will be escaped and appear like the following example.

<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 Entity EnforceStateTransitions property is true, any incident instance can only be changed to one of the allowed statuscode values. You can useIOrganizationService.Update to set the statuscodeOptionSetValue 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
Record state and status
Retrieve and Detect Changes to Metadata