Use Web API actions

Use Web API actions to perform reusable operations that have side effects in Microsoft Dataverse. Send a POST request with actions listed in Web API Action Reference to modify data, trigger business logic, or invoke custom processes. You can also define custom actions. For more information, see Create your own messages.

Actions are defined in the CSDL $metadata document. See Web API Actions for more information.

Unbound actions

The following XML shows the definition of the Merge action represented in the $metadata service document.

<Action Name="Merge">
   <Parameter Name="Target" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="Subordinate" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="UpdateContent" 
      Type="mscrm.crmbaseentity" />
   <Parameter Name="PerformParentingChecks" 
      Type="Edm.Boolean" 
      Nullable="false" />
</Action>

The Merge action corresponds to the MergeRequest class when you use the SDK for .NET. Use this action to merge a pair of duplicate records. This action doesn't include a return value. If it succeeds, the operation is complete.

The following example shows the HTTP request and response to call the Merge action for two account records.

Request:

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

{
  "Target": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "cc1e2c4a-e577-ec11-8d21-000d3a554dcd"
  },
  "Subordinate": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "e408fa45-3a70-ec11-8943-00224823561e"
  },
  "PerformParentingChecks": false
}

Response:

HTTP/1.1 204 No Content
OData-Version: 4.0

For more information, see Merge table rows using the Web API.

Bound actions

You can bind an action to an entity or to an entity collection. Binding an action to an entity is more common.

In the CSDL $metadata document, an Action element that represents a bound action has an IsBound attribute set to 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 you invoke a bound function, include the full name of the function, including the Microsoft.Dynamics.CRM namespace. If you don't include the full name, you get the following error: Status Code:400 Request message has unresolved parameters.

Actions bound to a table

The following example shows the definition of the AddToQueue action and AddToQueueResponse complex type in the CSDL as an action bound to an entity:

<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 SDK for .NET. In the Web API, this action is bound to the queue entity type that represents the AddToQueueRequest.DestinationQueueId property.

This action accepts several more parameters and returns a AddToQueueResponse complex type corresponding to the AddToQueueResponse returned by the SDK for .NET. When an action returns a complex type, the definition of the complex type appears directly above the action in the CSDL.

You must invoke an action bound to an entity by using a URI to set the first parameter value. You can't set it as a named parameter value.

The following example shows how to use the AddToQueue action to add a letter to a queue. Because the type of the Target parameter type isn't specific (mscrm.crmbaseentity), you must explicitly declare type of the object by 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. For more information, see Specify entity parameter type.

Request:

POST [Organization URI]/api/data/v9.2/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.2/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Actions bound to a table collection

It's less common to find actions bound to an entity collection. The following list includes some actions you might find:

FulfillSalesOrder in Dynamics 365 for Sales

CreateMultiple

UpdateMultiple

As an example of an action bound to an entity collection, the following definition shows the ExportTranslation action represented in the CSDL $metadata:

<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 SDK for .NET. In the Web API, this action is bound to the solution entity type. But rather than passing a value to the request, the entity collection binding constraint requires that the URI of the request must include the path to the specified entity set.

The following example shows how to use the ExportTranslation action, which exports a binary file containing data about localizable string values that you can update to modify or add localizable values. Note how the entity collection bound action comes after the entity set name for the solution entity: solutions.

Request:

POST [Organization URI]/api/data/v9.2/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.2/$metadata#Microsoft.Dynamics.CRM.ExportTranslationResponse",
    "ExportTranslationFile": "[Binary data Removed for brevity]"
}

Use a custom action

A custom action can be a custom API or a custom process action. Each type of custom action has a corresponding operation you can use. For a custom API, the operation can be a function. To learn more, see Create your own messages.

The following example shows a custom process action.

Custom action example: Add a note to a contact

Suppose you want to create a custom action that adds 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, you see this new action defined when you download the CSDL.


<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 show how to call the custom action and the response it returns if successful.

Request:

POST [Organization URI]/api/data/v9.2/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.2/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Specify the table type parameter

When an action requires an entity as a parameter and the type of entity is ambiguous, 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, the Target parameter to the AddToQueue action is an activity. But since all activities inherit from the activitypointer entity type, 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 and RemoveMembersTeam actions because the Members parameter is a collection of systemuser entity type, which inherits its ownerid primary key from the principal entity type. If you pass the following JSON to represent a single systemuser in the collection, it's clear that the entity is a systemuser and not a team entity type, which also inherits from the principal entity type.

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

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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-14

Condividi tramite

Use Web API actions

Unbound actions

Bound actions

Actions bound to a table

Actions bound to a table collection

Use a custom action

Custom action example: Add a note to a contact

Specify the table type parameter

See also

Commenti e suggerimenti

Risorse aggiuntive