Tutorial: Use the CData BizTalk Adapter for Azure Active Directory to run updategrams (2023)

The CData BizTalk Adapter for Azure Active Directory allows you to run SQL commands, updategrams, and stored procedures against Azure Active Directory data in BizTalk. This article provides a walkthrough of an application that uses an updategram to inject Azure Active Directory data.

1. A one-way file destination holds the XML document that contains the updategram.
2. The document is forwarded to a solicit-response send port configured on the adapter.
3. The adapter executes the command. The result of an insert includes the ID of the new record and the rows affected.
4. The response from Azure Active Directory is forwarded to a one-way file send port that writes the BizTalk message to a file.

Build the sample application

The following sections guide you through creating the sample application:

1. Generate the schema and an updategram instance
2. Configure a receiving port
3. Configure a location for receiving files
4. Configure the adapter in a solicit-response send port
5. Configure a file send port
6. Create filters to route BizTalk messages through the application
7. Fill in the locations and ports and activate them
8. View application logs

Generate the schema and an updategram instance

You can use wizards in Visual Studio to generate the schema and updategram instance:

1. Add the adapter to your project
2. Generate an insert schema
3. Generate an updategram instance

Add the adapter to your project

Use the Add Adapter Wizard to add the adapter to your project. You use the adapter to query Azure Active Directory for metadata about the table you want to insert into; for example "domains".

1. In Solution Explorer, right-click the project and click Add -> Add Generated Items.
2. In the resulting dialog box, select Add Adapter Metadata.
3. In the Add Adapter Wizard that appears, select the CData BizTalk Adapter for Azure Active Directory from the list view.
4. In the Port menu, leave the selection blank. If you want to use the connection string for an adapter that is already configured, select the send port or receive location from your BizTalk application.

Generate an insert schema

You use the schema as a template to create an updategram that injects Azure Active Directory data. The schema is an .xsd file that defines the XML request and response. As an example, we show how to generate an insert updategram. You can follow the same process to generate updates and delete updategrams.

1. On the Connection String page of the Schema Wizard, enter authentication credentials and other connection properties.
2. In the next step select the Send Port option.
3. Disable the one-way option. The one-way option ignores any responses from the adapter for the updategram, such as B. the returned AffectedRows value. The ID of the newly created row is also returned. Disabling the one-way option gives you an updategram scheme that supports ID retrieval.
4. From the Command Type menu, select Updategram.

5. Choose the Insert option and select the table and columns you want to insert into. This tutorial uses ID and AvailabilityStatus.

   note: When you create the updategram, you are limited to including the columns that you include in the schema.

   
6. On the summary page, review the settings you defined and click Finish to close the wizard.

Generate an updategram instance

In this step, you create the XML message that will be sent to the adapter in later steps. To create the updategram, right-click the .xsd file in Solution Explorer, and then click Generate Instance. The location where the updategram is saved is listed on the Output tab.

The updategram is structured to define what response is desired from Azure Active Directory. For example updategrams and more information, see the help documentation for the adapter.

Configure the receiving port

To add a receiving location to your application, you must first add a receiving port. Receive ports can receive data from multiple receiving locations.

1. Open your application in the BizTalk Server Administration Console.
2. Right-click Receive Ports and click New -> One-way Receive Port. The Receive Port Properties dialog box appears.
3. Enter a name for the receiving port.

Configure the location for receiving files

A static one-way file receive location creates a BizTalk message that contains the updategram.

1. Right-click Receiving Locations and click New -> One-Way Receiving Location.
2. Select the receiving port to which the new receiving site should belong. The Receive Location Properties dialog box appears.
3. Enter a name for the receiving location.
4. Choose FILE from the Transport Type menu.
5. Click Configure. The File Transport Properties dialog box appears.
6. In the Receive Folder field, enter the path to a folder; B. DemoOutbound. The receive location searches this folder for files that match the criteria in the File Mask field.
7. From the Receive Pipeline menu of the Receive Location Properties dialog box, select the default PassThruReceive option.

Configure the Azure Active Directory adapter in a solicit-response send port

The configuration consists of the following steps:

1. Create and configure the solicit-response send port
2. Configure the adapter
3. Configure the connection to Azure Active Directory

Create and configure the solicit-response send port

Use a solicit-response send port to get the result of an updategram command; This tutorial returns the ID of the newly inserted record in BizTalk.

1. Open your BizTalk application in the BizTalk Administration Console.
2. Right-click Send Ports and select New -> Static Solicit-Response Send Port. The Send Port Properties dialog box appears.
3. Enter a name for the send port.
4. From the Transport Type menu, select CData.AzureAD.

Configure the CData Azure Active Directory adapter

Define the command that the adapter runs in the Adapter Transport Properties dialog box.

1. In the send port properties, click the Configure button. The Adapter Transport Properties dialog box appears.
2. In the CommandType property, select Updategram.

For descriptions of the various adapter properties and their functions, see the Adapter Configuration section of the Help documentation.

Configure the connection to Azure Active Directory

Configure credentials and other properties required to connect to Azure Active Directory:

1. In the Adapter Transport Properties dialog box, click the button in the Connection String property. The Connection String Options dialog appears.

2. Enter connection properties.

   Below is a typical connection string:

   OAuthClientId=MyApplicationId;OAuthClientSecret=MySecretKey;CallbackURL=http://localhost:33333;InitiateOAuth=GETANDREFRESH

   Azure Active Directory uses the OAuth authentication standard. To authenticate with OAuth, you need to create an app to get theOAuthClientId,OAuthClientSecret, andCallback URLconnection properties. For authentication instructions, see the OAuth section of the help documentation.

3. Click Test Connection to verify the values.

For descriptions of the various connection properties and their functions, see the Connection String Options chapter in the help documentation.

Configure a file send port

The file send port writes the ID returned by the insert to a file. Complete the following steps to configure a one-way send port to write incoming messages to a file.

1. Right-click Send Ports, and then click Static Unidirectional Send Port.
2. From the Type menu, choose FILE.
3. Click Configure.
4. In the Destination Folder field, enter the path to the folder where you want the message to be written. Example: DemoInbound.

Create filters to route BizTalk messages through the application

Complete the following steps to create filter rules that define the following mappings in your application:

• Map the solicit-response send port to the BizTalk message that contains the updategram.
• Map the file send port to the BizTalk message created by the result of running the updategram.

1. In the request-response send port properties, click Filter and set the following values:

   • Property: Choose BTS.InboundTransportLocation from the menu.
   • Value: Enter the URI of the one-way receive location, in this example C:\DemoOutbound\*.xml.
   

2. In the properties of the one-way send port, click Filter and set the following values:

   • Property: Choose BTS.SPName from the menu.
   • Value: Enter the name (not URI) of the solicit-response send port.
   

Fill in the locations and ports and activate them

To ensure that the updategram is picked up from the receiving location, perform the following steps when you start your BizTalk application:

1. Right-click the solicit-response send port and click Start. This also enters the send port.
2. Right-click the one-way send port and click Start. This also enters the send port.
3. Right-click the receiving location and click Enable.

You can now copy the updategram to the folder that you configured for the receive location.

Open the folder you configured for the one-way send port: This folder contains the new ID in an XML file. The message resembles the following example:

<table xmlns="http://www.cdata.com/AzureADProvider" AffectedRows="1"> <row> <Id>0014000001XERBUAA5</Id> </row></table>

View the application logs

In the application logs, you can view error messages and quickly verify that your application initialized successfully. To open the logs, expand the Event Viewer (local) node in the navigation tree in the management console. Expand Windows Logs and select Application.

A list of the errors that have occurred can be found here. This includes error messages for all applications on the system, so it's important to check the source of the error message. For the receive location, the source should be "CData BizTalk AzureAD Receive Adapter". Details of the error message should shed light on why the error occurs.

Contactsupport@cdata.comfor instructions on how to fix the error.