Define custom state model transitions


Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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.

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




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.


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.



Label: Active

Value: 0

Label: In Progress

Value: 1

State: 0

Label: On Hold

Value: 2

State: 0

Label: Waiting for Details

Value: 3

State: 0

Label: Researching

Value: 4

State: 0

Label: Resolved

Value: 1

Label: Problem Solved

Value: 5

State: 1

Label: Information Provided

Value: 1000

State: 1

Label: Canceled

Value: 2

Label: Canceled

Value: 6

State: 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 view the metadata for an uncustomized organization in the Excel file called EntityMetadata.xlsx included in the top-level folder of the SDK download.

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="">
<allowedtransition sourcestatusid="1" tostatusid="6" />
<allowedtransition sourcestatusid="1" tostatusid="1000" /> 
<allowedtransition sourcestatusid="1" tostatusid="2000" />
<allowedtransition sourcestatusid="1" tostatusid="5" />

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.

&lt;allowedtransitions xmlns=""&gt;
&lt;allowedtransition sourcestatusid="1" tostatusid="6" /&gt;
&lt;allowedtransition sourcestatusid="1" tostatusid="1000" /&gt;
&lt;allowedtransition sourcestatusid="1" tostatusid="2000" /&gt;
&lt;allowedtransition sourcestatusid="1" tostatusid="5" /&gt;

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

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright