Use Web API actions

Note

Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.

Actions and functions represent re-usable operations you can perform using the Web API. Use a POST request with actions listed in Web API Action Reference to perform operations that have side effects. You can also define custom actions and they’ll be available for you to use.

Unbound actions

Actions are defined in CSDL metadata document. As an example, the following is the definition of the WinOpportunity Action represented in the metadata document.

<Action Name="WinOpportunity">
  <Parameter Name="OpportunityClose" Type="mscrm.opportunityclose" Nullable="false" />
  <Parameter Name="Status" Type="Edm.Int32" Nullable="false" />
</Action>

The WinOpportunity Action corresponds to the WinOpportunityRequest using the organization service. Use this action to set the state of an opportunity to Won and create an opportunityclose EntityType to record the event. This action doesn’t include a return value. If it succeeds, the operation is complete.

The OpportunityClose parameter requires a JSON representation of the opportunityclose entity to create in the operation. This entity must be related to the opportunity issuing the opportunityid single-valued navigation property. In the JSON this is set using the @odata.bind annotation as explained in Associate tables on create.

The Status parameter must be set to the status to for the opportunity when it is closed. You can find the default value for this in the opportunity EntityType statuscode property. The Won option has a value of 3. You may ask yourself, why is it necessary to set this value when there is only one status reason option that represents Won? The reason is because you may define custom status options to represent a win, such as Big Win or Small Win, so the value could potentially be different from 3 in that situation.

The following example is the HTTP request and response to call the WinOpportunity action for an opportunity with an opportunityid value of b3828ac8-917a-e511-80d2-00155d2a68d2.

Request

POST [Organization URI]/api/data/v9.0/WinOpportunity HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Status": 3,
 "OpportunityClose": {
  "subject": "Won Opportunity",
  "opportunityid@odata.bind": "[Organization URI]/api/data/v9.0/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"
 }
}

Response

HTTP/1.1 204 No Content
OData-Version: 4.0

Bound actions

There are two ways that an action can be bound. The most common way is for the action to be bound by an entity. Less frequently, it can also be bound to an entity collection.

In the CSDL metadata document, when an Action element represents a bound action, it has an IsBound attribute with the value true. The first Parameter element defined within the action represents the entity that the operation is bound to. When the Type attribute of the parameter is a collection, the operation is bound to a collection of entities.

When invoking a bound function, you must include the full name of the function including the Microsoft.Dynamics.CRM namespace. If you do not include the full name, you will get the following error: Status Code:400 Request message has unresolved parameters.

Actions bound to a table

As an example of an action bound to an entity, the following is the definition of the AddToQueue Action represented in the CSDL:

 <ComplexType Name="AddToQueueResponse">
 <Property Name="QueueItemId" Type="Edm.Guid" Nullable="false" />
 </ComplexType>
 <Action Name="AddToQueue" IsBound="true">
  <Parameter Name="entity" Type="mscrm.queue" Nullable="false" />
  <Parameter Name="Target" Type="mscrm.crmbaseentity" Nullable="false" />
  <Parameter Name="SourceQueue" Type="mscrm.queue" />
  <Parameter Name="QueueItemProperties" Type="mscrm.queueitem" />
  <ReturnType Type="mscrm.AddToQueueResponse" Nullable="false" />
</Action>

This entity bound action is equivalent to the AddToQueueRequest used by the organization service. In the Web API this action is bound to the queue EntityType that represents the AddToQueueRequest.DestinationQueueId property. This action accepts several additional parameters and returns a AddToQueueResponse ComplexType corresponding to the AddToQueueResponse returned by the organization service. When an action returns a complex type, the definition of the complex type will appear directly above the action in the CSDL.

An action bound to an entity must be invoked using a URI to set the first parameter value. You cannot set it as a named parameter value.

The following example shows using the AddToQueue Action to add a letter to a queue. Because the type of the Target parameter type is not specific (mscrm.crmbaseentity), you must explicitly declare type of the object using the @odata.type property value of the full name of the entity, including the Microsoft.Dynamics.CRM namespace. In this case, Microsoft.Dynamics.CRM.letter. More information: Specify entity parameter type

Request

POST [Organization URI]/api/data/v9.0/queues(56ae8258-4878-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Target": {
  "activityid": "59ae8258-4878-e511-80d4-00155d2a68d1",
  "@odata.type": "Microsoft.Dynamics.CRM.letter"
 }
}

Response


HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Actions bound to a table collection

It is less common to find actions bound to an entity collection. The following are some you may find:

     
CreateException Action/ DeliverIncomingEmail Action/ ExportTranslation Action/
FulfillSalesOrder Action/ ValidateSavedQuery Action

As an example of an action bound to an entity collection, the following is the definition of the ExportTranslation Action represented in the CSDL:

<ComplexType Name="ExportTranslationResponse">
	<Property Name="ExportTranslationFile" Type="Edm.Binary" />
</ComplexType>
<Action Name="ExportTranslation" IsBound="true">
	<Parameter Name="entityset" Type="Collection(mscrm.solution)" Nullable="false" />
	<Parameter Name="SolutionName" Type="Edm.String" Nullable="false" Unicode="false" />
	<ReturnType Type="mscrm.ExportTranslationResponse" Nullable="false" />
</Action>

This entity collection bound action is equivalent to the ExportTranslationRequest used by the organization service. In the Web API this action is bound to the solution EntityType. But rather than passing a value to the request, the entity collection binding simply applies the constraint that the URI of the request must include the path to the specified entity set.

The following example shows using the ExportTranslation Action which exports a binary file containing data about localizable string values which can be updated to modify or add localizable values. Note how the entity collection bound action is preceded by the entity set name for the solution entity: solutions.

Request

POST [Organization URI]/api/data/v9.1/solutions/Microsoft.Dynamics.CRM.ExportTranslation HTTP/1.1
Accept: application/json
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "SolutionName":"MySolution"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ExportTranslationResponse",
    "ExportTranslationFile": "[Binary data Removed for brevity]"
}

Use a custom action

Regardless of whether the operations included in your custom action have side effects, they can potentially modify data and therefore are considered actions rather than functions. There is no way to create a custom function.

Custom action example: Add a note to a contact

Let’s say that you want to create a custom action that will add a new note to a specific contact. You can create a custom action bound to the contact entity with the following properties.

UI Label Value
Process Name AddNoteToContact
Unique Name new_AddNoteToContact
Entity Contact
Category Action

Process Arguments

Name Type Required Direction
NoteTitle String Required Input
NoteText String Required Input
NoteReference EntityReference Required Output

Steps

Name Step Type Description
Create the note Create Record Title = {NoteTitle(Arguments)}
Note Body = {NoteText(Arguments)}
Regarding = {Contact{Contact}}
Return a reference to the note Assign Value NoteReference Value = {Note(Create the note (Note))}

After you publish and activate the custom action, when you download the CSDL you will find this new action defined.


<Action Name="new_AddNoteToContact" IsBound="true">
  <Parameter Name="entity" Type="mscrm.contact" Nullable="false" />
  <Parameter Name="NoteTitle" Type="Edm.String" Nullable="false" Unicode="false" />
  <Parameter Name="NoteText" Type="Edm.String" Nullable="false" Unicode="false" />
  <ReturnType Type="mscrm.annotation" Nullable="false" />
</Action>

The following HTTP request and response shows how to call the custom action and the response it returns if successful.

Request

POST [Organization URI]/api/data/v9.0/contacts(94d8c461-a27a-e511-80d2-00155d2a68d2)/Microsoft.Dynamics.CRM.new_AddNoteToContact HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "NoteTitle": "New Note Title",
 "NoteText": "This is the text of the note"
}

Response


HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Specify table type parameter

When an action requires an entity as a parameter and the type of entity is ambiguous, you must use the @odata.type property to specify the type of entity. The value of this property is the fully qualified name of the entity, which follows this pattern: Microsoft.Dynamics.CRM.+<entity logical name>.

As shown in the Bound actions section above, the Target parameter to the AddToQueue Action is an activity. But since all activities inherit from the activitypointer EntityType, you must include the following property in the entity JSON to specify the type of entity is a letter: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Two other examples are AddMembersTeam Action and RemoveMembersTeam Action because the Members parameter is a collection of systemuser EntityType which inherits it's ownerid primary key from the principal EntityType. If you pass the following JSON to represent a single systemuser in the collection, it is clear that the entity is a systemuser and not a team EntityType, which also inherits from the principal entitytype.

{
 "Members": [{
  "@odata.type": "Microsoft.Dynamics.CRM.systemuser",
  "ownerid": "5dbf5efc-4507-e611-80de-5065f38a7b01"
 }]
}

If you do not specify the type of entity in this situation, you can get the following error: "EdmEntityObject passed should have the key property value set.".

See also

Web API Functions and Actions Sample (C#)
Web API Functions and Actions Sample (Client-side JavaScript)
Perform operations using the Web API
Compose Http requests and handle errors
Query Data using the Web API
Create a table using the Web API
Retrieve a table using the Web API
Update and delete tables using the Web API
Associate and disassociate tables using the Web API
Use Web API functions
Execute batch operations using the Web API
Impersonate another user using the Web API
Perform conditional operations using the Web API

Note

Can you tell us about your documentation language preferences? Take a short survey.

The survey will take about seven minutes. No personal data is collected (privacy statement).