Itineraries details
Itineraries
The way Link messages flow in BizTalk is based on a concept called Itineraries. An itinerary consists of a sequence of itinerary steps. In most cases an itinerary step will take form of an orchestration. A message will go through two itineraries: one inbound and one outbound. The inbound itinerary will consist of the necessary steps to transform the received message to the defined CMD format, and the outbound itinerary will contain the steps needed to transform the CMD to the desired output. This way the inbound and outbound message formats are loosely coupled.
There is a key context property within the Link framework that is used for message routing called Next (namespace: http://Ebex.EdiPortal.Common.BizTalkCommonProperty.FlowControl). The concept is that the Link disassembler promotes the value from the first itinerary step of the inbound itinerary. And thereafter each step, whether it is implemented as an orchestration or a send port, needs to call a method in the framework to get the next itinerary step, and promote it to the Next property. This continues until the last itinerary step of the outbound itinerary. If a step is the last one, it should not submit the message back to the message box.
If you are defining an outbound message format that supports message batching, it will have two outbound itineraries; one for batching and one for non-batching. One of them will be used when processing a message depending on the configuration of the receiver partner.
Itinerary steps can have parameters that are based on the input or output message formats (depending on if it is a part of the ingoing of outgoing itinerary).
Included in Link
The following itinerary steps are included in the framework:
- TransformToCdm
Executes a defined sequence of maps and send pipelines in order to get from the inbound message format to the CDM format. These maps and pipelines are set up as a parameter for the itinerary step. - TrackCdm
Tracks defined tracking fields from the message body of the CDM document. These are defined as XPath statements when defining a new document type. These fields can be used for searching in the user interface. - TransformFromCdm
Very much like the TransformToCdm step. This also executes a transformation logic which consists of a sequence of maps and send pipelines. - Batch
Concatenates messages under a new root node. The root node, and its namespace is defined with the outgoing message format (DocumentConfig in the Link Administration Tool). - Assemble
Here the message is assembled in the state it should be in, when it is sent to the receiving partner. Meaning that if the output message is a positioned text file, the flat file assembler will be executed. - Send
The message is sent to the receiving partner based on the transport configurations set up on the distribution in the Link front-end.
Based on these steps the following itineraries are included in the Link.
- Inbound itineraries:
- ToCdm_Standard: TranformToCdm à TrackCdm
- Outbound itineraries:
- FromCdm_Standard: TransformFromCdm à Assemble à Send
- FromCdm_Batch: TransformFromCdm à Batch à Assemble à Send
It is very easy to create new itineraries through the Link Administration Tool. But in most scenarios the three mentioned itineraries will be sufficient. This is explained in the chapter about using the Link Administration Tool.
Parameters for Itinerary Steps
Itinerary steps can take parameters.
- SND_PL
- MAP
- SCHEMATRON
Parameters seperated by ; and parameter values seperated by %
When you create a specific document format (DocumentConfig) with the Link Administration Tool, you can specify parameters for the steps in the selected itineraries. Of the itinerary steps that are included in the Link framework, the following take parameters:
- TransformToCdm and TransformFromCdm.
The parameter for these two steps specifies the steps a message needs to go through in order to be transformed to the desired target format. Either the CDM or the output format. The transformation is a sequence of steps, where each step can be a BizTalk map, a send pipeline or a Schematron validation. The parameter string is a sequence of these steps separated by a semicolon where each step uses the syntax: “<Type>%<Value>”. Type can be MAP, SND_PL or SCHEMATRON, and the value will be a fully qualified type name of the map or pipeline to be executed, except for when using schematron. The schematron validation can be used in two ways: It can be specified as a embedded .NET resource in an assembly installed in the Global Assembly Cache, or it can point to a schematron file, placed somewhere that the BizTalk service account can access. If the schematron file is looked up as an embedded resource, the value part of that step is prefixed with embedded:// and followed by the syntax: <fully qualified assembly name>$. If it uses the file system it should be prefixed with file:// and followed by a path to the schematron file. An example of an itinerary step parameter for TransformFromCdm where the message is validated using schematron, then transformed with a BizTalk map:
SCHEMATRON%embedded://SomeCompany.BizTalk.Object.SalesInvoice.Schemas_CDM_SalesInvoice.Schemas, Version=1.0.0.0, Culture=neutral, PublicKeyToken=da6813e38f94ddd7$SomeCompany.BizTalk.Object.SalesInvoice.Schemas_CDM_SalesInvoice.Schemas.Schematron.CdmSalesInvoice_Schematron_Validation.sch;MAP%SomeCompany.BizTalk.Object.SalesInvoice.Map_CDM_to_EDIFACT_INVOIC_D96A.Transforms.Map_CdmSalesInvoice_to_EDIFACT_INVOIC_D96A_UN_EAN008, SomeCompany.BizTalk.Object.SalesInvoice.Map_CDM_to_EDIFACT_INVOIC_D96A.Transforms, Version=1.0.0.0, Culture=neutral, PublicKeyToken=da6813e38f94ddd7
These parameters are configured for Document Configs that applies data transformation. In the cases where the parameter only contains a Biztalk map (which is quite often), the Link Administration Tool can help you create this string. - Assemble.
If the standard pipeline for assembling your outbound message based on its Format Type is not sufficient, you can specify a pipeline a parameter for the Assemble step. Specifying a send pipeline as a parameter is done with the same syntax as with the transform steps: SND_PL%<fully qualified pipeline type name>. If no parameter is specified for this step, the standard pipeline for the given Format Type will be executed. MAP% can also be used for instance to apply an xml envelope.
Implementing custom itinerary steps
When you need to implement a new itinerary step, you first need to create a new itinerary step through the Link Administration Tool, and create itineraries that include it. Here are some steps and guidelines for implementing an orchestration that acts as an itinerary step in Link.
Start by referencing the assembly "EdiPortal.Common.BizTalkCommonPropertySchemas" in your new orchestration.
We recommend that you at least create three new status types that can be logged. One indicating that the itinerary step has been started, one that it has been completed, and one that it has failed its processing. In the itinerary steps that is included in the Link we have used the following syntaxes for these statuses:
- “<itinerary_step_name> started”
- “<itinerary_step_name> completed”
- “<itinerary_step_name> failed”
These status types must belong to the group "Document flow".
Doing this will create better transparency, since you can see user interface how long a message is in its flow.
- Use direct binding for logical receive port.
- Wrap all of you orchestration shapes in a Scope, so that we can catch all exceptions.
- In the receive shape that is connected to the logical receive port, Activate must be set to True to get the message received to instantiate a new instance. You must also create a filter expression.
A clause in the filter expression must be that the value of the “Next” property must be equal to the name of the new itinerary step.
4. Log a status indicating that the itinerary step has been started (recommended).
DocumentsId = messageIn(Ebex.EdiPortal.Common.BizTalkCommonProperty.DocumentsId);
Ebex.EdiPortal.Common.Tracking.Document.SetStatusByDocumentsId(DocumentsId, "CustomProces started", "", Ebex.EdiPortal.Common.Configuration.EdiPortalConfiguration.BizTalkEdiPortalUsersId); 
5. Now you can implement the logic you want to be executed for this itinerary step. There are a few things of importance. You can’t submit the received message back to the message box, since it will have the same “Next” value, and will be consumed by the same orchestration again. Therefore when creating the output message there are the following requirements:
First you create the new itinerary object with all of its variables in an expression shape copying the information from the incoming message.
The variables itineraryStringVariable, itineraryActualVariable and itineraryNextStringVariable are in the System.String format, while the itineraryVariable is of the type Ebex.EdiPortal.Common.Business.FlowControl.Itinerary.
// Itinerary object
itineraryVariable = new Ebex.EdiPortal.Common.Business.FlowControl.Itinerary(messageIn(Ebex.EdiPortal.Common.BizTalkCommonProperty.Itinerary), messageIn(Ebex.EdiPortal.Common.BizTalkCommonProperty.ActualItinerary));
// Set Itinerary
itineraryStringVariable = itineraryVariable.ItineraryFull;
// Set Actual Itinerary
itineraryActualVariable = itineraryVariable.ActualItinerary;
// Set previous and next properties to control flow
itineraryNextStringVariable = itineraryVariable.Next;
Instantiate the outgoing message in a construction shape and add all of the context properties to it.
messageOut = messageIn;
messageOut(*) = messageIn(*);Finally update the context properties of the outgoing message.
messageOut(Ebex.EdiPortal.Common.BizTalkCommonProperty.ActualItinerary) = itineraryActualVariable;
messageOut(Ebex.EdiPortal.Common.BizTalkCommonProperty.Itinerary) = itineraryStringVariable;
messageOut(Ebex.EdiPortal.Common.BizTalkCommonProperty.Next) = itineraryNextStringVariable;Log a status indicating that the itinerary step has been completed (recommended).
Ebex.EdiPortal.Common.Tracking.Document.SetStatusByDocumentsId(DocumentsId, "CustomProces completed", "", Ebex.EdiPortal.Common.Configuration.EdiPortalConfiguration.BizTalkEdiPortalUsersId)
When submitting the message back to the BizTalk’s message box, there are some context properties that need to be promoted for routing purposes. So use a CorrelationSet with the following context properties, and use it as Initiating correlation set on the send shape:
Ebex.EdiPortal.Common.BizTalkCommonProperty.BatchingKey
Ebex.EdiPortal.Common.BizTalkCommonProperty.FlowConvoy
Ebex.EdiPortal.Common.BizTalkCommonProperty.Next
Ebex.EdiPortal.Common.BizTalkCommonProperty.TransportConvoyKey
Log a status indicating that the itinerary step has failed (recommended).
Call the orchestration ErrorHandlingOneMsg. It takes two paramteters: one the message received by the orchestration, and an exception. This will set the document in the Link in the failed state, and provide error details in the user interface. If you throw exceptions of type Ebex.EdiPortal.Common.Exceptions.FlowException with a proper error code, a technical and a non-technical error description will be shown as well as potential causes and solutions.
