New: Cybus Helm Charts 3.0.0.
Learn more.
Ctrlk
Contact Uscybus.io
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Microsoft Dynamics 365 Integration

How to integrate Microsoft Dynamics 365 with Connectware, including Entra ID authentication, creating Dataverse rows from shop floor data, and polling Dataverse tables with OData queries.

This guide describes how to integrate Microsoft Dynamics 365 with Connectware. You configure a service commissioning file that creates rows in a Microsoft Dataverse table from shop floor data and polls a Dataverse table with an OData query in return. A complete example file is available at the end of this guide.

Objectives

  • Establishing an OAuth-authenticated connection between Connectware and the Dataverse Web API.

  • Creating rows in a Dataverse table from shop floor data.

  • Polling a Dataverse table with an OData query.

Prerequisites

To follow this guide, you will need the following:

  • A running instance of Cybus Connectware.

  • A Microsoft Dynamics 365 environment that stores its data in Microsoft Dataverse (for example, Sales, Customer Service, or Field Service).

  • Administrator privileges in Microsoft Entra ID to register an application, and in the Power Platform admin center to create an application user.

  • Access to the Admin UI with sufficient user permissions.

  • Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, and endpoints).

Connectware and Microsoft Dynamics 365 Integration

Dynamics 365 applications such as Sales, Customer Service, and Field Service store their business data in Microsoft Dataverse. Dataverse exposes this data through the Web API, an OData v4 REST interface available at https://<environment>.api.crm.dynamics.com/api/data/v9.2/. Connectware communicates with the Web API through the HTTP/REST connector, which handles token retrieval and renewal automatically.

This guide uses a custom Dataverse table named Quality Event as an example:

  • Shop floor to Dynamics 365: Machines publish quality events to MQTT topics, and Connectware creates one table row per event. Quality engineers then work with the records in Dynamics 365, in Power Automate flows, or in Power BI reports.

  • Dynamics 365 to shop floor: Connectware polls the table with an OData query and publishes the result to an MQTT topic, so shop floor systems receive changes made in Dynamics 365.

The same patterns apply to any Dataverse table, standard or custom.

The MQTT topics in this guide follow an ISA-95-style equipment hierarchy (<enterprise>/<site>/<area>/<line>/<cell>). The mappings subscribe with wildcards across all levels, so any machine in the hierarchy is picked up without changing the integration.

App Registration and Application User

Connectware authenticates against the Dataverse Web API as a service principal, using the OAuth 2.0 client credentials grant with Microsoft Entra ID. This requires an app registration in Microsoft Entra ID and an application user in your Dataverse environment:

  1. Register an application in Microsoft Entra ID and create a client secret for it. Record the Application (client) ID, the Directory (tenant) ID, and the client secret. For detailed steps, see Use single-tenant server-to-server authentication in the Microsoft documentation.

  2. In the Power Platform admin center, create an application user that is bound to the app registration and assign it a security role that grants create and read privileges on the target table. For detailed steps, see Create an application user in the Microsoft documentation.

  3. Look up the Web API endpoint of your environment in Power Apps under Settings > Developer resources. For more information, see View developer resources in the Microsoft documentation.

Dynamics 365 Connection Properties

The connection to the Dataverse Web API requires values from your environment and your app registration. We add them as parameters to the service commissioning file, so you can set them when you install the service.

Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.

  • dataverseApiHost: The host name of the Web API endpoint of your environment, without the scheme. For example, example.api.crm.dynamics.com.

  • environmentUrl: The URL of your environment, shown as the instance URL on the Developer resources page. Connectware requests the OAuth token for this URL. For example, https://example.crm.dynamics.com.

  • tenantId: The Directory (tenant) ID of your Microsoft Entra ID tenant.

  • clientId and clientSecret: The Application (client) ID and the client secret of the app registration.

  • entitySetName: The entity set name of the target table. For example, cr123_qualityevents.

  • pollInterval: The polling interval for the Dataverse table in milliseconds.

  • topicRoot: The root of the MQTT topic hierarchy. Defaults to enterprise.

Dynamics 365 Connection

To connect to the Dataverse Web API, we set up a Cybus::Connection resource that uses the HTTP/REST connector with the OAuth 2.0 Client Credentials Grant. The prefix property applies the Web API base path /api/data/v9.2 to all endpoints of the connection, so the endpoint paths only contain the entity set names. The headers property adds the headers that Microsoft recommends for all Dataverse Web API requests.

Microsoft Entra ID must know which API a requested token is for. The v2.0 token endpoint expects this information in a scope parameter (https://<environment>.crm.dynamics.com/.default), which the oauthClientCredentials property does not provide. This guide therefore uses the v1.0 token endpoint (https://login.microsoftonline.com/<tenant-id>/oauth2/token), which identifies the target API through a resource value instead. The audience property of the connection carries the environment URL for this purpose. If the connection does not reach the Connected state and the service logs show an AADSTS error from the token endpoint, your Connectware version does not transmit this value with the token request. In that case, use a static access token as described in Using a Static Access Token.

Using a Static Access Token

You can authenticate with a token that you obtain outside of Connectware instead of the oauthClientCredentials property. Request the token from the v1.0 token endpoint of your tenant, with the environment URL as the resource value:

Replace ${TENANT_ID}, ${CLIENT_ID}, and ${CLIENT_SECRET} with the values of your app registration, and https://example.crm.dynamics.com with the URL of your environment. Copy the access_token value from the response and pass it as an Authorization header in the connection instead of the oauthClientCredentials property:

Access tokens from Microsoft Entra ID expire after about one hour, so this option is only suitable for testing and troubleshooting.

Creating Dataverse Rows from Shop Floor Data

To create a table row, the Dataverse Web API expects a POST request to the entity set of the table, with the column values as the JSON request body. To find the entity set name, open your table in Power Apps and select Advanced > Tools > Copy set name.

We define a write endpoint for the entity set and a mapping that feeds it from the MQTT topic hierarchy. The HTTP/REST connector expects the request body in the body property of the message (see Publishing Data to REST Servers). The transform rule wraps the incoming payload accordingly, so machines can publish their data without knowing about this convention.

Any message published to a matching topic, for example enterprise/hamburg/assembly/line-1/press-01/quality-events, now creates one row in the table. The property names in the payload are the logical names of the table columns, in lowercase and including the publisher prefix. The examples in this guide use the placeholder prefix cr123, replace it with the prefix of your solution publisher:

Dataverse responds with the status 204 No Content and returns the URI of the created row in the OData-EntityId response header. Connectware publishes the result of every request to the /res topic of the endpoint.

Polling a Dataverse Table with an OData Query

To read data from Dynamics 365, we define a subscribe endpoint that polls the table at the configured interval (see Subscribing to Data). The query property adds OData query options to the GET request: $select limits the returned columns, $filter returns only active rows, and $orderby with $top returns the ten most recently changed rows.

Connectware wraps every poll result in a JSON structure with a timestamp (see Response Message Format). The rows of the table arrive in the value array of the OData response:

Verifying the Integration

  1. Install the service and set the parameters to the values of your environment and your app registration.

  2. Check that the connection is in the Connected state on the service details page in the Admin UI. If the connection does not reach the connected state, check the service logs for errors from the token endpoint.

  3. Publish a test message to enterprise/hamburg/assembly/line-1/press-01/quality-events, for example with an MQTT client or the Admin UI.

  4. Open the table in Power Apps or in your Dynamics 365 app and check that a new row appears with the values of the test message.

  5. Use the Data Explorer to check that the poll result arrives on the topic enterprise/dynamics-365/quality-events at the configured interval.

  6. The result of every HTTP request is published to the /res topic of the endpoint. If Dataverse rejects a request, the message on the /res topic contains an error property with the HTTP status.

Service Commissioning File Example

microsoft-dynamics-365-example.yml
4KB
Open
PreviousSAP MII IntegrationNextOracle Fusion Cloud SCM Integration

Last updated

Was this helpful?