MSDyn365 Internals: Read-only Sales entities

If you work with the standard D365 Sales entities like Quote, Order and Invoice you might have had users come across error messages like

Error updating Quotes - Cannot Update a Read-Only Entity

Most entity types have Active and Inactive states but can actually be edited via the API even when they’re inactive. These three sales entities have some more specialised logic though.

States and Transitions

It’s important to understand the different states a record can be in and how they can move between them. State codes are defined by the system and can’t be edited (though you can change the name of them). Status codes within the various states are configurable – you can add, remove or rename these as much as you like.

Mostly you can update the statecode and statuscode fields via the API using a standard Update request. However, there are some cases where you need to use specialised messages to change from one state to another.

Here we can see the quote entity has 4 state codes. The only one that the record is normally editable in is Draft (green). The others (red) are read-only. If you open a record in any of these states in the user interface the form will be shown read-only, and if you try to edit a record using an API, Power Automate, workflows etc. you’ll likely (depending on permissions, see below!) get the “Error updating Quotes – Cannot Update a Read-Only Entity” message.

We can also see that to move a quote from the Active to Won state requires using a WinQuote action, while moving from Active to Closed requires using a CloseQuote action. Any of the other state transitions shown can be done with a standard Update request.

So what does this mean if we need to change the description of a quote in Won state? First we’d need to make it editable by changing the state back to Draft. Then we can make the change we need, then update the state to Active, then use the WinQuote request to change the state back to Won again.

Orders have got a flatter hierarchy of states – from the initial Active state you can go directly to any of the other 4 states. Going to Cancelled state requires using a CancelOrder request, and Fulfilled requites a FulfillOrder request. All the other transitions use a standard Update request.

Updating a cancelled order requires updating the state back to Active, making the required changes, then using the CancelOrder request to change the state back to Cancelled again.

Invoices are slightly simpler – although they can still only be edited in their default “New” state, they can be moved directly from any state to any other state using a standard Update request.

Permissions aren’t everything

You might find that your users hit this error but you don’t, which suggests there’s some permission missing. It’s a bit more awkward than that though. In this case it’s not a specific permission that you could add to a security role that lets users edit an otherwise read-only record. Instead, the user has to either:

• have the System Administrator security role, or
• be an integration user and have Sales Order Processing enabled

If either of these are met then the user will be able to edit quotes/orders/invoices in any state, otherwise they’ll get the “Cannot Update a Read-Only Entity” error.

Because the records are editable in any state by a system administrator, this can be an easy error to overlook while you are building a system.