Click here to Skip to main content
Click here to Skip to main content

Tagged as

Invoking Bing Maps REST API through an Orchestration in BizTalk Server 2013

, 20 Feb 2014 CPOL
Rate this:
Please Sign up or sign in to vote.
This article attempts to explain how to invoke the Bing Maps REST API through an Orchestration in BizTalk Server 2013.

Introduction

This article quickly explains how to connect to a REST based service using BizTalk. A BizTalk Orchestration is used to talk to a simple Bing Geocoding service via REST API. BizTalk 2013 introduces a new adapter for REST which is WCF-WebHttp and also a new concept known as 'Variable mapping'

Quick References for further reading 

If you want a detailed introduction about REST and want to read further before reading this article,
refer to the following articles.  

Invoking Bing Geocoding REST API through BizTalk

Step 0: Apply for the Bing Maps API Application Key

Refer to this URL [http://msdn.microsoft.com/en-us/library/ff428642.aspx]

The following are the steps to invoke the Bing Geocoding REST API through BizTalk.

Step 1: Finalize the Bing Geocoding URL

  1. Finalize the Bing URL for Geocoding and generate XML document.

    http://dev.virtualearth.net/REST/v1
    /Locations?query=One%20Dell%20Way,%20Round%20Rock,%20TX%2078682&
    key=Ag_GDRUeN3ghulGjTGIAW1ziMR8j-aQ5cu8SbKI0x4wsL8WykRPdSV4lOb9XeptU&o=xml

    Notice the various parameters used in the URL.

    Parameter Name Explanation
    Query Address of the Geocode location
    Key Bing MAPS Application ID
    O Output value in XML or JSON.
  2. Generate the XML document by placing the URL in the browser.

  3. Right click on the browser and select View Source and then save it locally as BingRESTResponse.xml.
  4. Generate a schema (BingRESTResponse.xsd) out of the XML file saved in the previous step. This schema shall be imported into the BizTalk solution.

Step 2 BizTalk Administration Console Configuration

  1. Open BizTalk Administration Console to create a new Send Port.
  2. Choose the default ‘BizTalk Application 1’ or any other BizTalk Application of your choice.
  3. Observe the settings for the Send Port:'SP_BingMaps:REST'. Note that the send port is automatically created when you import the bindings file into the BizTalk application.
    Use the download link to download the Visual Studio 2012 BizTalk project and take a look at the BizTalk bindings file in the BindingFiles folder.

  4. The Receive Pipeline is set to XMLReceive, as the schema for the response has been generated in Step 1.

     

    Fill in all the details as shown in the screenshot.

  5. Click on the Configure button. See the screenshot below.

    HTTP Method and URL Mapping 

    Notice the attributes Name, Method and Url for every HTTP URL being mapped.

    <BtsHttpUrlMapping>
        <Operation Name="GetGeoCode" Method="GET" Url="?query={userAddressQuery}&key={BingMapsKey}&o=xml" />
    </BtsHttpUrlMapping>

    What is variable mapping?

    The technique of mapping the parameters with the actual values from the BizTalk Orchestration is known as Variable mapping. The variable mapping is done using the parenthesis {parameter}.

  6. Click on the Edit… button. NOTE that a BizTalk Property schema has to be created for the variable mapping. Note that the schema can be created after setting the values in the Variable mapping dialog. Click ‘OK’ and select the ‘Messages’ Tab.

    The screenshot below represents the Property schema specified in the Variable mapping dialog.

  7. Specify GET on the Outbound Message tab and click OK.

    Click OK several times and close all the dialog boxes to create a new Send Port for Bing Geocode.

    Note that the send port is automatically created when you import the bindings file into the BizTalk application.

Step 3: Open the BizTalk solution

Open the BizTalk solution ‘DSHS.GeoCoding.sln’ and note the following points.

  1. The 3rd shape in the orchestration is used to send a GET request to the Bing Geocoding Service.

  2. The elements of the message on the 3rd shape is mapped as BizTalk Message Context variables due to the property promotion (BingMapsRestParams.xsd). The elements in the input message are mapped as shown in the following table.

    Request Message Variables Message Context Variables
    ApplicationID BingMapsAPIKey
    QueryAddress UserAddressQuery

  3. The 4th shape is a receive shape where the response from the Bing Maps Service call is returned. This is mapped onto the schema (BingRESTResponse.xsd) which has been created in Step 1.
  4. The BizTalk map in the solution converts the Bing Maps API response into the appropriate XML format required by the consumer. This is very straightforward process.

Step 4: Create the BizTalk Drop file locations on the local box

  1. Create the BizTalk Drop locations
    BizTalk Input Folder C:\BizTalkDropLocations\DSHS.GeoCode\In
    BizTalk Output Folder C:\BizTalkDropLocations\DSHS.GeoCode\Out
    BizTalk Sample Input files C:\BizTalkDropLocations\DSHS.GeoCode
  2. Open the sample file DSHS_GeoCodingRequest_sample_1.xml located in the ‘SampleFiles’ directory. Note that the ApplicationID must be generated correctly, refer to Step 0 for obtaining the key correctly.

  3. Make changes to the Query Address XML tag and save the file.
  4. Import the bindings file (DSHS.GeoCoding.Bindings.xml) into BizTalk and deploy the solution correctly. Start the BizTalk Application.
  5. Copy + Paste the file into the BizTalk Input Folder ‘C:\BizTalkDropLocations\DSHS.GeoCode\In’
  6. Observe the GeoCode values in the BizTalk Output Folder ‘C:\BizTalkDropLocations\DSHS.GeoCode\Out’. See screenshot below.

  7. Validate the output file for the correct Geocode values.

Conclusion 

In this article we have attempted to connect to a REST based service using just the HTTP GET verb through a BizTalk orchestration. In future I shall attempt to connect to a complex REST based service.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Naveen Karamchetti
Architect AT&T Wi-Fi Services
United States United States
Naveen has done his Masters (M.S.) in Computer science, has started his career programming the mainframes and now has more than a decade of programming, development and design experience. Naveen has a sharp eye and keen observation skills. Naveen has worked for several companies and strived hard to build large scale business applications and bringing better solutions to the table.
Quite recently Naveen has built a fairly complex integration platform for a large bank. His hobbies include training, mentoring and research. Naveen spends his free time visiting National Parks nationwide.
 
Naveen has developed the BizTalk Control Center (BCC)
http://biztalkcontrolcenter.codeplex.com

Comments and Discussions

 
GeneralGood one PinmemberMember 1020732325-Feb-14 6:35 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.141015.1 | Last Updated 20 Feb 2014
Article Copyright 2014 by Naveen Karamchetti
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid