Global Change Console Sample Application
This code sample will teach you the basics of building an application that integrates with Blackbaud CRM via the AppFxWebService.asmx. The application is a relatively simple console app written in C# that utilizes the AppFxWebService.asmx to list information about relevant the Global Change Process business process that is used to launch the custom global change definition named Address Coordinate TimeZone Global Change (Custom). While this custom global change is referenced in the code, you are free to experiment and switch out the references to your own global change definition and global change instance, if desired. This project is targeted to the .NET 4.0 Framework.
What You Will Learn
-
How to create a variable from the web service proxy class.
-
How to initialize the web service proxy with the URL, credentials, and client application name.
-
Two methods for how to provide credentials for authentication: basic authentication and default Windows credentials for the user running the console application.
-
How to provide a database key to identify the database.
-
How to utilize the Request-Response Pattern .
-
How to communicate with pending asynchronous operations using the familiar events-and-delegates model.
-
How to retrieve information about a business process definition.
-
How to retrieve information about a global change definition.
-
How to retrieve the saved parameters for a global change instance.
-
How to launch a business process both synchronously and asynchronously .
-
How to write an event handler to catch the BusinessProcessLaunchCompleted event.
-
How to retrieve the most recent status results for a business process/global change.
-
How to retrieve a list and display a history of global change instance runs.
-
How to handle SoapExceptions returned from the web service.
Access the Code
The sample console application was developed in Microsoft Visual Studio 2010 using C#. Download and unzip the file containing the source code. After it is unzipped, you can access the code by opening the solution file named GCInfoConsoleApp.sln within a folder named GCInfoConsoleApp. The solution contains a single C# console project named GlobalChangeConsoleApp. The code can be found within a file named Program.cs.
Tip: You can download a copy of the Global Change Console Application source code here.
What Does the Code Sample Do?
The application first displays information about the "Global Change Process" business process that launches global changes.
Next, the application displays information about a global change definition (including the parameters) such as our custom "Address Coordinate TimeZone (Custom)" global change.
Then it displays the a global change instance's parameter and values for a global change instance. The end user has a choice to launch the business process (which launches the global change) either synchronously or asynchronously. The program pauses and waits for a value of either "sync" or "async." Press enter to resume the application.
If synchronous, the application launches the business process but blocks the program's execution until it completes.
After the synchronous call completes, the results of the launch are displayed followed by the most recent status of the business process run.
If asynchronous, the application performs the launch yet remains responsive by retrieving the most recent status results.
After the BusinessProcessLaunchCompleted event is handled, the application displays the results of the launch, followed by the most recent status.
Finally, the application provides a listing of global change instance runs.
Operations
The console application calls the following operations on the AppFxWebService:
| Operation Name | Description |
|---|---|
|
BusinessProcessInformation |
Displays information on a business process definition as defined with a BusinessProcessSpec. |
|
GlobalChangeInformation |
Displays information on the global change definition as defined with a GlobalChangeSpec. |
| GlobalChangeParametersLoad | Returns the saved parameters for a global change instance. |
| BusinessProcessLaunch | Launches a given business process synchronously using a BusinessProcessID and ParameterSetID. |
| BusinessProcessLaunchAsync | Launches a given business process asynchronously. See BusinessProcessLaunchCompleted event. |
| BusinessProcessLaunchCompleted | The event provided by the web service when the asynchronous business process launch is completed. Handles the event by adding a new event handler of type BusinessProcessLaunchCompletedEventHandler. |
| DataFormLoad | Displays most recent status information for the given business process parameter set. Utilizes a data form named "Business Process Parameter Set Recent Status View Form." |
| DataListLoad | Returns a status list for the global change business process. Utilizes a data list named "Global Change Process Status List." |
In addition to the AppFxWebService.asmx operations listed above, the code utilizes an HTTP web handler (.ashx) named BusinessProcessInvoke.ashx as an alternative way to launch a business process synchronously using a database key name, BuinessProcessID, and ParameterSetID.
Prerequisites
You need to understand of the following:
-
How to create a global change.
-
How the Global Change Process business process works to launch a global change.
-
The Global Change Tables used to store global change definitions, instances and statuses on global change runs.
-
The code references a custom global change. You can either build and deploy the custom global change, complete the Exercise for Creating a CLR Based Global Change, or point to a different global change in the source code.
-
Within Blackbaud CRM, you need a global change configured including its relevant parameter values.
-
How to modify the web reference to the correct AppFxWebService.asmx web service URL path.
Reference a Global Change Definition, Global Change Instances via GUIDs
Within the source code, the business process definition, global change definition, and global change instance are identified via the appropriate GUID. There is no user input to select the global change instance to run. The GUIDs are primary key values in the appropriate Global Change Tables. In a real world application, the developer would need to list the choices of global change definition and global change instances and let the end user select the global change to start and display information about. While the source code is not fancy, it does represent useful API calls and orients the developer to the appropriate GUIDs in the database tables.
Modify the Web Reference URL
In the project's Web Reference folder, you will find a web reference named "localhost" has already been established to the AppFxWebService.asmx web service. You need to change the value of the URL to this web service by right-clicking the localhost web reference and selecting Properties (Alt+Enter) from the context popup menu.
With the Properties open, modify the path to the URL for the web service. You need to point the URL to an installed instance of Blackbaud CRM. For details, see Locating the AppFxWebService.asmx Endpoint and Adding a Web Reference to AppFxWebService.asmx.
You can also set the URL in the code. Within the program.cs code file, check out the method named InitAppFxService(). Here you will find the URL is being set in code. You need to modify the URL path to fit your environment.
The Relationship between Business Processes and Global Changes
To launch a global change, we have to launch a business process that has been designed to launch a global change. Global changes are launched via a specific business process named Global Change Process. The Global Change Tables section helps to describe and illustrate this relationship. Its worth a read!