BizTalk Server 2013 R2: Handle exceptions from REST services in Orchestration

Article
1/17/2024

https://msdnshared.blob.core.windows.net/media/2016/08/7827.NinjaAwardTinyBronze.pngBronze Award Winner

Introduction

This article explains step by step procedure to handle exceptions when consuming REST services in BizTalk orchestrations.

I recently consumed a WEB API rest service in a BizTalk orchestration and observed that the orchestration catch block is not catching the exception thrown by the service, when I put a scope and exception in the orchestration and returning a fault to the client in case of errors. Since the control is not getting back to the catch block, the orchestration instance gets suspended and no response/fault is returned to the client. Yet the web client is waiting for the response from BizTalk and eventually times out.

I did observe that the control is going to catch block in case the REST service returns a message with status code 404. And for all the other HTTP codes the orchestration catch block is not executed.

The below article on TechNet explains writing a custom WCF behaviour to access the error and HTTP status codes in orchestration.

http://social.technet.microsoft.com/wiki/contents/articles/16625.biztalk-server-rest-services-error-handling.aspx

Here is my two problems with the approach mentioned in the above article.

Maintenance and debug problems with the custom WCF behaviour.
In the orchestration the response is treated as an XML document for both successful and error responses. Then, based on the HTTP status code we need to assign this xml to the actual typed response or the error response. I have around 20 orchestrations consuming the REST services and I don’t want to create an extra xml document variable and then message assignment shapes based on the if condition.

So I thought of doing this only using scope/catch block just like the normal exception handling we put in the orchestrations and did a PoC. I am able to achieve this using a fault operation to the REST send port and this post is totally based on my experience with the POC.

Problem Statement

BizTalk Orchestration catch block is not catching the exception thrown by REST service other than 404 status code. Not able to parse the HTTP status code and error message.

Let’s get started with creating BizTalk artefacts for this assignment.

Create BizTalk artefacts

Create a new empty BizTalk server project with name “POC.RESTErrorHandling”

Add an Employee schema with basic ID, Name fields and save as Employee.xsd. Promote the ID as distinguished filed in order to access the value in the orchestration.

Create schemas for web api request and response

Easy way to create the schemas for Web API is to generate from it from the Web API help page structure.

We can access the web api help page as below

https://fswvapp201d.twgfs.net/TWGFS.Customer.Services.CRM/Help

Copy the xml format of the request and response and save them as xml files.

Once we have valid xml files we can generate the schemas using BizTalk schema generation wizard.

Right click on Project and select Add à Add generated items

Select Generate schemas à select document type as Well-formed xml and select the input file.

Click OK and the schemas are created in the project.

Create Orchestration

Create a basic orchestration with a receive shape to pick the employee xml file

Create 3 messages in the orchestration view for input, web api request and response.

Create a two way send port to send the request and receive the response.

Once the response is received create a send port to copy the response to a folder.

Create a catch block and write the below code in the expression shape.

System.Diagnostics.EventLog.WriteEntry("BizTalk Server","Error Occured." +ex.Message,System.Diagnostics.EventLogEntryType.Error);

And finally orchestration looks like this.

Testing the default setup

Right click on “POC.RESTErrorHandling” BizTalk project and deploy to see what the out of box behaviour.

After deployment go to BizTalk server admin console and create one receive port to pick the input xml file and one send port to save the same file to folder if there are no errors and one two way send port to talk to REST service.

Create these ports using the binding file attached.

POC.RESTErrorHandling.BindingInfo.xml

Drop the employee input xml file in to the folder. The input message is shown in the picture below.

I am passing the ID as 12345 which does not exists in the system hence expecting the error from web api rest service. In this case my web api method returns http status code as 500(Internal server error) and error message as “rest error.Test exception message” for testing.

I dropped the message into in folder and message is not created in out folder hence there should be an error.

I can see two error messages in the Application Event viewer.

There was a failure executing the response(receive) pipeline: "Microsoft.BizTalk.DefaultPipelines.XMLReceive, Microsoft.BizTalk.DefaultPipelines, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" Source: "XML disassembler" Send Port: "POCWebAPI_Send" URI: "https://fswvapp201d.twgfs.net/TWGFS.Customer.Services.CRM" Reason: Finding the document specification by message type "Error" failed. Verify the schema deployed properly.

The above error occurred as the web api returned the <Error> xml response and there is no schema corresponding to it in the BizTalk project. And the below second error is also related to the same

Error Occured.An error occurred while processing the message, refer to the details section for more information

Message ID: {4A105D8E-6BCD-4BB4-9F87-3B85A12A921E}

Instance ID: {18CC6099-4162-4973-89D2-222871564486}

*Error Description: There was a failure executing the response(receive) pipeline: "Microsoft.BizTalk.DefaultPipelines.XMLReceive, Microsoft.BizTalk.DefaultPipelines, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" Source: "XML disassembler" Send Port: "POCWebAPI_Send" URI: "https://fswvapp201d.twgfs.net/TWGFS.Customer.Services.CRM" Reason: Finding the document specification by message type "Error" failed. Verify the schema deployed properly.

*

Solution Design

Create a schema for the error response returned by REST service
Create a receive pipeline with xml disassemble and add the both document schemas, one is web api response and the other is error schema
Create a fault operation to the web api send port and attach the fault handler to the catch block.

Create error schema and pipeline

This error response syntax we don’t get it from web api help page hence fire a request in Fiddler to the Fiddler and copy the error xml to a file.

Create the error schema from the error xml and the schema looks like this.

Promote the Message filed as distinguished property to access the error message in catch block.

Next create a receive pipeline and add the document schemas.

Modify the Orchestration

Open the orchestration and create a message for Error schema.

Create two variables.

varHTTPStatusCode of type string
varXMLDoc of type xml document.

On the two way send port add a fault operation of type POC.RESTErrorHandling.APIError

Attach an exception block of type Port_2.GetCustomerDetails.Fault_1

Use a Construct_Message shape to assign the exception object to the error message.

Add an Expression shape to access the error message and http status code from the message headers.

System.Diagnostics.EventLog.WriteEntry("BizTalk Server","rest error." +REST_Error.Message,System.Diagnostics.EventLogEntryType.Error);
varHTTPStatusCode = REST_Error(WCF.InboundHttpStatusCode);
System.Diagnostics.EventLog.WriteEntry("BizTalk Server","http response code is : " + varHTTPStatusCode,System.Diagnostics.EventLogEntryType.Error);

Save the project and deploy again.

Deployment

Download the zip file from technet gallery using below link which contains the solution and bindings files

https://code.msdn.microsoft.com/BizTalk-Handle-exceptions-88863203
Unzip to folder
Open POC.RESTErrorHandling.sln, build and deploy the project
Go to BizTalk server admin console and import the bindings file “POC.RESTErrorHandling.BindingInfo.xml”
Running the sample
Drop the sample input file “Employee.xml” into In folder and the error is displayed in the Application Event viewer.

http response code is : InternalServerError and rest error. Test exception message

References

http://social.technet.microsoft.com/wiki/contents/articles/16625.biztalk-server-rest-services-error-handling.aspx

Share via