I’ve now posted the below article on a TechNet wiki
Below a list of know bugs, issues, & other quirks* of BizTalk 2013 R2 (mainly CU3) and Visual Studio 2013 (update 4) , but I will update with fixes as the CUs come out or when I know about a new issue, so if you have another one I will add it (and link to it if you have a blog about it) if you let me know. This in addition to the ones listed by Microsoft on Known Issues in Installation, Configuration, and Deployment
* My definitions for classifying these are
Bug: Causes negative impact and no known work around or requires a lot of effort to work around.
Issue: Causes negative impact but has an easy or quick work around.
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.
Microsoft BizTalk Mapper (Visual Studio)
Issue: The Mapper will change a link to 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.
Work around: 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
Work around: Test the maps at run-time.
Quirk: How the Mapper displays items starting with underscore.
Details: If you have a schema where a Element, Attribute or Record that starts with a underscore, it shows in the mapper as ending with a underscore.
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.
Work around: Drop the new functoid next to the existing and drag the connecting lines to the new functoid.
More: This has was set to the status backlog in User Voice Fix Functoid replacement in Visual Studio before the site was shut down.
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
Work around: Open the map in a XML editor and set them manually.
Update: This was raised on User Voice The BizTalk Mapper needs all the custom map attributes exposed in the editor properties before the site was shut down.
BizTalk (schema) Editor (Visual Studio)
Issue: Can’t set decimal precision for a decimal type in the schema editor
Details: There in no option in the Schema Editor to set how many decimal points you want for a decimal type.
Work around: Open it up 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 version 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.
Work around: Deploy the schemas and pipelines in Development and have the run-time parse the messages.
Update: This was raised on User Voice Visual Studio support for Json Schemas before the site was shut down.
Missing: Can’t create custom Orchestration shapes
Details: There is no ability to create a custom orchestration shape to make code re-usability easier.
Work Around: Copy and past the shape.
Update: Status of Under Review on User Voice Custom Orchestration Shapes before the site was shut down.
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.
Work around: None
Update: Was Status of Under Review on User Voice Better support for BAM before the site was shut down. As the BAM Portal has been deprecated in BizTalk 2020, and more logging to Azure has been implemented, I would think the rest of BAM is going to go the same way.
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
Work around: Compose the settings elsewhere and paste them in.
Missing: The ability to copy and past a port
Details: It would make development easier sometimes of you could copy and existing port with all it’s settings.
Work around: Export a bindings file and edit the name of the port and re-import.
Update: This is had status Under Review on user voice Copy and paste Ports from the Admin Console before the site was shut down.
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
Update: This has been raised on User Voice Prevent rebuild each time a test is run before the site was shut down.
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
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‘.
Work Around: Remove the maps from the ports that reference the schema and add them back afterwords.
Fix: (supposedly) Deploy CU4, see FIX: Redeployment of schema referenced by maps fails after you install BizTalk Server kb 3167704 in CU4, however I 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: This was raised on User Voice Remove forced dependancy checks on Schema and Maps like ESB does before the site was shut down.
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.
Work Around: Delete all the files from the folder %APPDATA%\Microsoft\BizTalk Server\Deployment\BindingFiles\ before importing the MSI.
Note: This has been 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
Work Around: Manually set these after deployment
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.
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 a 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.
Work around: Save the message to disk and view/format it with your favourite tool
Update: This was set to status Backlog on User Voice XML / JSON Viewer before the site was shut down.
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 an 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
Work around: Use of external tools to track changes
Update: This was raised on User Voice User Auditing of Administration Events before the site was shut down.
Update 2: This was released as a feature for BizTalk 2020
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 priviliges
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 <>
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).
Work around: None
Update: This was been raised on User Voice Enhance the subscription filters before the site was shut down.
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. This appears to happen when the API does not return a list of allowed authentication schemas.
Work arounds: 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.
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 behave 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
Work around: 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
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.
Work around: Have to inspect the text in the System.Exception message to work out what exception was thrown
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 throw 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.
Work around: Catch the exception in an Orchestration and look for the not found error description that the service threw.
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
Work around: None know.
Note: Occurred in BizTalk 2013 R2 CU1
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 was raised on User Voice Pickup limits for File Adapter before the site was shut down.
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.
Work around: Use the FTP adapter instead.
Update: This was raised on User Voice FILE adapter support for empty files and had the status of Backlog before the site was shut down.
Bug: SFTP Receive Location will stop picking up files
Details: A SFTP Receive Location will stop picking up files with no errors or warning. Only restarting the Host Instance that it is running in will then have it pick up the files
More Details: Technet Forum Biztalk SFTP Adapter Issue in Receive Location. For BizTalk 2016 possibly the same issue was fixed, FIX: SFTP adapter receive locations stop working intermittently during higher load in BizTalk Server
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
Work around: Install a third party adapter that does have this option.
Update: This was raised on User Voice Enable timestamp comparison on sftp adapter, before the site was shut down.
Note: This was resolved in KB 4464664 but only for BizTalk 2016 in CU6
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
Work Around: 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
Update: This has was 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 before the site was shut down.
Note: This was released as a feature for BizTalk 2020
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.
Update: This was raised on user voice FTP adapter should use account name or SSO Affiliate Application Name to distinguish receive locations and was sitting at status Backlog, before the site was shut down.
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
Work Around: 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
Was raised on User Voice Fix the long time BUG regarding XMLTransmit pipeline and targetcharset before the site was shut down.
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.
Work around: 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.
Work around: 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 per 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. “
Work around: 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.
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
Work Around: 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 before the site was shut down.
Note: This was implemented in BizTalk 2016 with some CU’s.
However It has been reported on Twitter that “We have some issues with the new #biztalk CU7. The json encoder has started formatting boolean values as string values, like “true” instead of true.” and “As we wanted the FTP fixes in CU7 we installed it anyway and replaced the jsonextension dll with an older version.”
Issue: The BizTalk JSON Encoder adds a outputs a Integer as a decimal
Details: If you use the JSON Encoder and have a element defined as Integer, when it goes through the JSON Encode it becomes a decimal, e.g. 100 becomes 100.0
Work Around: Change the type from Integer to Int or Long depending on the size of the expected number (if unbound, use long).
Issue: The BizTalk JSON Encoder adds a time to a Date
Details: If you use the JSON Encoder and have a 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.
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
Work Around: 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 a element defined as a datetime, when it goes through the JSON Encoder it change it to local times. e.g. in 1999-05-31T13:20:00.000-05:00 becomes “1999-06-01T06:20:00+12:00”.
Work Around: 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|
Work Around: 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
Work Around: 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.
Work Around: 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 before the site was shut down and is marked requested by other team (.Net), and also on Github for dotnet
Update 2: This was released as a feature in BizTalk 2020.