One of the “Core tenets” of the Infinity platform is that is should be “Web delivered”.
In support of this tenet, we’ve engineered all Infinity-based applications (BBEC, RP, Altru, et al) so that they expose their data (and metadata!) via web services. Every data form, record operation, data list, batch, query, search list, etc., can be completely accessed (and manipulated!) using one of the various endpoints described by the web service. At last count, there are over 16,000 distinct features in the system, which means there are over 16,000 distinct web service endpoints you can call**! When you consider that you can even use the Infinity Platform SDK to add brand new features to the system (which in turn automatically yield brand new web service endpoints for those features), the breadth of functionality exposed to consumers is staggering!
(**minor clarification – technically, there are only ~200 physical endpoints that make up the Infinity web service. All features in the system are accessed using those endpoints, so the number of logical endpoints grows as the number of features in the system grows. A good discussion on this request/response pattern can be found in this book.)
In this post, I’m going to provide a very basic example for how to access one of those 16,000 features to fetch some information about a constituent record. Specifically, I’ll use the “Constituent Summary Profile View Form” feature to return a few interesting fields like the primary address, email, and phone number for the constituent.
Now there are lots of choices for which tool to use in order to access the web service – any tool capable of issuing SOAP requests will do. For this example, I’m going to use PHP which is a very popular (and free!) scripting language that runs on many contemporary web servers (IIS, Apache, etc). PHP code is executed on the server, similar to ASP, and the resulting html is then sent down the wire to the client. Conveniently, PHP has a built-in SOAP client (intuitively named soapClient) which makes it very easy to consume web services.
However, access to the web service itself is serious business – another one of the “Core tenets” of the Infinity platform is “Security”, and we’ve engineered it in at the web service level. This means that all access to the system is secure – even access outside of the traditional “client” shell or browser. There is no “back-door” API that allows a 3rd-party application to access resources that haven’t been granted it.
In order to call the web service for an Infinity-based application:
- You must be an authenticated user in that application
- You must be granted security permission to the feature being used
- If record-level security is enabled (site security, constituent security, etc), you must have security permission to the record itself
To satisfy security requirement #1, this example will make use of the Trusted Subsystem pattern where calls to the BBEC web service will be made using the credentials of a user account specifically created for this purpose (not to be confused with the user who is seeing the web page). That user account will be added to a System Role in BBEC that has been granted permission to use the “Constituent Summary Profile View Form” feature (which will satisfy security requirement #2). For this example, assume record-level security is disabled so requirement #3 is met – if it were enabled, we would simply need to use a constituent record for which we had access.
Assuming the security requirements are met, accessing the web service is straightforward – only a few pieces of data are required:
- The URL to the web service definition language (the WSDL)
- The name of the database to use
- The ID of a constituent in the database (for this example)
Given those items, the PHP code below will create a soapClient object, pass it the appropriate user credentials, and then issue a DataFormLoad request to load the “Constituent Summary Profile View Form” form for a constituent.
The full PHP code for this example is provided below:
3: // This example shows how to use PHP to call the BBEC web service to fetch information about a constituent.
5: // the url of the BBEC web service definition language
6: $wsdl = 'https://someServer/bbappfx/appfxwebservice.asmx?wsdl';
8: // the database to use
9: $database = 'BBInfinity';
11: // the credentials to access the web service using basic authentication
12: $userName = 'someDomain\someUserName';
13: $password = '<password>';
15: // the ID of a constituent in the system
16: $recordId = '7FE91DD8-6EDD-435E-A738-A8A70C782D4D';
18: $options = array(
19: 'login' => $userName,
20: 'password' => $password,
21: 'soap_version' => SOAP_1_2,
22: 'exceptions' => true,
23: 'trace' => 1,
24: 'cache_wsdl' => WSDL_CACHE_NONE
27: // access the BBEC web service through a SoapClient object
28: $sc = new SoapClient($wsdl, $options);
30: // the app info object must be supplied with each request made to the BBEC web service
31: $clientAppInfo = array(
32: 'ClientAppName' => 'PHP Sample Application',
33: 'REDatabaseToUse' => $database,
34: 'TimeOutSeconds' => 120
37: // build the parameters for the DataFormLoad method (these correspond to properties of the DataFormLoadRequest type)
38: $req = array(
39: 'ClientAppInfo' => $clientAppInfo,
40: 'FormID' => '1f4fea31-5779-44db-bcce-ec5afa36d82b',// the data form instance ID of the 'Constituent Summary Profile View Form'
41: 'RecordID' => $recordId // the ID of a constituent
44: // invoke the DataFormLoad web service method, which returns a DataFormLoadReply object
45: $reply = $sc->DataFormLoad($req);
46: $dataFormItem = $reply->DataFormItem;
47: $fieldValues = $dataFormItem->Values->fv;
49: // pick off the desired info from the fields values returned by the web service
50: $address = $fieldValues->Value;
51: $phoneNumber = $fieldValues->Value;
52: $emailAddress = $fieldValues->Value;
56: <span>The following constituent information is from Blackbaud Enterprise CRM:</span>
64: echo $address;
74: echo $phoneNumber;
84: echo $emailAddress;
Here’s a screen shot of the resulting web page:
If you have the Infinity Platform SDK installed, you can find a more exotic PHP example that uses inheritance with the soapClient in the Samples\LAMPDemo folder. This example illustrates how to access the web service methods for loading data forms, data lists, simple data lists, and search lists. In order to run the example:
- Copy the PHP files in this folder to your web server
- Edit the infinity.php file and specify the url, database, credentials to use to access your Infinity web service
- Navigate to the search.php file in your browser
This will show the “inline” constituent search below:
Type in some criteria and click “Search” to see the results:
Select a record in the output, which will navigate to the constit.php page (notice the ID for the selected constituent is in the query string):
Update – here is a link to the updated PHP files from the Infinity SDK\LAMPDemo sample: