Recently we had a couple of defects in the development of one of our integration solutions where we hadn't handled date times correctly in relation to day light saving. When we looked for some guidance to help us it seemed that there is a fair bit of discussion around .net implications of this but little recent content about BizTalk. Probably the most useful background articles are the following:
Although the articles talk about why things happen, I thought it would be useful to walk through some common scenarios to see how the date/time may be affected in these different situations.
Before we get into that a little about our situation and what we found (forgive the diagram).
So in our situation we have an application which publishes an event (item 1 on the diagram) which has an effective date to BizTalk. BizTalk then goes back to the application which published the event and gets some information about the entities associated with the event (item 2 on the diagram). BizTalk then sends this information to application 2 (item 3 on the diagram).
In most cases things seemed to work fine, but the enrichment data is date/time specific and we found an example when the events effective date was 26th August 2010 at midnight we were hit by date time issues. The original event which was published send a message to a web service with a date time which was 2010-08-26:00:00:00:000+01:00. In the call back to the application (again via a web service) we flowed the event effective date back to the application but in the process between the two web services the date time has suddenly changed to be 2010-08-25:23:00:00:000.
We were able to easily fix this by using the .ToLocaTime() method when constructing the message to send back to the application and because all applications are in the same time zone this fixed this for us.
What I did find when troubleshooting this is that there is only certain places where the date is converted so I thought it would be worth talking through some scenarios to elaborate on other articles which explain why this is done.
For all tests I would use the below message as the input, and I'im running the tests on a VM where the current date is 28-08-2010 and the time zone is currently British Summer Time (GMT + 1 hour).
<ns0:Root xmlns:ns0="http://Bts.DateTime.Schemas.Input">
<TestDate>2010-08-28T00:00:00.000+01:00</TestDate>
</ns0:Root>
In troubleshooting our problem I wanted to put together some scenarios so we could be clear on how a DateTime value is affected by the way it is used in different situations and hopefully the following scenarios will be useful to compliment the above articles from a BizTalk perspective.
Scenario 1: Flowing a message through a messaging scenario (Pass Through)
In this scenario I have a receive location which picks up the inbound file. There is a send port subscribing to this inbound port which puts the file back into a different folder. Both ports have pass through pipelines. The below diagram illustrates this scenario.
Test Result
In this scenario I add the message below containing the BST date of midnight on the 28th and it comes out exactly the same and the date is unchanged.
<ns0:Root xmlns:ns0="http://Bts.DateTime.Schemas.Input">
<TestDate>2010-08-28T00:00:00.000+01:00</TestDate>
</ns0:Root>
Summary
A pass through messaging scenario has no effect on the message in terms of the date time.
Scenario 2: Flowing a message through a messaging scenario (Xml Disassembler)
In this scenario I have the same as above in scenario 1 where there are two file based ports. This time the inbound port has an XmlRecieve Pipeline containing the XmlDisassembler. The below diagram illustrates this scenario.
Test Result
The output message contains the date in exactly the same format that it came in, and in the graphic below you can see that the xml disassembler promoted the date time to my property schema and it contains the date exactly as it came in containing the time zone information indicating that I am on BST.
Summary
This scenario seems to have no effect on the date time.
Scenario 3: Flowing a message through a messaging scenario (Xml Disassembler & Xml Assembler)
This scenario is an extension to scenario 2 only this time the send port has the XmlTransmit pipeline so contains the XmlAssembler component. The schema has an associated property schema so in this scenario property promotion and demotion will occur. The below diagram illustrates this scenario.
Test Result
In this case the input message results in the message coming out looking like the below.
<?xml version="1.0" encoding="utf-8"?><ns0:Root xmlns:ns0="http://Bts.DateTime.Schemas.Input">
<TestDate>2010-08-27T23:00:00.0000000Z</TestDate>
</ns0:Root>
In this case you can see the date time has been converted to the UTC format.
Summary
In this scenario there is some promotion and demotion of the date happening due to the use of the assembler and disassembler in combination with the property schema.
In this scenario you can see that the date/time is changed as it flows through BizTalk.
Scenario 4: Map on the send port
In this scenario I have a receive port with the Xml Receive Pipeline and a send port with a pass through pipeline. I have also got a map on the send port which will convert the input message into the output message. The below diagram illustrates this scenario.
Test Result
In this scenario the below result was produced.
<ns0:Root xmlns:ns0="http://Bts.DateTime.Schemas.Output"><TestDate>2010-08-28T00:00:00.000+01:00</TestDate></ns0:Root>
As you can see the date/time is still in the BST off set as was in the input file.
Summary
This scenario appears to have no impact on the date time
Scenario 5: Map on send port using Property Promotion & Demotion
In this scenario we have exactly the same situation as scenario 4 except that the send port now has the Xml Transmit Pipeline. The schemas both have an element matching to the same context property so the date will be promoted on the way in and demoted on the way out. The following diagram illustrates this scenario.
(Update: just noticed the diagram has the wrong send pipeline, it should be XmlTransmit. Ill update this asap).
Test Result
This test produced the below result.
<?xml version="1.0" encoding="utf-8"?><ns0:Root xmlns:ns0="http://Bts.DateTime.Schemas.Output"><TestDate>2010-08-27T23:00:00.0000000Z</TestDate></ns0:Root>
As you can see the date is in the UTC format.
Summary
In this scenario you can see the date/time is affected and really the property demotion happens after the map anyway.
Scenario 6: Xml Assembler with No Demotion
In this scenario we will use a pass through receive pipeline and an Xml Transmit pipeline. I will also use a different schema which has no association with context properties so that no promotion and demotion will take place. The following diagram illustrates this scenario.
Test Result
The following message was produced.
<?xml version="1.0" encoding="utf-8"?><ns0:Root xmlns:ns0="http://Bts.DateTime.Schemas.InputNoContext">
<TestDate>2010-08-28T00:00:00.000+01:00</TestDate>
</ns0:Root>
Summary
In this scenario the date/time is unchanged.
Scenario 7: The message flowing through an orchestration
In this scenario I will accept the input message and then this will be picked up by an orchestration. Within the orchestration I will access the date in various ways and then display the results. The below diagram shows conceptually how this works.
In this scenario my aim is to cover the following:
- Writing out the value of the date via the distinguished field
- Writing out the value of the date via the context property
- Writing out the value of the message as a whole
- Writing out the string for the date after extracting it via xpath
- Writing out the string for the date after the xpath result is parsed into a .net DateTime
-
Passing the message into a helper class so the xlang message is deserialized to a class and then accessing the date as a property on the class
The below diagram just illustrates that the orchestration is very simple. It picks up the message then I use an expression shape to access the date.
The next picture shows the code within the expression shape.
The below picture shows the helper class and the simple way im writing out the date from the deserialized class:
Test Result
There are a couple of observations based on the results:
- The distinguished field will return the date in UTC format
- The context property will return the date in UTC format when accessed in the expression shape even though its shown in the message context with the +1 hour off set
- The message itself remains unchanged still containing the full date with the off set
- Extracting the date with xpath and creating your own DateTime object will create the DateTime in the localised date format.
- When accessing deserialized class the date is displayed in the localised format
The below picture shows the message in the orchestrations context properties are shown below.
The below picture shows the trace captured with DebugView showing the output from the different things tried in this scenario.
Summary
Within an orchestration there are a number of scenarios in which the date/time will be changed, but you can also control this through other techniques. This is the scenario you have to be most careful with depending on the approach you take.
Conclusion
Hopefully this article provides some useful guidance on how and when date/times may be appear to change when you implement various integration scenarios with BizTalk. A few general rules that seem to apply are:
Going back to the original problem our issue was caused because when we received the event message coming in from the source application we were extracting the effective date from the event message in an orchestration via a distinguished field and the creating our enrichment request message in a .net class which was then sent to the source application. In this process the localised date which came in from the source application had now converted to the UTC format when it was send back to the application which resulted in our enrichment request returning the wrong data for that customers contract. We were able to localise the date again before the enrichment to solve that problem.
The source for the samples in this article is available at the following location:
http://www.box.net/shared/91v27ugoya