Use Web API actions

Article
01/12/2017

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

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.

In this topic

Unbound actions

Bound actions

Use a custom action

Specify entity parameter type

Unbound actions

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

<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 entities 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 EntityTypestatuscode 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/v8.2/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/v8.2/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"
 }
}

Response

HTTP/1.1 204 No Content
OData-Version: 4.0

Bound actions

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. As an example, 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 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.

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

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.

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/v8.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/v8.2/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Use a custom action

If you define custom actions for your organization or solution these will also be included in the CSDL metadata document. For information about creating actions using the customization tools in the application, see the TechNet topic Actions. For information about creating and using your own custom actions, see Create your own actions.

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))}

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/v8.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/v8.2/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Specify entity parameter type

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

Use Web API actions

In this topic

Unbound actions

Bound actions

Use a custom action

Custom action example: Add a note to a contact

Specify entity parameter type

See Also

Additional resources