Crafting HTTP Requests for the AppFxWebService.asmx

Infinity's Web API is fairly well documented, especially if you're going to be referencing the web service as a web reference in a .NET (Visual Studio), PowerShell, or Java project. This content attempts to explain how HTTP requests to AppFxWebService.asmx can be manually crafted for use and/or testing with tools like Fiddler.

Choosing an endpoint

To begin using the API, you must first choose what functionality you want to use. This endpoint will determine what data you will send, and what you can expect to receive in response. This document does not describe each endpoint in detail, but rather how to find the endpoints and explore them.

The Endpoint Reference Page

The Endpoint Reference page is a very useful tool for Infinity systems (such as Blackbaud CRM or ResearchPoint) that will allow you to see functionality exposed to you via the Web API. There are a couple ways to access the Endpoint Reference page, but not all of them may be applicable depending on how you access your Infinity product. If, when accessing your Infinity product you come to the splash or "Candy Store" page with many choices of how to continue, including: Web Shell, Web dashboard, Mobilize, Utilities,Endpoints, and Browser, then finding your endpoints is simple. All you have to do is click on the Endpoints link and it will take you to the Endpoint Reference page.

If you do not have the above landing page available to you, you can still access it. From inside your Infinity application, copy the entire URL up to `/webui/...`

For example, if your starting page URL after logging in is http://localhost/bbappfx/webui/webshellpage.aspx?databasename=BBInfinity you should copy http://localhost/bbappfx.

Once you have this base URL, add /endpointhelp.aspx?databasename=BBInfinity to the end of it. The resulting URL, http://localhost/bbappfx/endpointhelp.aspx?databasename=BBInfinity, will take you to the Endpoint Reference page.

Once on the page, there are many things to explore, but if you're reading this document the one you probably care about is Blackbaud AppFx Web Service.

The AppFxWebService documentation lists the available operations. Your integration software can use these operations to get things done in Blackbaud CRM or ResearchPoint..

AppFxWebService.asmx Endpoint Description

Blackbaud’s Infinity Web Services APIs can be used by custom third party software to interact with individual features via HTTP. Every application feature is accessible via standard web services accessible from any programming tool that utilizes XML, HTTP, and SOAP.This page describes the multitudes of operations that are supported by the Web API. It's up to you to scan the list to find an operation that might suite your needs, but for the rest of the document we will look at SimpleDataListLoad.

The table below provides an abbreviated guide to some of the most essential operations for performing CRUD type activities (Create, Read, Update, and Delete), along with other operations like record searches and listing records and look-up code table values. These operations typically require the ID of the feature. For more information on locating and securing Infinity features, see Add Features to Infinity System Role.

Example: Essential AppFxWebService.asmx CRUD Operations

When you click on an operation description, you will be taken to a page with lots of XML. This is a helpful description of the SOAP requests and responses that the API consumes and produces. Specifications for SOAP 1.1 and SOAP 1.2 are shown for each endpoint. The first XML document shown is the SOAP request, which you will need to craft. The second XML document shown is the SOAP response, which you will have to handle.

Although we all wish that this operation description page was the end of the story, there is a bit more to be done before a request can be successfully sent.

Headers

Most of the headers that you'll need are described in the Endpoint description page above the SOAP request example. For example:

POST /bbappfx.dev.firebird/AppFxWebService.asmx HTTP/1.1

Host: localhost

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "Blackbaud.AppFx.WebService.API.1/SimpleDataListLoad"

are all but one of the headers you will need to make a successful SOAP 1.1 POST request. The one that is missing is the `Authorization` header.

Authentication

Since you must be logged in to use the application, the API is only available to authenticated users, and that includes your application. Infinity supports a few types of authentication, including Basic and NTLM. For more information on authorization, see Authentication and Authorization.

Basic Authentication

Basic authentication is simple.

1. Create a string username:password from your Infinity login credentials or create a username PAT for a proxy user.
2. Base64 encode that string.

Take that string and add the following header

Authorization: Basic YOURBASE64ENCODEDAUTHENTICATIONSTRING

And that's it! Your request will be authenticated now.

NTLM Authenticaion

Describing how to manually compute an NTLM signature and use it in this context is currently beyond the scope of this document. It is an option, though, if you cannot use Basic authentication.

Most of the SOAP request body is perfectly described by the endpoint description page. You can copy-paste and modify the sample request and be 90% of the way to a perfectly functioning request. However, there are two bits of information that you will need to add to the request to make it work correctly.

ClientAppInfo

One thing that the sample request does not describe is an element that must be included called `ClientAppInfo`. Its format is as follows:

<ClientAppInfo 
        REDatabaseToUse="YOUR DATABASE IDENTIFIER/KEY" 
        ClientAppName="THE NAME OF YOUR REQUESTING APPLICATION" 
        TimeOutSeconds="THE NUMBER OF SECONDS BEFORE A REQUEST TIMES OUT"
        />

REDatabaseToUse

Your database identifier/key will vary. For this example, I am using 'BBInfinity'. Your database key will most likely vary. Read below.

This is the identifier of the database your Infinity product uses. This is also known as the 'database key'. You can find this value in the URL when you are using the product. For example, on the landing page of Blackbaud CRM/Research Point the URL is

http://localhost/.../webshellpage.aspx?databasename=BBInfinity

and we can see that the database identifier is `BBInfinity`.

ClientAppName

This is a name that you should come up with to identify your application to the API. It should be unique and specific to your application. The Infinity application can use this application name for auditing purposes when additions, edits, or deletes occur to the data within the database tables.

TimeOutSeconds

The number of seconds before the request times out. I will use 120 seconds for this setting.

There are other attributes within the ClientAppInfo element. A brief description is provided below:

RunAsUserID

Optional. This attribute is not relevant for API Development and should be omitted. Within the Infinity user interface, this attribute is necessary to support system administrators who which to verify security for specific users.

SessionKey

Optional. The value for this attribute can be obtained via a prior call to the SessionStart operation on the AppFxWebService.asmx. SessionStart returns a session key to be used to main client state between calls to the service. Using this setting provides a slight performance benefit as some internal data is cached for the user during the session.

SOAP gotchas

Because Infinity's web service uses SOAP, it is important to be aware of some of the intricacies of SOAP that might not be immediately obvious and are not present in the sample request. It may be beneficial to have the SOAP standard definition on hand.

Strict typing of ambiguous data

In SOAP, data values that have an ambiguous type must have their type declared in the request so they can be properly serialized. With Infinity applications, this mostly only applies to the `Values` elements in a request's `Parameters`. The Rules for Encoding Types in XML can help to describe what you must do, and a list of included datatypes in XML is also useful when typing request parameters.

A complete SimpleDataListLoad SOAP 1.2 request

Non-functional, with parameters

Here is an example of a complete SimpleDataListLoad, with parameters. Sending this request, while valid, will probably not return meaningful results.

Headers:

Host: localhost

Content-Type: application/soap+xml; charset=utf-8

Content-Length: LENGTH

Authorization: Basic 11111111111111111111

Request Body:

<?xml version="1.0" encoding="utf-8"?>
    <soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
      <soap12:Body>
        <SimpleDataListLoadRequest xmlns="Blackbaud.AppFx.WebService.API.1">
          <ClientAppInfo REDatabaseToUse="BBInfinity" ClientAppName="Test App" TimeOutSeconds="100" RunAsUserID="00000000-0000-0000-0000-000000000000" xmlns="Blackbaud.AppFx.WebService.API.1" />
          <DataListID>1d5fc077-0049-483f-a65c-0c17d57476a4</DataListID>
          <DataListName>Scheduled Programs By Date Simple List</DataListName>
          <Parameters>
            <Values xmlns="bb_appfx_dataforms">
              <fv ID="DATE">
                <Value xsi:type="xsd:string">08/21/2013</Value>
                <ValueTranslation>08/21/2013</ValueTranslation>
              </fv>
              <fv ID="EVENTDATE">
                <Value xsi:type="xsd:string">08/22/2013</Value>
                <ValueTranslation>08/22/2013</ValueTranslation>
              </fv>
              <fv ID="SALESMETHODTYPECODE">
                <Value xsi:type="xsd:int">0</Value>
                <ValueTranslation>0</ValueTranslation>
              </fv>
            </Values>
          </Parameters>
          <SecurityContext>
            <SecurityFeatureID>1d5fc077-0049-483f-a65c-0c17d57476a4</SecurityFeatureID>
            <SecurityFeatureType>SimpleDataList</SecurityFeatureType>
            <RecordContext>
              <RecordID/>
              <RecordType/>
            </RecordContext>
            <AttributeContext>
              <AttributeCategoryID/>
            </AttributeContext>
          </SecurityContext>
        </SimpleDataListLoadRequest>
      </soap12:Body>
    </soap12:Envelope>

Functional, without parameters

This request has no parameters, but once adjusted to use values specific to your Infinity product, will return meaningful results in a response for you to examine.

Headers:

Host: localhost

Content-Type: application/soap+xml; charset=utf-8

Content-Length: LENGTH

Authorization: Basic 11111111111111111111

Request Body:

<?xml version="1.0" encoding="utf-8"?>
    <soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
      <soap12:Body>
        <SimpleDataListLoadRequest xmlns="Blackbaud.AppFx.WebService.API.1">
          <ClientAppInfo REDatabaseToUse="BBInfinity" ClientAppName="Test App" TimeOutSeconds="100" RunAsUserID="00000000-0000-0000-0000-000000000000" xmlns="Blackbaud.AppFx.WebService.API.1" />
          <DataListID>ea2c8565-85cb-433c-94f8-229e079f0445</DataListID>
          <DataListName>Record Types</DataListName>
          <Parameters/>
          <SecurityContext>
            <SecurityFeatureID>ea2c8565-85cb-433c-94f8-229e079f0445</SecurityFeatureID>
            <SecurityFeatureType>SimpleDataList</SecurityFeatureType>
            <RecordContext>
              <RecordID/>
              <RecordType/>
            </RecordContext>
            <AttributeContext>
              <AttributeCategoryID/>
            </AttributeContext>
          </SecurityContext>
        </SimpleDataListLoadRequest>
      </soap12:Body>
    </soap12:Envelope>

Tip: Those new to Infinity API development or those who want more details on the underlying concepts need to check out our step by step tutorial: Using Fiddler to Compose HTTP Requests