Consuming Business Analyst Online API SOAP Services

In the following walkthrough, we demonstrate how to use Visual Studio to consume the Online API SOAP Authentication and Report service WSDLs and execute tasks through the Online API. This walkthrough describes a simple workflow consisting of two steps. While this particular example is illustrated in Visual Studio 2010 and the C# programming language, the equivalent, or similar steps, can be taken with previous versions of Visual Studio and in other .NET languages such as VB.NET.

Step 1: an Online API token is generated with Online API subscription credentials. A valid token represents authenticated and authorized subscription credentials and can be used to execute subsequent tasks with the Online API. In the case of this walkthrough and in most of the documented SOAP samples, valid and working sample credentials are provided in the sample code.

Step 2: the previously generated token is used to obtain a list of accessible Online API report templates based on the subscription type associated with the user credentials.

Steps similar to those described in the walkthrough can be leveraged to execute all of the SOAP samples within the documentation.

Note - a token can be generated with the standalone Authentication class (through the Authentication WSDL) or through the BAOReportHelper class. The primary difference is, that the BAOReportHelper class renews to token automatically if it expires and becomes invalid. When using the Authentication class, the client application is responsible for token timeout management.

 

Create the Windows Application Project

1. In Visual Studio 2010 or newer, click File in the Menu Bar, then select New > Project in the menu.
2. In the New Project dialog, select Visual C# project type.
3. Then select Console Application.
4. Type a project name. For example, type BAOMap.
5. Click OK.

   

   
   

 

Add Web References to Esri Business Analyst Online API SOAP Services

1. Select Solution Explorer within your project.
2. Right-click the References item.
3. Click Add Service Reference.

   

   Inside the Add Service Reference dialog you will need to click on the Advanced button and the subsequent Add Web Reference button as illustrated in the following two screenshots below.

   

   
   

   

    

   Step 1: Generating a Token Using Valid Subscription Credentials

   Business Analyst Online API SOAP Services are secured to permit only authorized users. The security is implemented by using token-based authentication. Before a client accesses Business Analyst Online API SOAP Services, it must call Authentication or Get Token Web Services with a user name and password over a Secure Hypertext Transfer Protocol (HTTPS) Secure Sockets Layer (SSL) connection. These security measures minimize the risk that an unauthorized user can access Business Analyst Online API SOAP Services. HTTPS with SSL minimizes the risk that a valid login information can be stolen. If the user name and password are valid, Authentication Web Service returns a time-limited token. The token is a binary encoded string that the client application uses to call Business Analyst Online API SOAP Services. Further information regarding the getToken method can be found here.

   Note - the Business Analyst Online API SOAP Services use the default port 80 for HTTP URLs (URLs which begin with http://) and the default port 443 for HTTPS URLs (URLs which begin with https://).

   Adding the Web Reference:
   In the Add Web Reference dialog, ¹enter the Web service endpoint to the WSDL for an Esri Business Analyst Online API SOAP Web service in the URL combo box and ²Click the green arrow. For example:

   http://baoapi.esri.com/services/Authentication?wsdl

   Note that "?wsdl" is appended to specify that the WSDL for the Business Analyst capable Map service should be returned. The methods of the Business Analyst Online SOAP proxy should be displayed. ³Change the Web Reference name to something intuitive, for example "AuthenticationRef", and ⁴click Add Reference. The Business Analyst Online's Map Service proxy and value objects are created for you.

   

    

   Step 2: Obtain a List of BAO Report Templates

   Add another web reference so you can dynamically obtain a list of BAO report templates accessible with your subscription. Input the following inside the url combo box:

   http://baoapi.esri.com/services/BAOReport?wsdl

   Again, the Web reference name should be somthing intuitive - in this case, "BAOReportsRef". The fully-qualified namespace for the Business Analyst Online API SOAP Web Services proxy and value objects will be BAOMap.BAOReportsRef.

   

   By consuming the Business Analyst Online API SOAP WSDL and generating the proxy classes and value types in your IDE, they will be integrated into and recognized by your development environment as if they were a standard coding library. This will make your job of developing custom applications with Business Analyst Online API SOAP Services methods fast and easy.

    

   Add Code

   You can start consuming the Business Analyst Online API SOAP Services and create your own applications now. The sample code below shows how to create a new instance of BAOReport proxy and share it with other classes of the project.

   
   View code
   

   using System;
   using System.Collections.Generic;
   using System.Linq;
   using System.Text;
   //  Place the proxy references in the visible namespace
   using BAOMap.AuthenticationRef;
   using BAOMap.BAOReportRef;
   
   namespace BAOMap
   {
       class Program
       {
           //  Example using the Authentication class only
           //  See alternate example using the BAOReportHelper class
           static void Main(string[] args)
           {
               // Create Authentication class instance
               Authentication authclient = new Authentication();
   
               // Generate token using valid subscription credentials
               string username = "BAOAPISAMPLE";
               string password = "baoapisample";
               // NOTE: These working sample credentials are geofenced to the two Redlands ZIP codes
   
               string token = authclient.getToken(username, password);
   
               // Create BAOReport class instance to access BAO tasks
               BAOReport baoReportClient = new BAOReport();
   
               // Dynamically obtain a list of BAO report templates accessible with your subscription
               List reportTemplates = baoReportClient.GetReportTemplates(null, token).ToList();
   
               // Print out the names and IDs of the availabel report templates
               foreach (ReportTemplateInfo reportTemplate in reportTemplates)
               {
                   Console.Write("REPORT NAME:" + " " + reportTemplate.Title + "\nREPORT ID:" + "   " + reportTemplate.Name + "\n\n");
               }
   
               Console.WriteLine("\n\nPress any key to continue.");
               Console.ReadKey();
   
           }
       }
   }