Integrate with Logic Apps using a custom connector
Azure Logic Apps is a cloud service that helps you automate workflows across apps and services. By connecting Logic Apps to the Azure Digital Twins APIs, you can create such automated flows around Azure Digital Twins and their data.
Azure Digital Twins doesn't currently have a certified (pre-built) connector for Logic Apps. Instead, the current process for using Logic Apps with Azure Digital Twins is to create a custom Logic Apps connector, using a custom Azure Digital Twins Swagger definition file that has been modified to work with Logic Apps.
There are multiple versions of the Swagger definition file contained in the custom Swagger sample linked above. The latest version will be found in the subfolder with the most recent date, but earlier versions contained in the sample are also still supported.
In this article, you'll use the Azure portal to create a custom connector that can be used to connect Logic Apps to an Azure Digital Twins instance. You'll then create a logic app that uses this connection for an example scenario, in which events triggered by a timer will automatically update a twin in your Azure Digital Twins instance.
You also need to complete the following items as part of prerequisite setup. The rest of this section will walk you through these steps:
- Set up an Azure Digital Twins instance
- Add a digital twin
- Set up an Azure Active Directory (Azure AD) app registration
Set up Azure Digital Twins instance
To work with Azure Digital Twins in this article, you first need to set up an Azure Digital Twins instance. You also need the required permissions for using it. If you already have an Azure Digital Twins instance set up, you can use it instead.
Otherwise, follow the instructions in Set up an instance and authentication. The instructions contain information to help you verify that you've completed each step successfully.
After you set up your instance, make a note of the following values. You'll need these values to connect to the instance later:
- The instance's host name. You can find the host name in the Azure portal.
- The Azure subscription that you used to create the instance. Either its name or its ID will work. You can find the subscription on your instance's Overview page in the Azure portal.
Add a digital twin
This article uses Logic Apps to update a twin in your Azure Digital Twins instance. To continue, you should add at least one twin in your instance.
You'll need the Twin ID of a twin in your instance that you've created.
Set up app registration
To authenticate all the resources used in this article, you'll need to set up an Azure Active Directory (Azure AD) app registration. Follow the instructions in Create an app registration to set this up.
Once you have an app registration, you'll need the registration's Application (client) ID, Directory (tenant) ID, and client secret (find in the Azure portal). Take note of these values to use them later to grant access to the Azure Digital Twins APIs.
Create custom Logic Apps connector
Now, you're ready to create a custom Logic Apps connector for the Azure Digital Twins APIs. Doing so will let you hook up Azure Digital Twins when creating a logic app in the next section.
Navigate to the Logic Apps Custom Connector page in the Azure portal (you can use this link or search for it in the portal search bar). Select + Create.
In the Create logic apps custom connector page that follows, select your subscription and resource group, and a name and deployment location for your new connector. Select Review + create.
Doing so will take you to the Review + create tab, where you can select Create at the bottom to create your resource.
You'll be taken to the deployment page for the connector. When it's finished deploying, select the Go to resource button to view the connector's details in the portal.
Configure connector for Azure Digital Twins
Next, you'll configure the connector you've created to reach Azure Digital Twins.
First, download a custom Azure Digital Twins Swagger that has been modified to work with Logic Apps. Download the Azure Digital Twins custom Swaggers (Logic Apps connector) sample by selecting the Download ZIP button. Navigate to the downloaded Azure_Digital_Twins_custom_Swaggers__Logic_Apps_connector_.zip folder and unzip it.
The custom Swagger for this tutorial is located in the digital-twins-custom-swaggers-main\LogicApps folder. This folder contains subfolders called stable and preview, both of which hold different versions of the Swagger organized by date. The folder with the most recent date will contain the latest copy of the Swagger definition file. Whichever version you select, the Swagger file is named digitaltwins.json.
Unless you're working with a preview feature, it's generally recommended to use the most recent stable version of the Swagger file. However, earlier versions and preview versions of the Swagger file are also still supported.
Next, go to your connector's Overview page in the Azure portal and select Edit.
In the Edit Logic Apps Custom Connector page that follows, configure this information:
- Custom connectors
- API Endpoint: REST (leave default)
- Import mode: OpenAPI file (leave default)
- File: This configuration will be the custom Swagger file you downloaded earlier. Select Import, locate the file on your machine (Azure_Digital_Twins_custom_Swaggers__Logic_Apps_connector_\LogicApps...\digitaltwins.json), and select Open.
- General information
- Icon: Upload an icon that you like.
- Icon background color: Enter hexadecimal code in the format '#xxxxxx' for your color.
- Description: Fill whatever values you want.
- Connect via on-premises data gateway: Toggled off (leave default)
- Scheme: HTTPS (leave default)
- Host: The host name of your Azure Digital Twins instance.
- Base URL: / (leave default)
Then, select the Security button at the bottom of the window to continue to the next configuration step.
In the Security step, select Edit and configure this information:
- Authentication type: OAuth 2.0
- OAuth 2.0:
- Identity provider: Azure Active Directory
- Client ID: The Application (client) ID for the Azure AD app registration you created in Prerequisites
- Client secret: The Client secret from the app registration
- Login URL: https://login.windows.net (leave default)
- Tenant ID: The Directory (tenant) ID for your Azure AD app registration
- Resource URL: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0
- Scope: Directory.AccessAsUser.All
- Redirect URL: (leave default for now)
The Redirect URL field says Save the custom connector to generate the redirect URL. Generate it now by selecting Update connector across the top of the pane to confirm your connector settings.
Return to the Redirect URL field and copy the value that has been generated. You'll use it in the next step.
Now you've entered all the information that is required to create your connector (no need to continue past Security to the Definition step). You can close the Edit Logic Apps Custom Connector pane.
Back on your connector's Overview page where you originally selected Edit, note that selecting Edit again will restart the entire process of entering your configuration choices. It will not populate your values from the last time you went through it, so if you want to save an updated configuration with any changed values, you must re-enter all the other values as well to avoid their being overwritten by the defaults.
Grant connector permissions in the Azure AD app
Next, use the custom connector's Redirect URL value you copied in the last step to grant the connector permissions in your Azure AD app registration.
Navigate to the App registrations page in the Azure portal and select your registration from the list.
Under Authentication from the registration's menu, add a URI.
Enter the custom connector's Redirect URL into the new field, and select the Save icon.
You're now done setting up a custom connector that can access the Azure Digital Twins APIs.
Create logic app
Next, you'll create a logic app that will use your new connector to automate Azure Digital Twins updates.
In the Azure portal, search for Logic apps in the portal search bar. Selecting it should take you to the Logic apps page. Select + Add to create a new logic app.
In the Logic App page that follows, enter your subscription and resource group. Under Instance Details select a Consumption instance type, choose a name for your logic app, and select the deployment location. Choose whether you want to enable or disable log analytics.
Select the Review + create button.
Doing so will take you to the Review + create tab, where you can review your details and select Create at the bottom to create your resource.
You'll be taken to the deployment page for the logic app. When it's finished deploying, select the Go to resource button to continue to the Logic Apps Designer, where you'll fill in the logic of the workflow.
In the Logic Apps Designer, under Start with a common trigger, select Recurrence.
In the Logic Apps Designer page that follows, change the Recurrence Frequency to Second, so that the event is triggered every 3 seconds. Selecting this frequency will make it easy to see the results later without having to wait long.
Select + New step.
Doing so will open a Choose an action box. Switch to the Custom tab. You should see your custom connector from earlier in the top box.
Select it to display the list of APIs contained in that connector. Use the search bar or scroll through the list to select DigitalTwins_Add. (The DigitalTwins_Add action is the API call used in this article, but you could also select any other API as a valid choice for a Logic Apps connection).
You may be asked to sign in with your Azure credentials to connect to the connector. If you get a Permissions requested dialogue, follow the prompts to grant consent for your app and accept.
In the new DigitalTwinsAdd box, fill the fields as follows:
- id: Fill the Twin ID of the digital twin in your instance that you want the Logic App to update.
- twin: This field is where you'll enter the body that the chosen API request requires. For DigitalTwinsUpdate, this body is in the form of JSON Patch code. For more about structuring a JSON Patch to update your twin, see the Update a digital twin section of How-to: Manage digital twins.
- api-version: The latest API version. Currently, this value is 2020-10-31.
Select Save in the Logic Apps Designer.
You can choose other operations by selecting + New step on the same window.
Query twin to see the update
Now that your logic app has been created, the twin update event you defined in the Logic Apps Designer should occur on a recurrence of every three seconds. This configured frequency means that after three seconds, you should be able to query your twin and see your new patched values reflected.
For more about querying your Azure Digital Twins instance, see Query the twin graph.
In this article, you created a logic app that regularly updates a twin in your Azure Digital Twins instance with a patch that you provided. You can try out selecting other APIs in the custom connector to create Logic Apps for various actions on your instance.
To read more about the APIs operations available and the details they require, visit Azure Digital Twins APIs and SDKs.