Node-RED: OData processor, based on MSDynamics Nodes

This repository containes as general way of performing odata webapi queries based on the msdynamics-contact-lookup Node-RED node, designed to lookup a contact in MS Dynamics based on a phone number. Authentication with Microsoft Dynamics 365 is handeled by a built-in configuration node. This simplifies the process of managing authentication tokens, ensuring seamless integration with Dynamics 365 APIs and paves the way for easier addition of new nodes.

Extensions have been made to be able to perform all sorts of CRUD queries, also retrieval of large datasets, using paging url's.

OData Processor.

Performs CRUD operations on the endpoint

Inputs and Outputs

Input: all operations rely on the properties of the input message.
msg = {
"debug":true, //shows the used url in the console log
"entitySetName":"contacts", // including the 's' at the end
"query":"$filter=telephone1%20eq%20'6348186468'&$select=firstname,lastname,emailaddress1",
"method":"GET", // GET,POST,PATCH,DELETE
"keys": "rowid=rowkeyvalue",
"odataPayload":{ // only required for POST,PATCH
"data1":"value1"
},
"pageSize":500, // if you want to change the default, optional
,"url":"link to the next set of paged results." // url you got from the previous result
}

Required/optional properties per operation:
GET : 'url' or 'entitySetName', 'query', optional : 'pagesize'
POST : 'entitySetName', 'keys', 'odataPayload'
DELETE : 'entitySetName', 'keys'
PATCH : 'entitySetName', 'keys', 'odataPayload'

The url property overrides entitySetName and query properties. This is provided to get the next page of results.
depending on the operation, property odataPayload is sent with the request as required data (create or update).

Outputs: output of the operation, sometimes only the status, sometimes data, in the body property, including a link to the next set of data is paging limits are exceeded.

Configuration

- OData Connection: Select the OData configuration node.
- Lookup Timeout: Time in milliseconds before the lookup request is aborted (default 3000 ms).

Configuration Node

This configuration manages authentication with Microsoft Dynamics by handling access token generation and refresh. Nodes that use it can reuse the token and connection configuration to Dynamics directly. If using the standard nodes that come with this bundle, you do not need to take care of tokens, etc.
For use cases where you want to build aditional lookups that are not part of the functionality that comes with the nodes in this bundle, the refreshed access token can optionally be made availalbe in the Node-RED global context under the key msDynamicsToken, which includes the accessToken string, the expiresAt timestamp and the instanceUrl.

Features:

- Simplified authentication with Microsoft Dynamics 365.
- Automatic and configurable token refresh intervals.
- Secure handling of credentials.

Configuration

- Client ID and Secret: Provide the Client ID and Secret from your Microsoft Dynamics 365 app registration.
- Tenant ID and Instance URL: Specify your Dynamics 365 Tenant ID and the URL of your instance.
- Refresh Interval (minutes): Set the interval for how often the token should be refreshed.
- Retry Interval (minutes): Configure the retry interval in case of token refresh failure.
- Write to Global Context: Write token information to a global context object.
- Global Context Storage Key: The key for the global context variable under which you want the token information to be written. Default is msDynamicsToken.

_Configuration example of the MS Dynamics Connection Configuration node._

Usage

The Connection settings are done via one of the standard nodes in this bundle. Deploy one of them and in the settings from the "Dynamics Connection" menu select "add new...". Configure the necessary credentials and settings. The node handles authentication with Dynamics 365 and ensures that the token is refreshed as required. Token refresh is also triggered every time the flow is deployed or Node-RED restarts.

Token information is optionally stored in the Node-RED global context under the key msDynamicsToken which contains the following fields:

- accessToken
- expiresAt
- instanceUrl

To directly access the accessToken in your flows, use the following code snippet:

``javascript
const accessToken = global.get("msDynamicsToken.accessToken");
``

Storing token information in the global context is not needed when using the standard nodes that come in this bundle as they have direct access to the token.

_Example of token data in Node-RED's global context._

Notes

Security Note: Storing sensitive information like access tokens in the global context allows any node in the flow to access it. Ensure to follow best security practices in handling such sensitive information.
Configuration Note: The fields for Token Endpoint, Grant Type, Scope Suffix, and Host have default values that are suitable for most use cases. Only modify these if your specific Microsoft Dynamics setup requires different values.

License

This project is licensed under the MIT License.

Acknowledgments

This node is based on https://flows.nodered.org/node/@dastoyan/node-red-msdynamics, by https://flows.nodered.org/user/dastoyan and adapted for my needs.

This Node-RED node was developed as part of my work at Anywhere365 and an initiative to integrate Dynamics 365 more efficiently within the Dialogue Studio low-code environment which uses a custom version of Node-RED.

Disclaimer

- No Warranty: This node is provided "as is" without any warranties of any kind, either express or implied. Users are responsible for testing and validating its functionality in their specific environment.