C# Code · Customization and Configuration · Dynamics Plugins · Functional Info

{Microsoft Dataverse} Explore Custom API feature Part-1 in Dynamics 365

Custom APIs offer a new code-first way to define messages that you can add to Dataverse web services. Conceptually, Custom APIs are an extension to Custom Actions that have provided a no-code way to include custom messages

Compare Custom API with Custom Action

CapabilityWorkflow Custom ActionCustom APIDescription
Declarative logic with workflowYesNoWorkflow Actions can have logic defined without writing code using the Classic Workflow designer.
Custom APIs require a plug-in written in .NET to implement logic that is applied on the server.
Require specific privilegeNoYesWith Custom API you can designate that a user must have a specific privilege to call the message. If the user doesn’t have that privilege through their security roles or team membership, an error will be returned.
Define main operation logic with codeYesYesWith Workflow Custom Actions the main operation processes the Workflow definition which may include custom workflow activities. The code in these custom workflow activities is processed in the main operation together with any other logic in the workflow.

With Custom API the message creator simply associates their plug-in type with the Custom API to provide the main operation logic.
Block Extension by other plug-insNoYesAll messages defined using Workflow Custom Actions are extensible. This means any 3rd party developer can apply additional logic in a plug-in registered on the PreValidation, PreOperation, or PostOperation stages of the message to change the behavior.

If a 3rd party plug-in step is synchronous, it means that logic or errors in plug-ins that extend your message can cause the message defined by a Workflow Custom Action to fail. With a Custom API you can block this.
Make message privateNoYesWhen you create a message using a Workflow Custom Action, it is exposed publicly in the endpoint for anyone else to discover and use. If someone else takes a dependency on the message you created, their code will be broken if you remove, rename, or change the input or output parameter signature in the future.

If you do not intend for your message to be used by anyone else, you can mark it as a private message. This will indicate that you do not support others using the message you create, and it will not be included in definitions of available functions or actions exposed by the Web API $metadata service definition. Classes for calling these messages will not be generated using code generation tools.
Localizable names and descriptionsNoYesWhile Workflow Custom Actions provide for a friendly name for the custom action and any input and output parameters it uses, these values are not localizable. With Custom API you can provide localizable names and descriptions. These localized strings can then be bound to controls that provide a UI to use the message.
Create OData FunctionNoYesThe Dataverse Web API is an OData web service. OData provides for two types of operations: Actions & Functions.

An Action is an operation that makes changes to data in the system. It is invoked using the Http POST method and parameters are passed in the body of the request.A Function is an operation that makes no change to data, for example an operation that simply retrieves data. It is invoked using an Http GET method and the parameters are passed in the URL of the request There is nothing to prevent you from defining all operations as Actions if you wish. But some operations may be best expressed using a GET request available by defining a function.
Create a global operation not bound to an entityYesYesBoth provide the ability to define a global message not bound to an entity.
Bind an operation to an entityYesYesBoth provide the ability to pass a reference to a specific entity record by binding it to an entity.
Bind an operation to an entity collectionNoYesBinding an operation to an entity collection allows for another way to accept an entity collection as a required parameter value for operation.
Compose or modify a custom API by editing a solutionNoYesISVs who build and maintain products that work with the Power Platform apply ALM practices that involve solutions. The data within a solution is commonly checked into a source code repository and checked out by a developer applying changes.

A Workflow Custom Action is defined by a XAML Windows Workflow Foundation document which is transported as part of a solution. However, creating new or editing existing workflow definitions outside of the workflow designer is not supported.

Custom API definitions are solution aware components included in a solution through a set of folders and XML documents. These files and the file structure enable transport the API from one environment to another. Because these are plain text files, changes can be made to them, or new APIs can be defined by working with these files. This method of defining Custom APIs is supported.
Subject to 2 minute time limitNoYesA plug-in that implements the main operation for a Custom API is subject to the 2 minute time limit to complete execution.

A Workflow Custom Action is not technically limited to two minutes. If a step in the Workflow logic contains a custom workflow activity, that part will be limited to two minutes. But the entire workflow cannot run indefinitely. There are other limitations that will cause long-running Workflow custom actions to fail. More information: Watch out for long running actions

Data types supported for Custom API Request Parameters and Response properties are

The data type of the custom API request parameter.

  • Value: 0 Label: Boolean
  • Value: 1 Label: DateTime
  • Value: 2 Label: Decimal
  • Value: 3 Label: Entity
  • Value: 4 Label: EntityCollection
  • Value: 5 Label: EntityReference
  • Value: 6 Label: Float
  • Value: 7 Label: Integer
  • Value: 8 Label: Money
  • Value: 9 Label: Picklist
  • Value: 10 Label: String
  • Value: 11 Label: StringArray
  • Value: 12 Label: Guid

Next blog we will deep dive into Custom API. We will explore how to create Custom API and write .Net code to build the capabilities.

Part – 2 https://xrmdynamicscrm.wordpress.com/2020/12/21/microsoft-dataverse-explore-custom-api-feature-part-2-in-dynamics-365/

2 thoughts on “{Microsoft Dataverse} Explore Custom API feature Part-1 in Dynamics 365

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s