API

Voice for Dynamics exposes a JavaScript API which can be called by any custom or out-of-the-box JS plugin to carry out certain tasks. All functions within the API are asynchronous and the proper way to call is to use await statement or properly handle the Promise object returned.

Enreach.API.executeQuery

Sends a request to Enreach REST API. Authentication is managed automatically, by adding the token to request header.

Parameters:

query (string): path within Enreach API
postData (object): Object which gets sent as payload to Enreach API in a POST or PUT request
method (string): HTTP method to be used. If specified, overrides the method determined by the existence of postData;

If postData parameter is NULL then a GET request is sent, whereas any object passed here means a POST request. The object passed here is serialized as JSON in the request payload.

If method (non-mandatory) parameter is specified, it overrides the above logic to determine HTTP method.

Detailed Enreach API documentation can be found here: https://doc.enreachvoice.com/beneapi

Enreach.API.setANumber

Parameters:

aNumber (string): the A-number to set

Sets the A-number (the phone number the call appears to come from) before making an outbound call. This way the called party can see a meaningful caller when answering the call. In practice makes a call to Enreach API using the path /users/{userId}/features/cli/activate/

A-number is valid for the next call only, is not set permanently for the user.

Detailed documentation: https://doc.enreachvoice.com/beneapi#user-features

The user has to have correct settings in Enreach Cloud (among others CallAsSetting parameter, pool membership) to be able to impersonate (use the A-number) of a certain pool.

Enreach.API.Xrm.createRecord

Creates an entity in Dynamics with a retry logic, to ensure that in case CIF CRUD API fails, the operation will more likely succeed.

Parameters:

entityLogicalName: Logical name of the table you want to create. For example: "account".
data: A JSON object defining the columns and values for the new table record.
maxRetries: Maximum number of retries, if the operation against Dynamics API fails. Optional, default value is 3.
delay: The amount of milliseconds to wait between two retries. Optional, default value is 1000 (1 second)

Microsoft CIF API works so, that from within the widget it sends a message to main window using window.postMessage() JavaScript method, and then waits for the main window to return the result in the same way. Timeout of this mechanism is 10 seconds, so CIF API considers the request as failed after not receiving any response in 10 secs, even if it actually succeeds after the timeout. As a result, retrying might create duplicates in Dynamics, so this API feature must be used only if duplicates don’t cause serious problems.

The purpose and usage of the method is identical to the underlying API provided by Microsoft, the only addition is the retry logic.

Enreach.API.Xrm.updateRecord

Updates an entity in Dynamics with a retry logic, to ensure that in case CIF CRUD API fails, the operation will more likely succeed.

Parameters:

entityLogicalName: The table logical name of the record you want to update. For example: "account".
id: GUID of the table record you want to update
data: A JSON object containing key: value pairs, where `key` is the property of the table and value is the value of the property you want to update.
maxRetries: Maximum number of retries, if the operation against Dynamics API fails. Optional, default value is 3.
delay: The amount of milliseconds to wait between two retries. Optional, default value is 1000 (1 second)

Microsoft CIF API works so, that from within the widget it sends a message to main window using window.postMessage() JavaScript method, and then waits for the main window to return the result in the same way. Timeout of this mechanism is 10 seconds, so CIF API considers the request as failed after not receiving any response in 10 secs, even if it actually succeeds after the timeout. As a result, retrying might update the same record multiple times in Dynamics, so this API feature must be used only if multiple updates don’t cause serious problems.

The purpose and usage of the method is identical to the underlying API provided by Microsoft, the only addition is the retry logic.

Enreach.API.Xrm.retrieveRecord

Retrieves an entity from Dynamics with a retry logic, to ensure that in case CIF CRUD API fails, the operation will more likely succeed.

Parameters:

entityLogicalName: The table logical name of the record you want to retrieve. For example: "account".
id: GUID of the table record you want to retrieve
options: OData system query options, $select and $expand, to retrieve your data.
maxRetries: Maximum number of retries, if the operation against Dynamics API fails. Optional, default value is 3.
delay: The amount of milliseconds to wait between two retries. Optional, default value is 1000 (1 second)

Microsoft CIF API works so, that from within the widget it sends a message to main window using window.postMessage() JavaScript method, and then waits for the main window to return the result in the same way. Timeout of this mechanism is 10 seconds, so CIF API considers the request as failed after not receiving any response in 10 secs, even if it actually succeeds after the timeout. As a result, retrying might fetch the same record multiple times from Dynamics, so this API feature must be used only if it doesn’t cause serious problems.

The purpose and usage of the method is identical to the underlying API provided by Microsoft, the only addition is the retry logic.

Enreach.API.Xrm.execute

(Available from v1.5.2 on)

Executes a request (e.g. an action) against Dynamics API.

Parameters:

data: the data (payload) to be sent to the API
metaData: the metadata of the request

This API function utilizes the same window.postMessage() mechanism as all the rest of Xrm API functions.

According to Microsoft’s documentation, when executing requests, metadata retrieval happens by adding a getMetadata() function to the prototype of the request function.

Request data is serialized to JSON and then sent to a sub-page for processing, using window.postMessage(). Since functions like getMetadata() couldn't be serialized, data and metaData objects have to be passed separately. The final query object with getMetadata() function is assembled within the sub-page which is handling request execution.

Example code to execute a WhoAmIRequest in a custom plugin:

var SampleCustomer = SampleCustomer || {};
SampleCustomer.Plugins = SampleCustomer.Plugins || {};

SampleCustomer.Plugins.whoAmI = async function (context) {
    var requestData = {};

    var metadata = {
        boundParameter: null,
        parameterTypes: {},
        operationType: 1, // This is a function. Use '0' for actions and '2' for CRUD
        operationName: "WhoAmI",
    };

    var response = await Enreach.API.Xrm.execute(requestData, metadata);
    console.log("Your user id is " + response.UserId);
};