BizTalk 2013 R2 known bugs, issues & quirks
Introduction
Every so often we come across a bug, a strange behavior, or something we just wish BizTalk or Visual Studio was capable of doing. The following is a list of known bugs, issues, & other quirks* of BizTalk 2013 R2 and Visual Studio 2013 development tools for BizTalk, this in addition to the ones listed by Microsoft on Known Issues in Installation, Configuration, and Deployment.
* Definitions for classifying these are
Bug: Causes negative impact and there is no known workaround or requires a lot of effort to work around.
Issue: Causes negative impact but has an easy or quick workaround.
Missing: A feature that BizTalk doesn't have that would make our life easier.
Quirk: Something strange or unusual but does not cause a negative impact so far as known.
Development
Microsoft BizTalk Mapper (Visual Studio)
Issue: The Mapper will change a link to an attribute of the same name when it was going to the element.
**Details: **If you have an existing element in a schema mapped from to an Element, and you then add an attribute at the same level with the same name, the mapper will change the link to go to the attribute.
Workaround: Add the link for the Element back after adding the attribute to the schema and check & correct the attribute link.
Note: The reverse applies as well, if you are coming from an Element and add an attribute of the same name, it will change the link.
Issue: The Use XSL Transform setting has no effect in Visual Studio
Details: Changing the XSL Transform setting has no effect when you test the map in Visual Studio. See BizTalk 2013 R2 CU2 & BizTalk 2016 – Use XSL Transform
Workaround: Test the maps at run-time.
Quirk: How the Mapper displays items starting with an underscore.
Details: If you have a schema where an Element, Attribute or Record starts with an underscore, it shows in the mapper as ending with an underscore.
https://cdijkgraaf.files.wordpress.com/2016/08/quirkunderscore.png
Work around: None
Note: No impact on functionality.
Missing: Replace functoid in map
Details: In earlier versions of Visual Studio you used to be able to drag and drop a functoid from the toolbox onto a functoid on the map to replace it.
Workaround: Drop the new functoid next to the existing and drag the connecting lines to the new functoid.
Update: This has been set to the status backlog in User Voice Fix Functoid replacement in Visual Studio
Missing: Some attributes in the map can't be edited in the editor
Details: Some attributes in the map cannot be edited in them map properties. These are:
GenerateDefaultFixedNodes
OptimizeValueMapping
PreserveSequenceOrder
TreatElementsAsRecords
Workaround: Open the map in an XML editor and set them manually.
Update: This has been raised on User Voice The BizTalk Mapper needs all the custom map attributes exposed in the editor properties
BizTalk (schema) Editor (Visual Studio)
Issue: Can't set decimal precision for a decimal type in the schema editor
Details: There is no option in the Schema Editor to set how many decimal points you want for a decimal type.
Workaround: Open it with the XML Editor or text editor and add it manually. See Base Data Types and Restrictions in the Schema Editor
Note: This has been an issue since 2004, so a long-standing issue that applies to earlier versions of BizTalk/Visual Studio as well.
Missing: Can't validate / generate JSON payloads from Visual Studio
Details: It would be good to be able to validate JSON payloads against a schema or to generate JSON messages from a schema like you can with XML and Flat Files.
Workaround: Deploy the schemas and pipelines in Development and have the run-time parse the messages.
Update: This has been raised on User Voice Visual Studio support for Json Schemas
BizTalk Orchestrations
Missing: Can't create custom Orchestration shapes
Details: There is no ability to create a custom orchestration shape to make code re-usability easier.
**Workaround: **Copy and paste the shape.
Update: Status of Under Review on User Voice Custom Orchestration Shapes
Business Activity Monitoring
Missing: Tools to make BAM development easier
Details: Having to use Excel and other clunky tools to develop and maintain BAM definitions.
Workaround: None
**Update: **Status of Under Review on User Voice Better support for BAM
BizTalk Server Administration (Console)
Issue: HTTP Method and URL Mapping & SOAP Action too small
Details: The HTTP Method and URL Mapping in WCF-WebHttp or SOAP Action header in other WCF adapters in the Transport Properties dialogue windows are too smal and you can't resize them.
See also Resizeable windows
Workaround: Compose the settings elsewhere and past them in.
Missing: The ability to copy and past a port
Details: It would make development easier sometimes of you could copy an existing port with all it's settings.
Workaround: Export a bindings file and edit the name of the port and re-import.
Update: This is status Under Review on user voice Copy and paste Ports from the Admin Console
Unit Tests
Issue: When you run unit tests it always does a rebuild of the entire solution
Details: When you run the unit test it always does a rebuild of the entire solution, even if you have made no changes or just a change to the unit test. With a large solution, this can significantly impact how long it takes to do unit tests.
Note: This is not BizTalk specific see Unnecessary project rebuilds when unit testing in Visual Studio
Workaround: None
Update: This has been raised on User Voice Prevent rebuild each time a test is run
Deployment
Issue: Redeployment of schema referenced by maps fails (Fixed in CU4?)
Details: Trying to re-deploy a schema that is referenced by a map on a port fails with the following database error.
Removal of the assembly failed. Make sure that all items in the assembly you are trying to remove fulfill the following conditions:
1. Pipelines, maps, and schemas are not being used by Send Ports or Receive Locations in the same or referenced application(s)
2. Roles have no enlisted parties
Database Error:
The DELETE statement conflicted with the REFERENCE constraint "bts_sendport_transform_foreign_transformid". The conflict occurred in database "BizTalkMgmtDb", table "dbo.bts_sendport_transform", column 'uidTransformGUID'.
The DELETE statement conflicted with the REFERENCE constraint "fk_bt_mapspec_bts_item". The conflict occurred in database "BizTalkMgmtDb", table "dbo.bt_MapSpec", column 'itemid'.The DELETE statement conflicted with the REFERENCE constraint "bts_sendport_transform_foreign_transformid". The conflict occurred in database "BizTalkMgmtDb", table "dbo.bts_sendport_transform", column 'uidTransformGUID'.
**Workaround: **Remove the maps from the ports that reference the schema and add them back afterwards.
Fix: (supposedly) Deploy CU4, see FIX: Redeployment of schema referenced by maps fails after you install BizTalk Server kb 3167704 in CU4, however you can just get a different error now sometimes. Still need to use the workaround in those cases.
Note: This was also fixed earlier in BizTalk 2010 and 2013 see kb 2908686
Update: Raised on User Voice Remove forced dependancy checks on Schema and Maps like ESB does
Issue: If you deploy a MSI without bindings it can revert to an older binding
Details: If you deploy a MSI without bindings and it does not contain bindings and you don't apply bindings either automatically or manually as part of the deployment, it can sometimes end up with a previous state of the bindings.
Workaround: Delete all the files from the folder %APPDATA%\Microsoft\BizTalk Server\Deployment\BindingFiles\ before importing the MSI.
Note: This has been an issue with previous version of BizTalk as well, see Unexpected bindings reset on BizTalk 2009
Issue: You can't export the Tracking settings on Policies via bindings file
Details: If you export a bindings file it does not contain the tracking settings for a Policy and there doesn't seem to be a way to automatically set them.
Note: Raised on StackOverflow How to import/export the tracking setting of a policy
Workaround: Manually set these after deployment
Administration
BizTalk Server Administration (Console)
Issue: Export Bindings is grayed out after importing bindings
Details: After deleting all artifacts, redeploying artifacts and then importing binding. Export Bindings is grayed out and unavailable in BizTalk Server Administration. Refresh does not fix this.
https://cdijkgraaf.files.wordpress.com/2016/08/exportbinding.png
Work around: Close and re-open or open a new BizTalk Server Administration Console
Issue: Restart is grayed out in BizTalk Server Administration
Details: If you have selected multiple hosts in the Host Instances and the last one you host you selected is an isolated host, either at the bottom of the list when selecting with Ctrl + A or Shift + Click, or alternatively the last added by Ctrl + Click, then Restart options is grayed out in the BizTalk Server Administration console
Work around: Either un-select the isolated hosts (Ctrl + Click) or sort the Host Instances so that the last host in the list is not an isolated one.
Missing: The ability to view messages as XML or JSON in the console
Details: In the administration console when you view a tracked message, you can only see it as text or Binary, and not as XML or JSON.
Workaround: Save the message to disk and view/format it with your favorite tool
Update: Set to status Backlog on User Voice XML / JSON Viewer
Missing: No Audit logs
Details: There is no audit trail in the BizTalk Administration console for such things as when a Port or Host Instance was stopped, (re)started and why (error or console) or by whom. Also when and what version of a DLL was imported into the BizTalk database. Details of when certain events occurred could help to diagnose issues. See Enable - Disable ports history in BizTalk
Workaround: Use of external tools to track changes
Update: Has been raised on User Voice User Auditing of Administration Events
ESB Exception Portal
Issue: ESB.AlertService.QueueGenerator.ProcessFaultsForQueue - Cannot interpret token '!' at position 62
Details: This is caused when in the ESB Exception Portal you add a Alert rule that contains a not condition and it creates it with a != rather than a <>
Work around: Run the following SQL with dbo privileges
use [EsbExceptionDb] update [AlertCondition] set Operator = '<>'where Operator = '!=' update [Alert] set ConditionsString = Replace(ConditionsString,'!=','<>')where ConditionsString like '%!=%'
Fix: Edit the following .aspx pages
ESB.Portal\Alerts\ConditionAdd.ascx & AlertEdit.aspx
Change != to <>
Run-time
Subscription Filters
Missing: The ability to do more complex subscription filters.
Details: You can only do a single level of logic e.g. (A and B) or (A and C) rather than A and (B or C).
Workaround: None
**Update: **This has been raised on User Voice Enhance the subscription filters
WCF-WebHttp adapter
WCF-WebHttp Adapter – Basic Authorisation does not work
Details: If you try and configure the WCF-WebHttp adapter to use basic authentication it does not pass the Authorization header
More: See WCF-WebHttp Adapter – Basic Authorisation
Workarounds: Either put the authorization in the outbound HTTP headers in the Message tab (not recommended), create a custom behaviour to add it, or use the old HTTP adapter.
Update: Raised on user voice Basic Authentication with WCF-WebHttp adapter
Bug: BizTalk WCF-WebHttp adapter does not detect 500 error & http StatusCode not available for other errors codes (fixed in CU5)
Details: When you get a 500 error from a RESTful service using the WCF-WebHttp adapter it behaves differently from other non 200 HTTP status codes.
For other error codes it throws a fault exception with the response payload including the payload returned. This makes it hard to handle 404 errors in a messaging only solution
See BizTalk WCF-WebHttp adapter does not detect 500 error for more details.
Work around: As a work around you could develop orchestrations to check for the WCF.InboundHttpStatusCode ContextProperty and its value and catch the other errors in a System.Exception block* (see bug below)
Fix: The fix for the 500 not throwing an error is included in CU5
Bug: BizTalk WCF-WebHttp adapter does not set the message type on error
**Details: **When you get a non 200 series http status code from a RESTful service using the WCF-WebHttp adapter, the SOAP fault message published to the message box does not have the context property MessageType. This means you cannot map it or catch it in a Fault on the Logical Port in the Orchestration
Workaround: Catch it in a System.Exception block in the Orchestration, see (BizTalk 2013 R2 JSON Encoder error – “Object reference not set to an instance of an object” – Part 1) or use BRE rules in a Pipeline to handle the SOAP Exception see BizTalk 2013 R2 JSON Encoder error – “Object reference not set to an instance of an object” – Part 2
**Note: **Also see above bug where it does not throw the 500 HTTP status as an exception.
Bug: BizTalk WCF-WebHttp adapter does not set http status code on error
Details: When you consume a RESTful service and get a non 200 series status code back, it will throw a SOAP exception in the Adapter (apart from the 500 status as above) and not promote the http status code in the message context InboundHttpStatusCode or InboundHttpStatusDescription like it does for a successful ones. If these were in the Context Properties it would make handling exceptions easier.
https://cdijkgraaf.files.wordpress.com/2016/08/inboundhttp.png
Work around: Have to inspect the text in the System.Exception message to work out what exception was thrown
Update: Raised on user voice webHttp support for HTTP error codes and set to a status of Backlog.
Missing: BizTalk WCF-WebHttp adapter ability to suppress 404 status code
Details: When you do a get on a RESTful service and get a 404 status code and a payload saying that the object you asked for does not exists, it will throws a SOAP exception. It would be nice to be able to suppress a 404 status code (or other status codes) on a GET (or other operations) and to parse the response as normal through the pipeline and process as business exception rather than a System Exception.
Workaround: Catch the exception in an Orchestration and look for the not found error description that the service threw.
Update: Mentioned in comments on user voice webHttp support for HTTP error codes.
WCF-SQL adapter
Bug: SQL Polling: Receive Location polling data after service window stop time
Details: If you Enable service window on a WCF-SQL port it can sometimes poll outside of that window.** **See Stackoverflow: Receive Location polling data after service window stop time
Workaround: None know.
Note: Occurred in BizTalk 2013 R2 CU1
File Adapter
Missing: Cannot configure the file adapter to limit the rate of pickups.
Details: Cannot configure the file adapter to limit the rate at which it picks up files. This can cause throttling issues in BizTalk
Work around: Write your own file pickup adapter
Update: This has been raised on User Voice Pickup limits for File Adapter
Missing: Ability to be able to pick up empty files
Details: The file adapter will discard zero length files. Sometimes clients do want BizTalk to process these and send a message to the destination system. The other adapters do not have this limitation.
Workaround: Use the FTP adapter instead.
Update: This has been raised on User Voice FILE adapter support for empty files and has status of Backlog.
SFTP Adapter
Missing: Cannot configure SFTP for read only files**.**
Details: There is no option like Delete After Download = No and Enable Timestamp comparison like the FTP Adapter. See Microsoft BizTalk Server 2013 R2 SFTP Adapter Tricks and Pitfalls - The Messaging Engine failed while notifying an adapter of its configuration
Workaround: Install a third party adapter that does have this option.
Update: This has been raised on User Voice Enable timestamp comparison on sftp adapter
Missing: Cannot configure SFTP to use temporary file names
Details: There is no option to use "Use temporary file while writing" or "Rename files while reading" like the file adapter for the SFTP adapter nor a After Put like the FTP adapter to rename the file. This can lead to issues with partially written files being picked up
Workaround: Use the Temporary Folder option
Missing: Cannot configure SFTP adapter to use SSO
Details: There is no option to configure the SFTP adapter to use SSO use detailed in BizTalk SSO & SSO Affiliate Settings
Workaround: None
Update: This has been marked as status in progress on User Voice SSO Affiliate Applications support for native SFTP adapter, also Wider support for SSO for out-of-the-box Adapters
FTP Adapter
Missing: Can't configure receive locations to the same URI using different credentials
Details: You can't configure multiple receive locations going to the same FTP sever and path, even though they use different credentials means they are mapped to different folders.
Workaround: Use host file or DNS entries to give different names to the same server
Update: This has been raised on user voice FTP adapter should use account name or SSO Affiliate Application Name to distinguish receive locations and is sitting at status Backlog.
Pipeline components
Issue: Changing the TargetCharset in the XML or Flat File assembler has no effect in the BizTalk Administration Console
Details: If you change the TargetCharset value in a pipeline via the BizTalk Administration console it does not change the outgoing payload to that encoding.** **See Flat File Assembler Encoding and Charset
Workaround: Change the Encoding in Visual Studio and redeploy the pipeline.
**Note: **This has been an issue since BizTalk 2006, see BUG: The TargetCharset value in an XMLTransmit pipeline configuration may not take effect as expected in BizTalk Server 2006
Update: Raised on User Voice Fix the long time BUG regarding XMLTransmit pipeline and targetcharset
Issue: The ESB Add Namespace pipeline component adds the BOM back
Details: If you use the ESB Remove Namespace pipeline component and tell it RemoveByteOrderMark and follow it with a ESB Add Namespace Pipeline component in a send pipeline to a file, then the file produced will have a byte order mark.
Workaround: Use a custom add namespace pipeline component.
Bug: The BizTalk JSON Encoder hangs forever
Details: A XML schema that references a complex type or another schema will cause the JSON Encoder to Hang.
Workaround: Simplify the schemas you use to create JSON payloads.
More Details: Mark Brimble's blog post JSON Encoder hangs forever
Issue: The BizTalk JSON Encoder applies same type to elements with the same name
Details: If you have elements at more than one level of your XML schema with the same name, but different types, then it will apply the same type as the first one it encounters. This will either cause things to be quoted when they should not be, or if it is a string that it thinks is a int etc. it will throw the following exception if the string cannot be an int.
"There was a failure executing the send pipeline <pipeline & URI details> Reason: Input string was not in a correct format. "
Workaround: Rename the fields so they are unique.
More Details: Pim Simons blog post JSON Encoder Type Bug who found it in BizTalk 2016. A similar issue has also been raised on Fix bug in JsonEncoder - cannot handle records and fields with the same name.
Update: This could possibly be resolved by Microsoft updating the version of Newtonsoft as per User Voice Json Encoder/Decoder use new version of Newtonsoft.Json
Issue: The BizTalk JSON Decoder drops trailing 0's after the decimal
Details: If you use the JSON Decoder and you have a decimal element it will drop trailing zeroes after the decimal point. E.g. -10.00 becomes -10. If there are non zeroes it will leave it alone e.g. 10.41 stays 10.42
Workaround: In a map use a scripting functoid and format it back to the number of decimal places required** Return parameter.ToString("F2");**
Note: this work around will format it to two decimal places even if there are more, so please ensure you format to the appropriate number of places.
**Update: **This could possibly be resolved by Microsoft updating the version of Newtonsoft as per User Voice Json Encoder/Decoder use new version of Newtonsoft.Json
Issue: The BizTalk JSON Encoder adds a outputs a Integer as a decimal
Details: If you use the JSON Encoder and have an element defined as Integer, when it goes through the JSON Encode it becomes a decimal, e.g. 100 becomes 100.0
Workaround: Change the type from Integer to Int or Long depending on the size of the expected number (if unbound, use long).
**Update: **This could possibly be resolved by Microsoft updating the version of Newtonsoft as per User Voice Json Encoder/Decoder use new version of Newtonsoft.Json
Issue: The BizTalk JSON Encoder adds a time to a Date
Details: If you use the JSON Encoder and have an element defined as Date, when it goes through the JSON Encoder it becomes a datetime, e.g. 1999-05-31 becomes "1999-05-31T00:00:00"
**Work Around: Change the type **to string.
**Update: **This could possibly be resolved by Microsoft updating the version of Newtonsoft as per User Voice Json Encoder/Decoder use new version of Newtonsoft.Json
Issue: The BizTalk JSON Encoder changes blanks in XML to null in JSON
Details: If you use the JSON Encoder and have a element that is empty, it becomes a null in the JSON payload.
**More Details: **REST JSON Christmas Puzzle
Workaround: Use the BRE Pipeline and do a Replace the string ": null in the message body with the string ": "" (initial concept from REST JSON Christmas Puzzle – Work around).
Note: The above work around has an unintended side effect that it causes a BOM to be added. This may cause issues with some systems.
Quirk: The BizTalk JSON Encoder changing date-time timezone
Details: If you use the JSON Encode and have an element defined as a datetime, when it goes through the JSON Encoder it is changed it to local times. e.g. in 1999-05-31T13:20:00.000-05:00 becomes "1999-06-01T06:20:00+12:00".
Workaround: Change the type** **to string.
Note: As the time is still actually the same actual time, classifying as a quirk.
Quirk: The BizTalk JSON Encoder - JSON Array
Details: JSON Encoder not creating JSON Array for what should be a repeating element. This occurs if you don't have schema deployed that matches the XML payload and there is only a single item. See JSON Array -
BizTalk JSON Encoder|
Workaround: The XML must conform to a schema that BizTalk knows about. Use a custom send pipeline that contains a XML Assembler pipeline component before the JSON encoder pipeline component.
Quirk: The BizTalk JSON Decoder changing date-time timezone
Description: If you use the JSON Decoder it will cast ISO formatted dates to the local time zone, See BizTalk JSON Decoder changing date-time timezone
Workaround: None
Note: As the time is still actually the same actual time, classifying as a quirk.
Missing: Ability to use XSLT 2.0 or 3.0 in BizTalk Maps
Description: You can't use XSLT 2.0 or 3.0 in BizTalk Maps. This is actually a limitation of .Net.
Workaround: Use a third party component like Saxon as described here Is there XSLT 2.0 or 3.0 support in BizTalk Server 2016 mapping?
**Update: **This feature has been requested on User Voice Support for XSLT2 or XSLT3 and is marked requested by other team, and also on Github for dotnet