Step 3: Add Artifacts to the Project

 

Important

Microsoft Azure BizTalk Services (MABS) is being retired, and replaced with Azure Logic Apps. If you currently use MABS, then Move from BizTalk Services to Logic Appsprovides some guidance on moving your integration solutions to Logic Apps.

If you're brand new to Logic Apps, then we suggest getting started here:

• What are logic apps

• Create your first logic app, or quickly get started using a pre-built template

• View all the available connectors you can use in your logic apps

As per the business scenario, Northwind Traders receive the insurance quotes in more than one XML format. So, the tutorial assumes that there are two schemas in which Northwind receives insurance quotes. Both schemas are compliant with the ACORD standards. Assume the schema names to be ACORDRq1.xsd and ACORDRq2.xsd. There must be two response schemas as well that are compliant with ACORD standards, one each for each request schema. The response schemas are called ACORDRs1.xsd and ACORDRs2.xsd, respectively. Finally, per the business scenario, Northwind normalizes request messages in both the formats into a schema proprietary to Northwind, called NorthwindSchema.xsd. This tutorial assumes that the schemas are in the following format:

Note

The tutorial does not get into the details of creating these schemas.

After the schemas, the second set of artifacts required in the tutorial are Transforms. The Transforms map the request messages from the ACORD schema to the request message schema that is proprietary to Northwind. To start with the tutorial requires two Transforms, one to map ACORDRq1.xsd to NorthwindSchema.xsd (let’s call this ACORDRq1_To_Northwind.trfm) and one to map ACORDRq2.xsd to NorthwindSchema.xsd (let’s call this ACORDRq2_To_Northwind.trfm). Similarly two Transforms are required to map the response from Northwind into the response messages compliant with ACORD schema. One Transform maps the response from Northwind to ACORDRs1.xsd (let’s call this Northwind_To_ACORDRs1.trfm) and the other map the response from Northwind to ACORDRs2.xsd (let’s call this Northwind_To_ACORDRs2.xsd).

The following illustration summarizes how Transforms map the different schemas.

This topic demonstrates how to create these Transforms for mapping the different source and destination schemas. The two request schemas are the same, except for the Comments node in the ACORDRq2.xsd. So, for creating Transforms for request schemas, the following procedure only demonstrates creating one Transform (from ACORDRq1.xsd to NorthwindSchema.xsd). You can follow the same steps to create the other Transform as well (from ACORDRs2.xsd to NorthwindSchemas.xsd). Moreover, because the NorthwindSchema.xsd does not have a Comments node, the node in the ACORDRq2.xsd does not have a matching node in the destination schema and hence doesn’t require mapping.

Important

All the artifacts (the five schemas and the four Transforms) used in this solution are also packaged with the Bridges_RelayServices sample. You can download the sample from the MSDN Code Gallery. You can look at those artifacts as well for a better understanding. You can also add the schemas bundled with the sample to your BizTalk Service project.

To map ACORDRq1.xsd and ACORDRq2.xsd to NorthwindSchema.xsd

1. In the Bridges_RelayServices solution, right-click the project, point to Add, and select New Item.

2. From Add New Item, select Map, enter ACORDRq1_To_Northwind.trfm for the name, and then select Add.

3. For the source schema, select ACORDRq1.xsd. For the destination schema, select NorthwindSchema.xsd. The elements in the following table are directly mapped to each other, simply by connecting the two nodes, without the use of any Map Operation.

   Node in the source schema	Node in the destination schema
   ACORDStandardVersionCd	ACORDStandardVersionCd
   RqUID	RqUID
   TransactionRequestDt	TransactionRequestDt
   CurCd	CurCd
   InsuredOrPrincipal	InsuredOrPrincipal
   QuoteAmount	QuoteAmount

4. Parent node PersPolicy node and its child node LOBCd in the source schema map to the same elements in the destination schema. However, because PersPolicy is marked as ‘unbounded’ in the schema, it can appear more than once in the XML request message. So, the Transform must have a way to map each iteration of the PersPolicy node and its child node (LOBCd) to the relevant nodes in the destination schema. The MapEach Loop operation does just that. When you connect two elements in the source and destination schema by using a MapEach Loop operation, every occurrence of the element in the source schema is mapped to the relevant occurrence of the element in the target schema. Needless to say that the relevant node in the destination schema must also be marked as ‘unbounded’, as is the case in this tutorial where the node in the destination schema is also marked as unbounded.

   Another important thing to understand about MapEach Loop, and other loop operations in general, is the concept of scopes. Like programming languages, you can create scopes within Transforms as well. All the relationships (simple mappings or ones that involve Map Operations) defined within a scope are specific to the scope. But why discuss scopes when all that’s required is a MapEach Loop operation? That’s because adding a MapEach Loop operation, by default creates a new scope. So, perform the following series of steps to add the PersPolicy and LOBCd nodes to the relevant elements in the destination schemas:

   • Map PersPolicy nodes in the source and destination schema by using a MapEach Loop Map Operation. Adding a MapEach Loop also creates a scope.

   • Within the scope, map the LOBCd nodes in the source and destination schemas.

   • Close the scope.

   1. Drag and drop the MapEach Loop Map Operation to the Transform design surface. Notice that the scope is created in the MapEach Loop operation box, as this icon denotes ().

   2. Connect the PersPolicy node in the source schema to the MapEach Loop Map Operation. Similarly, connect the PersPolicy node in the destination schema to the same Map Operation.

   3. Map the LOBCd nodes in the source and destination schema. Notice that the link snaps to go ‘through’ the MapEach Loop operation, irrespective of how you link it. That’s because the actions are still being performed in the scope that the MapEach Loop operation created.

   4. Close the scope by selecting the icon (). The icon now changes to the following: .

5. Repeat step 4 to map the PersAutoLoanBusiness node, along with its child node, in the source and destination schemas. The final mapping resembles the following:

   

   Save changes to the project.

   Note

   Follow this procedure to create the Transform ACORDRq2_To_Northwind.trfm.

To map NorthwindSchema.xsd to ACORDRs1.xsd

1. In the Bridges_Services solution, right-click the project, point to Add, and select New Item.

2. From Add New Item, select Map, enter Northwind_To_ACORDRs1.trfm for the name, and then select Add.

3. For the source schema, select NorthwindSchema.xsd. For the destination schema, select ACORDRs1.xsd. The elements in the following table are directly mapped to each other, simply by connecting the two nodes, without the use of any Map Operation.

   Node in the source schema	Node in the destination schema
   ACORDStandardVersionCd	ACORDStandardVersionCd
   RqUID	RqUID
   TransactionRequestDt	TransactionRequestDt

4. The destination schema, ACORDRs1.xsd has a node called MsgStatusCd. The MsgStatusCd node must contain the value of the MsgStatus SOAP header that is set on the response message by the relay services. The typical way to do add this header with the value would be to:

   • Create a property, for example MsgStatus, as part of the bridge configuration (Enrich stage) to extract the value from the response message header. The tutorial demonstrates how to create this property in the subsequent steps, as described at To extract and promote properties in the pre-Transform Enrich stage.

   • Use the Get Context Property Map Operation to pass the value from the MsgStatus property to the MsgStatusCd node in the response schema.

   Even though the MsgStatus property is not yet created as part of the bridge configuration, one can still go ahead and use the Map Operation. The only thing to ensure would be that the same property name is used (in this case MsgStatus) while configuring the Enrich stage in the bridge.

   1. Drag and drop a Get Context Property Map Operation on the map designer surface. Double-click the Map Operation and in the dialog box, for the Property name field, enter MsgStatus, and then select OK.

   2. Connect the Get Context Property Map Operation to the MsgStatusCd node in the destination schema. The final map resembles the following:

      

5. Save changes to the project.

To map NorthwindSchema.xsd to ACORDRs2.xsd

1. In the Bridges_Services solution, right-click the project, point to Add, and select New Item.

2. From Add New Item, select Map, enter Northwind_To_ACORDRs2.trfm for the name, and then select Add.

3. For the source schema, select NorthwindSchema.xsd. For the destination schema, select ACORDRs2.xsd. The elements in the following table are directly mapped to each other, simply by connecting the two nodes, without the use of any Map Operation.

   Node in the source schema	Node in the destination schema
   ACORDStandardVersionCd	ACORDStandardVersionCd
   RqUID	RqUID
   TransactionRequestDt	TransactionRequestDt

4. Repeat step 4 in the procedure To map NorthwindSchema.xsd to ACORDRs1.xsd to map a value to the MsgStatusCd node in the destination schema.

5. Just like ACORDRq2.xsd, ACORDRs2.xsd has a node called Comments. How to get the value for this node? Unlike MsgStatus, it’s not a value that is present in the response message header. But it’s a value that is present in the request message and can be extracted from the request message itself. To set the value for Comments property in the response message, do the following:

   • Create a property, for example Comments, as part of the bridge configuration (Enrich stage) to extract the value from Comments element in the request message. The tutorial demonstrates how to create this property in the subsequent steps, as described at To extract and promote properties in the pre-Transform Enrich stage.

   • Use the Get Context Property Map Operation to pass the value from the Comments property to the Comments node in the response schema.

   Even though the Comments property is not yet created as part of the bridge configuration, one can still go ahead and use the Map Operation. The only thing to ensure would be that the same property name is used (in this case Comments) while configuring the Enrich stage in the bridge.

   1. Drag and drop a Get Context Property Map Operation on the Transform design surface. Double-click the Map Operation and in the dialog box, for the Property name field, enter Comments, and then select OK.

   2. Connect the Get Context Property Map Operation to the Comments node in the destination schema. The final Transform resembles the following:

      

6. Save changes to the project.

See Also

Tutorial: Using BizTalk Service Bridges to Send and Receive Messages from Service Bus Relay Service