API Overview

The Infinity platform is designed specifically to allow integration scenarios, and as part of that design, every application feature is accessible through standard web services accessible from any programming tool that utilizes XML, HTTP, and SOAP. Data lists and other Infinity features can be accessed with a call to the primary web service API named AppFxWebService.asmx or one of the other programmatic wrappers. An Infinity API developer can choose one of these HTTP-based API options to get the job done. This holds true for any application written on the Infinity platform. 

Note: The bbui-angular library is also available to wrap up calls to the Infinity web shell and UI Modeling services into Angular services. For more information, see the bbui-angular GitHub repo.

The API is Feature-centric

An Infinity application is an aggregation of many individual features. An Infinity feature such as a data form is designed to serve a specific need within the Infinity application. For example, the data form that adds an individual is named "Individual, Spouse, Business Add Form." This feature is designed to acquire data from an outside source (an end user in the shell or a custom API software developer) and save data to the Infinity database tables that represent an individual. 

To get something done with the API, you must first locate the feature and then automate that feature using the API. You do not negotiate a business object model. There is not a constituent or individual object that represents an individual. Or, let's say you want to list all of the expenses for a specific event. There isn’t an event object with an expenses property that returns an array expenses. Instead, find the name of the feature within the Infinity user interface that lists the expenses for an event and then write code using the API that automates that feature to retrieve that data from your program. While most other software platforms have an API that consists of a business object model to abstract the programmer away from the details of the relational database, the Blackbaud Infinity platform abstracts you from the database through the features. 

AppFxWebService.asmx Does It All

At a high level, the user interface "shell" that ships with all Infinity-based applications utilizes the Blackbaud AppFx Web Service (AppFxWebService.asmx) to communicate with Infinity-based features. "Features" refers to functionality created using the Infinity SDK such as data forms, data lists, record operations, etc. The AppFxWebService.asmx exposes every application feature including data lists, data forms, query, batch, security, KPIs, business operations and more.

A web service is programmable application logic accessible through industry standard web protocols. Just because the Blackbaud AppFx Web Service is built with Microsoft ASP.NET does not mean that the service is only available to other Microsoft applications. The phrase "standard Web protocols" is important because consumers of the Blackbaud AppFx Web Service can do so with any programming language (Java, PHP, .NET, etc.). Consumers of the web service do not need to know anything about the .NET platform, object model, or programming language used to implement the service; they only need to understand how to send and receive SOAP messages (HTTP and XML). Any platform or framework that understands SOAP should be able to communicate with the Blackbaud AppFx Web Service.

To use the AppFx Web Service within a .NET custom client, you set a web reference to the .asmx.  Visual Studio creates a proxy class within your client project to handle communication to the .asmx on your behalf. You can then start to program against the proxy class and automate Infinity features. The code snippet below leverages an add data form to add an event expense to an event.

The AppFx Web Service is loosely typed and feature-centric. You use it to point to specific feature, issue a request, and retrieve the reply. The API does not consist of an object model. You won't find an AddExpense method on an Event business object. Instead, the DataFormSave method takes the system record ID or name of a feature that saves the event expense information. To save an event expense through the AppFx Web Service, you first have to search for the appropriate Add Data Form feature within the user interface. After you land on the metadata page for the feature, you can obtain the data form's system record ID or name. In the code sample below, this Add Data Form is named "Event Expense Add Form." In your code, you make a call to the AppFx Web Service's DataFormSave operation. One of the parameters in the request is the ID or name of the feature/Add Data Form. Below is a code snippet that leverages the web service to call the Event Expense Add Form feature to save an expense to a specific event.

Wrap It up, I'll Take It

Your communication with Infinity-based applications can utilize either the Blackbaud AppFx Web Service (AppFxWebService.asmx) directly or through one of the various middleware "wrappers" that calls the AppFxWebService.asmx on your behalf. The purpose of a wrapper is to provide a different way to use the mechanism that is wrapped. Typically, the wrapper provides a simpler interface to the AppFxWebService.asmx. For example, the Blackbaud.AppFx.WebAPI.dll assembly and the Blackbaud.AppFx.*.WebAPIClient assemblies adapt the web service for .NET developers. Choice is good. The good news is you have a choice as to how you call the Blackbaud AppFx Web Service. 

You can choose to interact directly with the AppFxWebService.asmx or one of three wrappers:

  1. Blackbaud.AppFx.WebAPI.dll  (.NET Only)

  2. BizOps Web Services (Any Platform)

  3. Blackbaud.AppFx.*.WebAPIClient.dlls. (.NET Only)

Which API flavor you use to you communicate with an Infinity application depends on several factors:

  1. Do you use .NET as your software development platform or a non-.NET language such as Java or PHP?

  2. Do you need to access to more advanced features beyond simpler calls to create, read, update, delete, list, and search operations (CRUDLS)?  In other words, do you prefer a single mechanism to access every type of feature?

  3. Do you prefer interacting with strongly typed objects rather than loosely typed objects?

The table below lists the various API options along with a matrix of their advantages and disadvantages:

What is CRUDLS?

CRUDLS is an acronym that stands for Create Read Update Delete, List and Search.  Each letter in the acronym translates to a type of feature within an Infinity application. 

CRUDLS

Feature Types

Create

Add Data Form

Read

View Data Form

Update

Edit Data Form

Delete

Record Operation (Delete)

List

Data List , Code Table

Search

Search List

Blackbaud.AppFx.WebAPI.dll: .NET Programming with Access to Any Type of Feature

The Blackbaud.AppFx.WebAPI.dll is a lightweight proxy wrapper around the AppFxWebService.asmx. The Blackbaud.AppFx.WebAPI.dll is standalone assembly with only the generated SOAP client classes for the AppFx Web Service. If you install the SDK, you can find the Blackbaud.AppFx.WebAPI.dll in SDK\DLLReferences folder. In this scenario, we have access to all platform features through the AppFx Web Service.

Blackbaud.AppFx.WebAPI.dll provides loosely typed access to any Infinity feature. If you use Visual Studio and .NET as your software development platform and you would prefer a single mechanism to communicate with the Blackbaud AppFx Web Service, then the Blackbaud.AppFx.WebAPI.dll may be your best bet. Just like the AppFxWebService.asmx, Blackbaud.AppFx.WebAPI.dll provides access to features beyond CRUDLS, meaning you can access features such as KPIs, business processes, batch, etc. You do not have to set a web reference to the web service within your project, you simply add a regular assembly reference to the Blackbaud.AppFx.WebAPI.dll within your project.

In the diagram above, you can see that the Blackbaud.AppFx.WebAPI.dll (light green circle) is a client side DLL that wraps the Blackbaud AppFx Web Service (blue circle).  It provides access to all types of features beyond CRUDLS.

Request-Response Pattern

The Blackbaud API utilizes a request-response pattern. The pattern consists of request-response pairs. An operation is called on the proxy, such as DataListLoad. The request is passed to the operation. A reply is received from the proxy. Each request and reply object type is tailored to the type of operation. Let's assume we use the Blackbaud.AppFx.WebAPI.dll to communicate to an Infinity application instance. Since we need to "load" a data list with data, we will call the proxy's DataListLoad operation. This enables us to retrieve a list of data with multiple columns from the Infinity application.

To grab data from a data list, we package a request (DataListLoadRequest) that includes the name or ID of the data list, pass the request to the DataListLoad operation, and receive a response (DataListLoadReply). In VB.NET pseudo-code, the call to retrieve the data from a data list looks something like this:

Dim _appFx As Blackbaud.AppFx.WebAPI.ServiceProxy.AppFxWebService
Dim Request As New Blackbaud.AppFx.WebAPI.ServiceProxy.DataListLoadRequest
Dim Reply As New Blackbaud.AppFx.WebAPI.ServiceProxy.DataListLoadReply

Request.DataListName = "Event Calendar Event List"
Reply = _appFx.DataListLoad(Request)

Below is some more pseudo-code; this time to retrieve data from a code table. You can begin to see the request-response pattern emerge. An operation is called on the proxy:  CodeTableEntryGetList. The request is passed to the operation. A reply is received from the proxy. Each request and reply type is tailored to the operation. So, the proxy's CodeTableEntryGetList operation requires a Blackbaud.AppFx.WebAPI.ServiceProxy.CodeTableEntryGetListRequest and returns a Blackbaud.AppFx.WebAPI.ServiceProxy.CodeTableEntryGetListReply.

Dim _appFx As Blackbaud.AppFx.WebAPI.ServiceProxy.AppFxWebService
Dim Request As New Blackbaud.AppFx.WebAPI.ServiceProxy.CodeTableEntryGetListRequest
Dim Reply As Blackbaud.AppFx.WebAPI.ServiceProxy.CodeTableEntryGetListReply

Request.CodeTableName = "EVENTEXPENSETYPECODE"
Reply = _appFx.CodeTableEntryGetList(Request)

Here is one more pseudo-code example, this time to delete a record using a type of feature known as a record operation. Since we need to delete a row of data, we use the appropriate record operation/feature named "Event Expense: Delete." The proxy's RecordOperationPerform operation requires a Blackbaud.AppFx.WebAPI.ServiceProxy.RecordOperationPerformRequest and returns a Blackbaud.AppFx.WebAPI.ServiceProxy.RecordOperationPerformReply.

Dim _appFx As Blackbaud.AppFx.WebAPI.ServiceProxy.AppFxWebService
Dim Request As New Blackbaud.AppFx.WebAPI.ServiceProxy.RecordOperationPerformRequest
Dim Reply As Blackbaud.AppFx.WebAPI.ServiceProxy.RecordOperationPerformReply

Request.ID = _eventExpenseID  
Request.RecordOperationName = "Event Expense: Delete"
reply = _appFx.RecordOperationPerform(Request)

BizOps:  A Web Service for Each Type of CRUDLS Feature

BizOps (Business Operations Services) are granular. Each BizOp web service end point represents a single Infinity feature. Each BizOp web service end point wraps the generic AppFx Web Service. If you have a small application that only needs access to a few features, you can add the necessary references to the individual endpoints and begin to program.  Below is a listing of the CRUDLS features that can be addressed via a BizOps:

In the diagram above, you can see that a BizOp endpoint (light blue circle) is a web service that wraps the Blackbaud AppFx Web Service (dark blue circle). It provides access to every CRUDLS feature. Please note that since only CRUDLS features are supported, BizOps does not allow interaction with more advanced feature types such as Ad-hoc Query, Batch, Business Process, KPI, Smart Query, etc.

Blackbaud.AppFx.*.WebAPIClient.dll’s:  CRUDLS Luxury for .NET Programmers

The Blackbaud.AppFx.*.WebAPIClient.dlls contain strongly typed wrapper classes that wrap and therefore leverage the AppFxWebService.asmx. These assemblies only allow access to CRUDLS. The Blackbaud.AppFx.*.WebAPIClient.dlls are .NET client side DLLs that organize related features together into namespaces that make the platform's structure easy to navigate. These assemblies are included with the SDK and can be found by filtering your SDK\DLLReferences folder on Blackbaud.AppFx.*.WebAPIClient.dll.

Please note that since only CRUDLS features are supported, Blackbaud.AppFx.*.WebAPIClient.dlls do not allow interaction with more advanced feature types such as Ad-hoc Query, Batch, Business Process, KPI, Smart Query, etc.

Feature Automation is Fun!

  1. Every application feature is accessible through a web service named AppFxWebService.asmx.

  2. If you prefer, you can choose from one of the wrappers that wrap the AppFxWebService.asmx:

    1. Blackbaud.AppFx.WebAPI.dll 

    2. BizOps

    3. Blackbaud.AppFx.*.WebAPIClient.dlls

  3. Some wrappers are in the form of .NET DLLs that ship with our SDK, while BizOps consist of individual web service endpoints.

  4. The Infinity API is feature-centric. Locate the feature using the feature metadata – automate the feature using one of our APIs.

  5. Infinity API exposes programmatic access to individual features not an object model.

    .

Infinity Web API