Edit

Use Web API actions

  • Article

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. More information: Create your own messages.

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

Unbound actions

The following is 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 using the organization service. 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 is 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

More information: Merge table rows using the Web API

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 entity type that represents the AddToQueueRequest.DestinationQueueId property. This action accepts several additional parameters and returns a AddToQueueResponse complex type 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 DeliverIncomingEmail ExportTranslation
ValidateSavedQuery FulfillSalesOrder in Dynamics 365 for Sales

As an example of an action bound to an entity collection, the following is the definition of 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 organization service. 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 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

A custom action may be a Custom API or Custom Process Action. Either way it is created, there will be a corresponding operation that you can use. With Custom API, the operation may be a function. More information: Create your own messages

The following example is for a custom process action.

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 the 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 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 it's ownerid primary key from the principal entity type. 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 entity type, 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 Actions
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 row using the Web API
Retrieve a table row using the Web API
Update and delete table rows using the Web API
Associate and disassociate table rows 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