OAGIS and BizTalk walk through (PurchaseOrder) - Part 1

OAGIS and BizTalk walk through using AcknowledgePurchaseOrder, ConfirmBOD and ProcessPurchaseOrder Business Object Documents

About OAGIS

OAGIS is the common content model needed to represent messages that enable communication between business applications, whether the messages are application-to-application (A2A), business-to-business (B2B), or vertical industry- to-vertical industry (V2V) in nature. In short, OAGIS enables everywhere-to-everywhere integration.


OAGIS provides a common data model that provides a common basis of understanding, allowing all the applications involved in the information exchange to understand the intent of the message. The messaging specifications are analogous to the envelope. The integration engine used to transport and route the message is analogous to the postal service. The message and message format are analogous to OAGIS, which enables the understanding of the information on each end.

Understand OAGIS Schema and XML design

The common XML message structure provided by OAGIS is the Business Object Document (BOD,) which provides a message architecture based on the following reusable components:

Nouns - Nouns describe a common business object and are composed of Components, which are basic building blocks shared across all Nouns.

Verbs - Verbs describe the action to be applied to the Noun.

For example, the ProcessPurchaseOrder BOD is constructed from the PurchaseOrder Noun and the Process Verb. All BOD messages are based on common Nouns combined with a Verb.
During a document’s lifecycle, the Noun may be combined with various Verbs to achieve portions of a business process. You may send your partner a ProcessPurchaseOrder, the partner responds with an AcknowledgePurchaseOrder and you later may need to issue a ChangePurchaseOrder. All three messages would use the same Noun to describe the Purchase Order.
Additionally, all BODs contain an application area with information that can be used by the processing infrastructure for routing, authorization and receipt verification. 

Implementing BODs with BizTalk Server

Because OAGIS BODs are native XSD based schemas, you can directly use them within BizTalk projects with only minor modifications to the schemas. BizTalk projects are compiled into .NET assemblies during which the XSD schemas are compiled into classes. Due to this compilation of the schemas, the following changes must be made:

XSD Include and Import statements must be changed from file path to assembly reference when referencing schemas in a separate assembly.
Set the Root Reference property for Noun and BOD schemas to reduce the number of .NET classes created during compilation. This also determines which node the BizTalk Mapper will use as the document root

Creating Schema Projects

The recommended method of using BODs within BizTalk projects is to separate the Components into one project, Nouns into another project, and BODs into one or more projects. This modular approach mirrors the architecture of OAGIS and also reduces the number of items that need to be built and deployed when a new Noun or BOD needs to be implemented. The following steps demonstrate how to create BizTalk projects to implement OAGIS schemas within BizTalk Server:

Create Component Project

Download and extract the OAGIS schemas from http://www.oagi.org/. This archive contains the OAGIS schemas that will be used in the BizTalk projects. These steps are based on OAGIS Release 9.4. Similar steps can be used for other OAGIS releases.

In Microsoft Visual Studio 2010, create a new BizTalk project named “Component_Schemas.” This schema will contain the OAGIS Component schemas.

In Windows Explorer, navigate to the OAGIS schemas and find the Components folder. Copy the contents of this folder to your BizTalk project directory.

In Solution Explorer, select Show All Files. This should display the files and folders copied from the OAGIS Components folder.

Select each of the Component files and folders, and then right-click Include In Project. Deselect Show All Files to hide files not included in the project.

Add strong key to Project, build and Deploy.

Create Noun Project

In Microsoft Visual Studio 2010, create a new BizTalk project named “Noun_Schemas.”
In Solution Explorer, right-click the project name and select Add Reference. Select the Browse tab, browse to the Component_Schemas.dll assembly, and then click OK.

Right-click the project name, select Add, and then select Existing Item. Browse to and select the OAGIS Nouns: PurchaseOrder.xsd, BOD.xsd.

In Solution Explorer, double-click BOD.xsd. Click OK on the dialog box stating that this is an invalid XSD Schema. The BOD.xsd schema should appear. The schema is initially invalid as it contains XSD include statements that reference non-existent files. The following steps will modify the schema to use assembly references to resolve this error.

In the BOD.xsd schema, select the <Schema> node and then select Imports field, click the ellipsis (…) button.

In the Imports dialog box, find the rows that have XSD Include in the Import Type column. For these rows, note the file name specified in the Location column.

In the Import new schema as drop-down list, select XSD Include, and then click Add.

In the BizTalk Type Picker dialog box, expand the Project name, and then expand References. Expand the assembly reference that contains the Component schemas, expand the Schemas entry and then select the schema that matches the current XSD Include. Click OK.

There should now be two XSD Includes for each included Components schema: one with a file path in the Location column and a second with an assembly reference. Select the entries that contain a file location and click the X button to remove this entry. After all rows containing file locations have been removed, click OK.

Select the Root Reference field and in the drop-down list, select the entry that matches the Noun. For example, if the Noun schema is BOD, select the BOD entry.

Repeat the above steps for the PurchaseOrder schema.

Add strong key and deploy the Project.

Create BOD project

In Microsoft Visual Studio 2010, create a new BizTalk project named “BOD_Schemas.”

In Solution Explorer, right-click the project name and select Add Reference. Select the Browse tab and browse and select the Noun_Schemas.dll and Component_Schemas.dll assemblies. Click OK.
Right-click the project name, select Add, and then select Existing Item. Browse and select the OAGIS BODs: ConfirmBOD.xsd, AcknowledgePurchaseOrder.xsd, ProcessPurchaseOrder.xsd

In Solution Explorer, double-click AcknowledgePurchaseOrder.xsd. Click OK on the dialog box stating that this is an invalid XSD Schema, and the AcknowledgePurchaseOrder.xsd schema should appear.

In the AcknowledgePurchaseOrder.xsd schema, select the <Schema> node and perform the following steps in Properties:

- Select the Imports field, and then click the ellipsis (…) button.

- In the Imports dialog box, find the rows that have XSD Include in the Import Type column. For these rows, note the file name specified in the Location column.

- In the Import new schema as drop-down list, select XSD Include, and then click Add.

- In the BizTalk Type Picker dialog box, expand <Project name> and then expand References. Expand the assembly reference that contains the Noun schemas, expand the Schemas entry, and then select the schema that matches the current XSD Include. Click OK.

- There should now be two XSD Includes for each included Components schema; one with a file path in the Location column and a second with an assembly reference. Select the entries that contain a file location and click the X button to delete this entry. After all rows containing file locations have been removed click OK.

- Select the Root Reference field, and in the drop-down list, select the entry that matches the Noun. For example, if the BOD schema is AcknowledgePurchaseOrder, select the AcknowledgePurchaseOrder entry.

Repeat the above steps for the ConfirmBOD and ProcessPurchaseOrder schemas.

The following procedures describe the process of promoting two properties within the BOD project created previously. These properties will be used in an orchestration project in a later procedure.

In Microsoft Visual Studio 2010, open the BizTalk BOD_Schemas project.

In Solution Explorer, right-click the project name, select Add, and then select New Item.
In the Add New Item dialog box, select Schema Files in the Categories pane, and then select Property Schema from the Templates pane. Click Add.

In the PropertySchema.xsd, right-click the <Schema> node and add the as Child Field Elements: ConfirmationCode, LogicalID

After adding these elements, save and close the PropertySchema.xsd.

In Solution Explorer, right-click the ProcessPurchaseOrder.xsd and select Open.

In the left pane, select and expand the ProcessPurchaseOrder node and then expand the first <Sequence> node. Expand the ApplicationArea node, and then expand the Sender node.

Right-click the ConfirmationCode node, select Promote, and then select Show Promotions.
In the Promote Properties dialog box, select the Property Fields tab, and then click the Add a new Property Schema button.

In the BizTalk Type Picker dialog box, expand the Schemas entry, and then select the PropertySchema entry. Click OK.

Highlight ConfirmationCode, and then click Add. This creates a new entry in the Property fields list.
In the Property fields list, select the property created for Confirmation code and in the drop-down list, select ns0:ConfirmationCode. This selects the appropriate entry in the PropertySchema.xsd to use for this property.

In the left pane of the Promote Properties dialog box, select the ProcessPurchaseOrder\<Sequence>\ApplicationArea\Sender\LogicalID node, and then click Add.
Ensure that the Property entry for this field is selected on ns0:LogicalID.

Click OK, and then save the ProcessPurchaseOrder.xsd.

Add strong key to Project, build and Deploy.

In Next step we will take folloing business scenario and integrate end to end.

"We are receiving a ProcessPurchaseOrder BOD from a partner. The incoming message is received from a file location and passed into the BizTalk messaging engine, which activates a new orchestration to process this message. The orchestration will inspect the value of the ConfirmationCode element to determine the circumstances in which a ConfirmBOD message should be sent. A map will be used to generate an AcknowledgePurchaseOrder and ConfirmBOD (if needed,) message. The orchestration will then send the message(s) to the trade partner, using the value of the LogicalID node as the address of the send port."

.....state tune for next post