Web API Actions

Article
01/01/2023

Within the CSDL $metadata document, you will find Action elements that describe operations that change data.

Every action has a Name attribute. This name will be part of the URL when you use HTTP POST, sending any defined parameters for the action in the body of the request. More information: Use Web API actions

Bound actions

Actions may have a IsBound="true" attribute. This means it is a bound action. Actions without the IsBound attribute are unbound. A bound action means that the first parameter is a reference to a to a table record or to an entity set.

When an action is bound, it will have a reference to a specific item within the service namespace. To use the action, you must use the fully qualified name including the Microsoft.Dynamics.CRM namespace. More information: Service namespace

Parameters

Actions usually have one or more Parameter elements. Each parameter will have the following attributes:

Attribute	Description
`Name`	The name of the parameter. The name is unique unless the `Action` is overloaded. More information: Overloaded Actions.
`Type`	The type of the parameter.
`Nullable="false"`	Whether the parameter can accept a null value.

ReturnType

Actions may return values. When an action returns a value, it will have a ReturnType element.

Attribute	Description
`Type`	The type of the parameter.
`Nullable="false"`	Whether the value may be null.

Action definition examples

The following represent some fictional examples of Action definitions showing different binding patterns. Each of these examples returns an integer value.

Unbound actions

An unbound action with a single integer Number parameter.

<Action Name="UnBoundActionExample">
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Action>

Action bound to an entity

An action bound to the account entity with a single integer Number parameter.

<Action Name="EntityBoundActionExample" IsBound="true">
    <Parameter Name="entity" Type="mscrm.account" Nullable="false" />
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Action>

Action bound to an entity set

An action bound to the account EntitySet with a single integer Number parameter.

<Action Name="EntityCollectionBoundActionExample" IsBound="true">
    <Parameter Name="entityset" Type="Collection(mscrm.account)" Nullable="false" />
    <Parameter Name="Number" Type="Edm.Int32" Nullable="false" />
    <ReturnType Type="Edm.Int32" Nullable="false" />
</Action>

Overloaded Actions

Usually, each action you find in the $metadata will be the only action with that name. However bound actions can have multiple definitions when bound to different types. The AddItemCampaign action included the marketing solution is one example. You cannot create an overloaded action using custom API.

More information: Action Overload Rules

Next steps

Learn about Function Definitions.

Function Definitions