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.

Note

Although the Incident (Case) table isn't included in a default Microsoft Dataverse environment, it is used by Dynamics 365 for Customer Service and defined within the Common Data Model

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.

Logical Name	Display Name	Description
statecode	Status	Represents the state of the record. For custom tables this value is Active or Inactive. You can't add more state choices but you can change the choice 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 more status choices and change the labels of existing choices.

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.

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 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