Calling Dataverse Custom API from JavaScript
If you followed along our last blog post on how to implement business logic with Dataverse Custom API, you got a solid understanding how to set up a Custom API. Each API can be configured to have multiple request parameters of different datatypes. Passing a request object to Xrm.WebApi.online.execute along with a payload of request parameters triggers the action.
Lets setup a bound action that features all of those parameters and post back to the caller to see if all of them have made it to the server side.
Calling bound API from JavaScript
The function below uses Xrm.WebApi.online.execute
to trigger the API. It is important to describe the payload inside the getMetadata
function.
- Boolean ⇾ Edm.Boolean
- Decimal ⇾ Edm.Decimal
- Entity ⇾ mscrm.account
- EntityCollection ⇾ Collection(mscrm.crmbaseentity)
- EntityReference ⇾ mscrm.account
- Float ⇾ Edm.Float
- Integer ⇾ Edm.Int32
- Money ⇾ Edm.Money
- Picklist ⇾ Edm.Int32
- String ⇾ Edm.String
- StringArray ⇾ Collection(Edm.String)
async function callAction() {
let account = {
entityType: "account",
id: "2a932859-0ebb-eb11-bacc-000d3a2d9f66",
};
let DecimalParam = 42.2;
let BooleanParameter = "true";
let FloatParam = 42.4;
let MoneyParameter = 42;
let IntegerParam = 42;
let StringParam = "Lorem Ipsum";
let EntityReferenceParam = account;
let EntityParam = account;
let EntityCollectionParam = [account, account];
let PicklistParam = 42;
let StringArrayParam = ["Lorem", "Ipsum"];
function new_TestApiParameters(
entity,
BooleanParameter,
DecimalParam,
FloatParam,
MoneyParameter,
IntegerParam,
StringParam,
EntityReferenceParam,
EntityParam,
EntityCollectionParam,
PicklistParam,
StringArrayParam
) {
this.entity = entity;
this.BooleanParameter = BooleanParameter;
this.DecimalParam = DecimalParam;
this.FloatParam = FloatParam;
this.MoneyParameter = MoneyParameter;
this.IntegerParam = IntegerParam;
this.StringParam = StringParam;
this.EntityReferenceParam = EntityReferenceParam;
this.EntityParam = EntityParam;
this.EntityCollectionParam = EntityCollectionParam;
this.PicklistParam = PicklistParam;
this.StringArrayParam = StringArrayParam;
this.getMetadata = function () {
return {
operationName: "new_TestApiParameters",
boundParameter: "entity",
parameterTypes: {
entity: {
typeName: "mscrm.account",
structuralProperty: 5,
},
BooleanParameter: {
typeName: "Edm.Boolean",
structuralProperty: 1,
},
DecimalParam: {
typeName: "Edm.Decimal",
structuralProperty: 1,
},
FloatParam: {
typeName: "Edm.Float",
structuralProperty: 1,
},
MoneyParameter: {
typeName: "Edm.Money",
structuralProperty: 1,
},
IntegerParam: {
typeName: "Edm.Int32",
structuralProperty: 1,
},
StringParam: {
typeName: "Edm.String",
structuralProperty: 1,
},
EntityReferenceParam: {
typeName: "mscrm.account",
structuralProperty: 5,
},
EntityParam: {
typeName: "mscrm.account",
structuralProperty: 5,
},
EntityCollectionParam: {
typeName: "Collection(mscrm.crmbaseentity)",
structuralProperty: 4,
},
PicklistParam: {
typeName: "Edm.Int32",
structuralProperty: 1,
},
StringArrayParam: {
typeName: "Collection(Edm.String)",
structuralProperty: 4,
},
},
operationType: 0,
};
};
}
var request = new new_TestApiParameters(
account,
BooleanParameter,
DecimalParam,
FloatParam,
MoneyParameter,
IntegerParam,
StringParam,
EntityReferenceParam,
EntityParam,
EntityCollectionParam,
PicklistParam,
StringArrayParam
);
let res = await Xrm.WebApi.online.execute(request);
console.log((await res.json()).Response);
}
Console Output:
BooleanParameter: True DecimalParam: 42.2 FloatParam: 42.4 MoneyParameter: 42 IntegerParam: 42 StringParam: 'Lorem Ipsum' EntityReferenceParam: account EntityParam: 'account' EntityCollectionParam's Count: '2' PicklistParam: '42' StringArrayParam: '2'
Implementing a plugin
This plugin returns all parameters within a single string back to the caller. If it is a collection based parameter the count of elements is returned instead.
public class TestApiParametersPlugin : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
var response = "";
if (context.InputParameters.TryGetValue("BooleanParameter", out var BooleanParameter))
{
response += $"{nameof(BooleanParameter)}: {BooleanParameter}\n";
}
if (context.InputParameters.TryGetValue("DecimalParam", out var DecimalParam))
{
response += $"{nameof(DecimalParam)}: {DecimalParam}\n";
}
if (context.InputParameters.TryGetValue("FloatParam", out var FloatParam))
{
response += $"{nameof(FloatParam)}: {FloatParam}\n";
}
if (context.InputParameters.TryGetValue("MoneyParameter", out var MoneyParameter))
{
response += $"{nameof(MoneyParameter)}: {((Money)MoneyParameter)?.Value}\n";
}
if (context.InputParameters.TryGetValue("IntegerParam", out var IntegerParam))
{
response += $"{nameof(IntegerParam)}: {IntegerParam}\n";
}
if (context.InputParameters.TryGetValue("StringParam", out var StringParam))
{
response += $"{nameof(StringParam)}: '{StringParam}'\n";
}
if (context.InputParameters.TryGetValue("EntityReferenceParam", out var EntityReferenceParam))
{
response += $"{nameof(EntityReferenceParam)}: {((EntityReference)EntityReferenceParam).LogicalName}\n";
}
if (context.InputParameters.TryGetValue("EntityParam", out var EntityParam))
{
response += $"{nameof(EntityParam)}: '{((Entity)EntityParam).LogicalName}'\n";
}
if (context.InputParameters.TryGetValue("EntityCollectionParam", out var EntityCollectionParam))
{
response += $"{nameof(EntityCollectionParam)}'s Count: '{((EntityCollection)EntityCollectionParam).Entities.Count}'\n";
}
if (context.InputParameters.TryGetValue("PicklistParam", out var PicklistParam))
{
response += $"{nameof(PicklistParam)}: {((OptionSetValue)PicklistParam)?.Value}\n";
}
if (context.InputParameters.TryGetValue("StringArrayParam", out var StringArrayParam))
{
response += $"{nameof(StringArrayParam)}: '{((string[])StringArrayParam).Length}'\n";
}
context.OutputParameters.Add("Response", response);
}
}