Exploring REST Capabilities of BizTalk Server 2013 (Part 1: Exposing REST Endpoints)

The BizTalk Server 2013 beta is out there now and I thought I’d take a look at one of the key additions to the platform. In this current age of lightweight integration and IFTTT simplicity, one has to wonder where BizTalk will continue to play. That said, a clean support of RESTful services will go a long way to keeping BizTalk relevant for both on-premises and cloud-based integration scenarios. Some smart folks have messed around with getting previous version of BizTalk to behave RESTfully, but now there is REAL support for GET/POST/PUT/DELETE in the BizTalk engine.

I decided to play with two aspects of REST services and BizTalk Server 2013: exposing REST endpoints and consuming REST endpoints. In this first post, I’ll take a look at exposing REST endpoints.

Scenario #1: Exposing Synchronous REST Service with Orchestration

In this scenario, I wanted to use the BizTalk-provided WCF Service Publishing Wizard to generate a REST endpoint. Let’s assume that I want to let modern web applications send new “account” records into our ESB for further processing. Since these accounts are associated with different websites, we want a REST service URL that identifies which website property they are part of. The simple schema of an account looked like this:

2012.11.12rest01

I also added a property schema that had fields for the website property ID and the account ID. The “property ID” node’s source was set to MessageContextPropertyBase because its value wouldn’t exist in the message itself, but rather, it would solely exists in the message context.

2012.11.12rest02

I could stop here and just deploy this, but let’s explore a bit further. Specifically, I want an orchestration that receives new account messages and sets the unique ID value before returning a message to the caller. This orchestration directly subscribes to the BizTalk MessageBox and looks for any messages with a target operation called “CreateAccount.”

2012.11.12rest03

After building and deploying the project, I then started up the WCF Service Publishing Wizard. Notice that we can now select WCF-WebHttp as a valid source adapter type. Recall that this is the WCF binding that supports RESTful services.

2012.11.12rest04

After choosing the new web service address, I located my new service in IIS and a new Receive Location in the BizTalk Engine.

2012.11.12rest05

The new Receive Location had a number of interesting REST-based settings. First, I could choose the URL and map the URL parameters to message property (schema) values. Notice here that I created a single operation called “CreateAccount” and associated with the HTTP POST verb.

2012.11.12rest06

How do I access that “{pid}” value (which holds the website property identifier) in the URL from within my BizTalk process? The Variable Mapping section of the adapter configuration lets me put these URL values into the message context.

2012.11.12rest07

With that done, I bound this receive port/location to the orchestration, started everything up, and fired up Fiddler. I used Fiddler to invoke the service because I wanted to ensure that there was no WCF-specific stuff visible from the service consumer’s perspective. Below, you can see that I crafted a URL that included a website property (“MSWeb”) and a message body that is missing an account ID.

2012.11.12rest08

After performing an HTTP POST to that address, I immediately got back an HTTP 200 code and a message containing the newly minted account ID.

2012.11.12rest09

There is a setting in the adapter to set outbound headers, but I haven’t seen a way yet to change the HTTP status code itself. Ideally, the scenario above would have returned an HTTP 202 code (“accepted”) vs. a 200. Either way, what an easy, quick way to generate interoperable REST endpoints!

 

Scenario #2: Exposing Asynchronous REST Service for Messaging-Only Solution

Let’s do a variation on our previous example so that we can investigate the messages a bit further. In this messaging-only solution (i.e. no orchestration in the middle), I wanted to receive either PUT or DELETE messages and asynchronously route them to a subsequent system. There are no new bits to deploy as I reused the schemas that were built earlier. However, I  did generate a new, one-way WCF REST service for getting these messages into the engine.

In this receive location configuration, I added two operations (“UpdateAccount”, “DeleteAccount”) and set the corresponding HTTP verb and URI template.

2012.11.12rest12

I could list as many service operations as I wanted here, and notice  that I had TWO parameters (“pid”, “aid”) in the URI template. I was glad to see that I could build up complex addresses with multiple parameters. Each parameter was then mapping to a property schema entry.

2012.11.12rest13

After saving the receive location configuration, I configured a quick FILE send port. I left this port enlisted (but not started) so that I could see what the message looked like as it traveled through BizTalk. On the send port, I had a choice of new filter criteria that were related to the new WCF-WebHttp adapter. Notice that I could filter messages based on inbound HTTP method, headers, and more.

2012.11.12rest14

For this particular example, I filtered on the BTS.Operation which is set based on whatever URL is invoked.

2012.11.12rest15

I returned to Fiddler and changed the URL, switched my HTTP method from POST to PUT and submitted the request.

2012.11.12rest16

I got an HTTP 200 code back, and within BizTalk, I could see a single suspended message that was waiting for my Send Port to start. Opening that message revealed all the interesting context properties that were available. Notice that the operation name that I mapped to a URL in the receive adapter is there, along with various HTTP header and verbs. Also see that my two URL parameters were successfully promoted into context.

2012.11.12rest17

 

Summary

That was a quick look at exposing REST endpoints. Hopefully that gives you a sense of the native aspect of this new capability. In the next post, I’ll show you how to consume REST services.

About these ads


Categories: BizTalk, SOA, WCF/WF

33 replies

  1. I got an error – Receive location for address “/GPS/Service1.svc” not found ,
    when entering the following url on my browser: http://localhost/gps/Service1.svc?wsdl

    I also received this error when submitting POST via Fiddler (http://localhost/gps/Service1.svc )

    Orchestration Datasmith.Samples.BizTalkRest1.MsgOrchestration
    Port: WcfReceivePort_gps/Service1
    receive Location Name: WcfService_gps/Service1
    URI: /gps/Service1.svc

    Mapping:

    In web.config, I noticed no entries for receiveLocationMappings – not sure if this is an issue.

  2. I fixed this, thanks.

    another issue.

    I installed Biztalk 2013 Beta on Windows 2008 R2. I also installed .Net Framework 4.5.

    My problem is that when i select WCF_Custom, the UDP Binding is not present in the drop-down combo box on the Bindings tab.

    Any suggestions on how to resolve this?

    • Apparently, 32 bit & 64 bit machine.config needs to be updated, since Biztalk admin application is 32 bit, whereas, adapter is 64 bit.

      MS documentation doesn’t remind developer that both locations need to be updated, it usually just states update machine.config.

      MS should have a common\machine.config for configurations that both 32-bit & 64-bit rely on.

      • Hey Larry

        I’m sorry, but it is the .net 4.5 machine.config files that need to be edited, I guess?
        Can you explain shortly what and where needs to be addes,

        Tnx!

  3. Great Article!, Can you please explain on what the SetUnitque ID Message Assignment shape does? Based on the screenshot it looks like the UserName property has been promoted but not ID property. How are you setting the ID Property? Please advise.

    • I am trying to implement the Scenario 1 of this Article and i am getting the Routing Failure Report and the Message is getting suspended. When i see the error report the BTS.Operation have been promoted to have value of CreateAccount but the message Type is blank. Please advice on what could be the problem here.

    • The unique ID is just a random GUID that acts as the account ID on the returned message. Simply used System.Guid.NewGuid().ToString() to generate it.

      • I am struggling a but to use the expression editor to create the ack message, and assign the generated GUID… any hints on how to do this? Thanks!

  4. Hi Mike, if I recall, the “ack” message is the same as the input message type, just with a populated ID. To generate the ID, I typically use “msg.Id = System.Guid.NewGuid().ToString();”

    • Thanks for the reply Richard, the only message I have defined is “Account_Input” whose message type is the Account_XML schema as in your example. I do use this message as both the receive and send message of the orchestration. The problem I am having is with the expression in the message assignment shape inside the construct message shape. I am using “Account_Input.ID = System.Guid.NewGuid().ToString();”. The expression editor tells me: “identifier ID does not exist in Account_Input; are you missing an assembly reference?”. When I try to build the solution it tells me that 1) the expression is in error, 2) ‘Account_Input': message has not been initialized in construct statement, 3) use of unconstructed message ‘Account_Input’. Is there any thing else I am doing wrong here? Thanks again for your help.

  5. Richard
    I am also getting same error as Mike but still confused in that Message Assignment shape. I am new in Biztalk. FYI, I created a schema as you showed in your post with same name.
    can you please explaine more in detail please. thank you onces again.

    • Hi Ravi. So the Message Assignment shape is for instantiating new messages. You should have two messages, both of the same type. The first message is the one received by the orchestration, so it’s instantiated by default. The second — which has the generated ID in it — needs to be built before it can be sent as a response. To build it, you specify the 2nd message as the “message to build” for the Construct shape, and then in the Assignment shape, you can instantiate the second message by “copying” the first (Message2 = Message1;). Then you just set the value (and make sure that you’ve distinguished the schema field you want to set here) of the ID field (Message2.Id = ‘123’).

    • Richard,
      when you using in Receive port. Url=”/Property/{pid}/Account” I am confused here what is property and what is Account I am guessing Property is name of PropertySchema and Account is rootnode name of Account_XML.xsd…
      is there any other configuration you doing in receive port..like in behavior for servicebehavior or endpoint behavior!!!

      • Hi Ravi. In this post, remember that “Property” in the URL refers to the use case (sharing information about websites) and has nothing to do with property schemas. The “pid” parameter refers to which website property we’re referring to. The URL describes the resource, but the values I used don’t necessarily matter. We’re posting an XML payload to this URL, and THAT is what maps to the schema. The URL variables (like pid and aid) are thrown into the message context. That’s the only mapping from URL to message.

      • Richard,
        do you mind to review my work of WCF-webhttp. I am getting error while consuming it.
        Error is
        Error consuming wCF service metadata. Message part missing element. Correct service description “http://tempuri.org/” message type =”Service1_operation1_inputmessage” part “Part” nad return the wizard.
        if you provide me your email I can send you a screen shot of my work. if that help you out to solve it. my id is raviraj00144@yahoo.com
        thank you once again

Trackbacks

  1. Distributed Weekly 181 — Scott Banwart's Blog
  2. Exploring REST Capabilities of BizTalk Server 2013 (Part 2: Consuming REST Endpoints) « Richard Seroter's Architecture Musings
  3. R-ESB another way to use ReST in BizTalk 2013 « Nino Crudele's Blog
  4. Reading Notes 2012-12-17 | Matricis
  5. 2012 Year in Review « Richard Seroter's Architecture Musings
  6. BizTalk 2013 and Rest « Connected Pawns
  7. Yes Richard, You Can Use Ampersands on the BizTalk REST Adapter (And Some Asp.NET Web API Tips) | Richard Seroter's Architecture Musings
  8. Automating BizTalk Events with Windows Azure, BizTalk 2013 and ASP.Net | BizTalk Events
  9. TNWiki Article Spotlight - BizTalk Server: REST Services Error Handling - WikiNinjas - Official Blog of TechNet Wiki - Site Home - TechNet Blogs
  10. Exposing REST Endpoints – HTTP GET with No Query String | Connected Pawns
  11. Exposing Simple REST Service | Integrating Mules

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 264 other followers

%d bloggers like this: