advanced configuration batch and import - fundraising for web viewoverriding the...

Business ProcessesInfinity SDK Training

Products GroupBlackbaud

May 5, 2023

Table of Contents1 Course Prerequisites...................................................................................................................................42 Learning Objectives.....................................................................................................................................53 Business Process Overview.......................................................................................................................6

3.1 Parameter Sets and Instances............................................................................................................6

3.2 Processing the Data............................................................................................................................6

3.3 SDK Developer Responsibilities..........................................................................................................7

3.3.1 Parameter Set Page..................................................................................................................7

3.3.2 Business Process Logic.............................................................................................................8

3.3.1 Status Page.............................................................................................................................10

4 Business Process Parameters..................................................................................................................134.1 Overview............................................................................................................................................13

4.2 Managing Parameter Sets and Starting a Business Process without a Pre-Process Edit Data Form...........................................................................................................................................................13

4.2.1 Configuring the Start Process Action Button...........................................................................15

4.3 Managing Parameter Sets and Starting a Business Process with a Pre-Process Edit Data Form.. .16

4.3.1 Configuring the Start Process Action Button with a Pre-Process Edit Data Form...................18

4.4 Using a QueryViewSpec as a Parameter for Output Formatting.......................................................20

4.4.1 Understanding the QueryViewSpec’s JoinField......................................................................24

4.5 Using a Selection as a Parameter to Restrict the Row Set...............................................................26

5 Building the Business Process Processing Logic.................................................................................275.1 When a business process instance starts…......................................................................................27

5.1.1 Application Locks.....................................................................................................................27

5.1.2 Infinity ASP.Net WebHealth Events.........................................................................................27

5.1.3 Status Updated........................................................................................................................28

5.1.4 Simultaneous Run Check........................................................................................................28

5.1.5 Validate() and Retrieving the Parameters...............................................................................28

5.1.6 StartBusinessProcess() Performs the Bulk of Data Processing..............................................28

5.2 Typical Duties for your Sub Class......................................................................................................29

5.2.1 Retrieve and Validate the Parameters: Validate()..................................................................29

5.2.2 Start the Business Process: StartBusinessProcess().............................................................30

5.3 AppBusinessProcess base class’ OutputView Property....................................................................33

5.4 Creating an Output Table via the CreateOutputTableFromView() function.......................................34

5.5 Optionally Creating a Selection of Processed Records via CreateIDSet() Function.........................36

Blackbaud – Internal Use Only Page 1 7/16/2010

5.6 Creating an Output Table via the CreateOutputTable() function.......................................................37

5.7 AppBusinessProcess base class’ CreateFieldsList Function............................................................37

6 Business Process Instance Status Page.................................................................................................386.1 Expression Data Form Drives Expressions on the Status Page.......................................................41

6.2 Summary View Data Form.................................................................................................................42

6.3 Recent Status Tab.............................................................................................................................43

6.4 History Tab........................................................................................................................................44

6.4.1 Deleting History.......................................................................................................................48

6.5 Job Schedules...................................................................................................................................48

6.5.1 Add, Edit, and Delete Job Schedule Actions...........................................................................49

6.6 Action Group......................................................................................................................................50

6.6.1 Start Process Action................................................................................................................50

6.6.2 Edit Process Action..................................................................................................................50

6.6.3 Generate WSF Action..............................................................................................................51

6.6.4 Create Job Schedule Action....................................................................................................53

6.6.5 Create Task Action..................................................................................................................55

6.6.6 Delete Process Action.............................................................................................................57

7 Typical Catalog Project Specs and Code................................................................................................587.1 BusinessProcessSpec.......................................................................................................................58

7.1.1 BusinessProcessSpec XML Element......................................................................................59

7.1.2 ProcessorComponent Element................................................................................................60

7.1.3 BusinessProcessOutputHeader Element................................................................................62

7.1.4 FormMetaData Element...........................................................................................................63

7.1.5 QueryViewSpec(s) to Define the Output Format (Optional)....................................................63

7.1.6 SQLFunctionSpec to Limit the Output.....................................................................................63

7.1.7 SQLStoredProcedureSpec to Retrieve the Parameters within the Processing Code.............63

7.2 Specs to Manage the Parameter Sets...............................................................................................63

7.2.1 TaskSpec to Launch the Parameter Set Page........................................................................63

7.2.2 PageDefinitionSpec for the Parameter Set Page....................................................................64

7.2.3 TableSpec for the Custom Parameter Set Table.....................................................................64

7.2.4 AddDataFormTemplateSpec to Add a Parameter Set............................................................64

7.2.5 EditDataFormTemplateSpec to Edit a Parameter Set.............................................................64

7.2.6 EditDataFormTemplateSpec for the Pre-Process Edit Data Form..........................................64

7.2.7 RecordOperationSpec to Delete a Parameter Set..................................................................64

7.2.8 DataListSpec to List the Parameter Sets.................................................................................64


7.3 Specs to Manage the Business Process Status................................................................................65

7.3.1 TaskSpec to Launch the Status Page.....................................................................................65

7.3.2 PageDefinitionSpec for the Status Page.................................................................................65

7.3.3 ViewDataFormTemplateSpec for the Summary Section on the Status Page.........................65

7.3.4 ViewDataFormTemplateSpec for the Expression View Data Form on the Status Page.........65

7.3.5 DataListSpec to Return a Status List.......................................................................................65

8 Tables..........................................................................................................................................................678.1 Overview............................................................................................................................................67

8.2 BusinessProcessCatalog Table.........................................................................................................67

8.3 BusinessProcessStatus Table...........................................................................................................68

8.4 Business Process Parameter Set Table (USR_INVENTORYPROCESS)........................................69

8.4.1 Sample Business Process Parameter Table...........................................................................70

8.4.2 Business Process Parameter Status Table (USR_INVENTORYPROCESSSTATUS)...........73

8.4.3 Business Process Parameter Export Format Table (USR_INVENTORYPROCESSEXPORTFORMAT)...............................................................................74

8.5 BusinessProcessView Table.............................................................................................................75

8.6 BusinessProcessOutput Table..........................................................................................................78

8.7 BusinessProcessInstance Table Secures Parameter Sets...............................................................79

9 Queue Processes.......................................................................................................................................8010 Exercise 1 – Adding the Custom Parameter Set Table for the Business Process..............................8111 Exercise 2 - Adding the Selections for the Food Bank Inventory Business Processes.....................8612 Exercise 3 – Building the Processing Logic for the Food Bank Inventory Business Process..........9713 Exercise 4 – Adding Parameters Sets....................................................................................................11014 Exercise 5 - Building the Status Page....................................................................................................11515 Parameter Set Page.................................................................................................................................139

15.1 Business Process Parameter Set Data List.....................................................................................139

15.2 Exercise 6 – Review and Load the Business Process Parameter Set Data List.............................140

15.3 Exercise 7 - Building the Business Process Parameter Set Page...................................................141

16 Business Process Tasks.........................................................................................................................15716.1 Using a Task’s StartBusinessProcess Action Type.........................................................................157

16.2 Using a Task’s RunBusinessProcess Action Type..........................................................................159


1 Course Prerequisites

The following Infinity SDK course prerequisites or related experience are required before registering for this course.

1. An understanding of XML, XSL schemas, and XML namespaces

2. Understanding of the Infinity Platform, SDK, and Catalog System

3. Creating and managing solutions and projects using Microsoft Visual Studio

4. Building class libraries (assemblies) using Microsoft Visual Studio and Visual Basic.NET

5. Authoring classes and inheritance using Visual Basic.NET

6. Experience with Microsoft SQL Server Management Studio

7. An understanding of T-SQL including authoring SQL SELECT statements, views, user defined functions, and stored procedures.

8. Knowledge of SQL Server Agent Jobs

9. Ability to navigate and understand Infinity feature metadata within the shell

10. Ability to configure new pages, tabs, sections, and actions

11. Experience authoring the following types of Infinity Catalog Items (specs):

a. TableSpec

b. CodeTableSpec

c. AddDataFormTemplateSpec

d. EditDataFormTemplateSpec

e. ViewDataFormTemplateSpec

f. DataListSpec

g. Expression Data Form

h. QueryViewSpec

i. RecordOperationSpec

j. SQLFunctionSpec

k. SQLStoredProcedureSpec

l. PageDefinitionSpec

m. TaskSpec

n. Configuring Ad-Hoc Queries and Selections


2 Learning Objectives

1. Recognize the role of business processes within an Infinity based application

2. Understand the importance of parameter sets to a business process

3. Learn common patterns and best practices for formatting and restricting the output from a business process

4. Understand the difference between a business process and a business process instance

5. Learn how data processing occurs within a business process

6. List the Infinity SDK software developer responsibilities for building and supporting the functionality required for a business process

7. Describe the database tables used by Blackbaud Enterprise CRM to manage business processes

8. Describe how a QueryViewSpec can be used to define the output format for a business process

9. Describe how a selection can be used to limit the rows processed by a business process

10. Gain experience building a working inventory business process for the food bank sub application within Blackbaud Enterprise CRM including hands on experience in the building of:

a. Parameter set page to view, manage and secure parameter sets

b. Status page to view status of current and historical business processes-

c. Business process logic to generate the output


3 Business Process Overview

Freedom is the best word to discuss business processes. With business process you have freedom to process data to produce any output type. You are free to design any number of input parameters to get the job done. You are free to query, process, and transform the data however you wish. You are free to create the final output as there is no restriction on the format of the final processed data. From an architectural perspective, business processes are free to process the data and leave that data in a state that can be used by any number of future processes.

3.1 Parameter Sets and Instances

Individual parameters are organized into a parameter set. The end user can define multiple parameter sets for a given business process and then select a specific parameter set prior to launching the business process. A business process can be designed to accept zero, one or several parameters. Before a business process is run, the end user selects a parameter set and starts the business process instance. Using the parameter set for guidance, the business process instance will process the data. The parameters are used within the processing logic to produce the desired output. A business process can have a history of business process instances. Each instance is associated with a specific parameter set.

The custom business process described here includes a name to label the parameter set, a description to describe the business process instance, a reference to a query view to help format the output, and a selection to help restrict the row set being processed.

While this material highlights the best practice of using a QueryViewSpec to help format the output and a selection to help restrict the row set of a business process, keep in mind you are free to develop whatever parameters you see fit to create your custom solution. You are also free to create any type of output your requirements dictate.

3.2 Processing the Data

Data processing for a business process occurs within a .NET CLR class that exists within an assembly which is deployed on the Infinity web server. This code runs within the web services layer. Within this CLR class file, the parameter set values are retrieved and the processing on the data begins in earnest. How the processing occurs is up to you and the output data format is completely open.

A common practice is to use a QueryViewSpec to define the output format. A reference to a QueryViewSpec can be passed to the business process instance as a parameter within the parameter set. Different parameter sets can contain references to different QueryViewSpec which will in turn affect how the data is processed and


Figure 1 - An end user can configure multiple parameter sets for business process.

which columns will appear within the final output. See Using a QueryViewSpec for Output Formatting for details.

Often business processes will require a way to retrict the row set being processed. A best practice is to use a “selection” to accomplish this. A selection is a set of record id’s for a particular record type. A selection can be a static or unchanging list of record ids or it can be a dynamic list of record ids which are derived when called upon by a business process. Selections can be created using Blackbaud’s query tool by first creating either an ad-hoc query or smart query and then saving the query results as a selection. See Using a Selection to Restrict the Row Set for details.

The output for a business process could be a new flat file, xml file or database table which in turn could be used as the input for a subsequent business process for further processing. As another example, the output for a business process could be the creation and population of a new batch . Or, you could create a process that generates a flat file to be used by a separate, 3rd party system. Or, you could create and populate a database table that provides data for a report. The figure below depicts a business process instance running with a specific parameter set to produce a database table. Remember, a custom business process can use any number parameters as input to produce a table, xml file, flat file, batch, series of web service calls to another system, etc. You have freedom to create the parameters, processing, and output to solve your organization’s challenges.

Figure 2 - Business Process “A” utilizes parameter set “C” and produces an output table.

3.3 SDK Developer Responsibilities

When building a business process, an Infinity SDK developer typically will need to account for the following functionality:

1. Build a parameter set page to view, manage, and secure the parameter sets

2. Build the business process logic to generate the output

3. Build a business process instance status page to view the status of current and historical processes

3.3.1 Parameter Set PageOne of the tasks a business process administrator/end user will need to accomplish is managing parameter sets for a given business process. Once a parameter set has been established, the user should be able to start a new instance of the business process and view the history of previous business process instances. In addition, the user will need to permission and secure a parameter set for a particular site and/or role.


TripOt, 09/21/11,

Hyperlinks such as these should point to the new location.

http://www.bbdevnetwork.com/content/batch-overview

Figure 3 - A typical parameter set page

An Infinity SDK developer will need to build a parameter set page and the individual features referenced by the page. Below is a listing of the Infinity features that are typically used within a parameter set page:

1. Custom DataListSpec to view the list of parameter sets that the user has permission to view

2. Custom EditDataFormTemplateSpec to edit a parameter set

3. Custom AddDataFormTemplateSpec to add a parameter set

4. Custom RecordOperationSpec to delete a parameter set

5. Custom Page definition spec that references the following:

a. A tab with a section that references the data list to display the parameter sets

b. Add action to open the data form to add a new parameter set

c. Edit action to open the data form to edit the selected parameter set

d. Delete action to call upon the record operation to delete the selected parameter set

e. Start Process action to start the business process using the selected parameter set

f. Go to Process action to view the business process instance status page.

g. Security action to permission the selected parameter set which occurs via an out of the box Add Data Form provided by Blackbaud Product Development.

For more information on building the status page see Building a Page to Manage Business Process Parameter Sets.

3.3.2 Business Process LogicA BusinessProcessSpec is used to reference the .NET class. The ProcessorComponent tag references the assembly name and a fully qualified class name that contains the processing logic. The fully qualified class name consists of the class name (InventoryProcessBusinessProcess) appended to the assembly name (Blackbaud.CustomFx.FoodBank.Catalog).


Figure 4 - Sample BusinessProcessSpec

Your business process processing will occur within a .NET class that inherits from Blackbaud’s AppCatalog.AppBusinessProcess class. Overriding the Validate() sub within this class enables you to retrieve the parameter set values for the instance. Overriding the StartFunctionBusinessProcess() function enables you to write code that processes the data and produce the output. StartFunctionBusinessProcess() will send back an object of type Blackbaud.AppFx.Server.AppCatalog.AppBusinessProcessResult which provides the Infinity platform with the number of record successfully process and the number of exceptions, if any.

Figure 5 - Sample business process code


This class will be located within your catalog assembly along with your catalog items/specs. The assembly will run within the web service layer. For custom catalog assemblies built by Blackbaud Professional Services, customers, and other 3rd party development staff, the assemblies should be deployed to the vroot\bin\custom sub folder for your Infinity web application on the web server.

3.3.1 Status PageA business process will spawn many business process instances. When an instance is started, the designated parameter set is associated with the instance. The Infinity SDK developer will need to build a business process instance status page to view the status of the current business process instance along with historical instances. A business process instance status page is primarily used to view the recent and historical statuses for a business process and its associated parameter set. After a business process is started manually, the task or action typically will redirect the user to the status page. Users typically navigate to the status page from the parameter set page or other pages or tasks, if needed.

How you design your status page is up to you. Keep in mind that a typical business process instance status page should provide the ability to:

1. View business process instance parameter set information via a custom view data form

2. View recent status of the business process instance by leveraging an out of the box view data form

3. Start the most recent business process instance using the parameter set provided for the instance via a Start Process action button

4. Edit the parameter set for the business process via an action that calls upon an edit data form

5. Generate a windows script file to launch the business process with the current parameter set via an action that calls upon out of the box CLR code

6. Create a job schedule to launch the business process with the current parameter set by leveraging an out of the box add data form

7. Create an Infinity Task that launches the business process with the current parameter set via an action that calls upon an out of the box add data form

8. Delete the current parameter set for the business process


Figure 6 - Status page, recent status tab, and actions

9. View historical business process instances via a custom data list

10. Delete status history and any related output tables, if they exist, by leveraging an out of the box record operation.

Figure 7 – History Tab: status history requires a custom data list and an action to call a record operation that deletes the selected history

11. View and manage job schedules by leveraging out of the box data list, add data form, edit data form, and delete record operation


Figure 8 - Job Schedules Tab


4 Business Process Parameters

4.1 Overview

Individual parameters are organized into a parameter set. A business process can be designed to accept zero, one or several parameters. The end user can define multiple parameter sets for a given business process.

Before a business process is started, the end user creates one or several parameter sets, selects a parameter set, and starts the business process instance. Using the parameter set for guidance, the business process instance will process the data.

An end user will rely upon an add data form and an edit data form to save the parameter data into a custom database table. This table is built with a table spec and the name of the database table is referenced within the business process spec.

4.2 Managing Parameter Sets and Starting a Business Process without a Pre-Process Edit Data Form

Business processes can be configured to start with or without a pre-process edit data form. Using the diagram below as a guide, let’s walk through the high level steps involved with managing parameter sets and starting a business process.

Step1: End User Manages Data - An end user manages parameter values in sets via an Add Data Form and Edit Data Form which persist the parameter sets to the database within a custom parameter set table. At this point the business process has not been called upon to start. We are just managing data in a database table.

Step 2: Save the Parameter Data - The business process (BP) parameter table is a custom database table that stored parameter data for a specific business process. This table is referenced within the BusinessProcessSpec’s ParameterTableName attribute. Each row within the custom table holds a reference to a parameter set. The primary key value of the row is passed to a BP when the BP is started.

Step 3: Start the Business Process - The Start process action button is configured with an ActionType property value of StartBusinessProcess. The context passed to the BP is the primary key value of the custom BP parameter table (blue table). There is no PreProcessEditForm configured in this scenario. After the BP is started the user is directed to the status page.

Step 4: BP Processor Retrieves the Parameters and Crunches the Data - Using the primary key value of the parameter set which was selected by the end user prior to starting the business process, the BP will retrieve the parameters from the custom parameter table and process the data.

Step 5: Create Output Table - To fulfill the business requirements the business process can produce a new output table filled with the processed data. See related BUSINESSPROCESSOUTPUT and BUSINESSPROCESSSTATUS tables.


Figure 9 - Parameter Sets

Figure 10 - Managing Parameter Sets and Starting a Business Process without a Pre-Process Edit Data Form


4.2.1 Configuring the Start Process Action Button An end user will typically click an action button within a section on a page start a business process. The action should be configured to use the StartBusinessProcess action type passing the appropriate context value to the business process. The context value should be the primary key value of a row within the custom parameter set table.

With the user interface in design mode, right click the “Start process” button and select Properties from the context menu. This will open a property sheet for the action button.

Here is a screen shot of a “Start process” action button that resides within a section which contains a data list of a parameter sets.

The BusinessProcess property should be set the business process as defined by the BusinessProcessSpec.

The StatusPage property should be set to a status page which will need to be constructed for the BP.

The ContextType property should be the primary key value of a row within the custom parameter set table. Here we are setting it to the ID column on the data list which is the primary key value for the parameter set table.

Once a parameter set is selected and the action button has its context value, the “Start process” button can be selected to launch the BP and navigate the end user to the status page. See below.


Figure 11 - Configuring the "Start Process" action button

Figure 12 - "Start process" action button property sheet

Figure 13 - Business Process Status Page

4.3 Managing Parameter Sets and Starting a Business Process with a Pre-Process Edit Data Form

You may run across a scenario where an end user wants to change parameter values for a parameter set each time the business process is launched. Through configuration a SDK developer or anyone familiar with the capabilities of page designer can provide additional parameters for the “Start process” action button to include a pre-process edit form.

Using the diagram below as a guide, the red stars help to highlight the differences between starting a business process with and without a pre-process edit data form.

Step 2: Saving the Parameter Data - The save implementation of the add data form will need to provide default values for any additional parameters managed by the pre-process edit data form. One must save all the parameter values for the parameter set to support the queuing of business processes.

Step 4: Starting the BP - A PreProcessEditForm is configured in this scenario. The edit data form appears prior to the BP being started. This allows the end user to modify additional parameter values that typically get each time the business process is launched. Please note that an end user will not have the opportunity to select parameters via a PreProcessEditForm when a BP is launched within a Queue.

Step 5: Saving the Data from the Pre-Process Data Form - A pre-process data form is a stand alone data form that saves data to a parameter table. After the save is complete, the system launches the business process.

Step 6: BP Processor Retrieves the Parameters and Crunches the Data - Using the primary key value of the parameter set which was selected by the end user prior to starting the business process, the BP will


retrieve the parameters from the custom parameter table and process the data. Note: any additional parameters managed by the pre-process edit data form should be retrieved by the BP logic.


Figure 14 - Managing Parameter Sets and Starting a Business Process with a Pre-Process Edit Data FormNote: Pre-process edit data forms cannot be invoked at run time when a business process is launched as a step within a Queue. Queues are used to set up a series of business processes to run automatically and unattended. Each step in a queue refers to a business process and a specific

parameter set. Since a queue can launch a series of business processes automatically there is no opportunity for human interaction and therefore no opportunity to modify the parameters via the pre-process edit data form. For more information on Queue see the section titled Queue Processes.

4.3.1 Configuring the Start Process Action Button with a Pre-Process Edit Data FormThe pre-process edit form is meant to as a way for end users to modify parameter values that typically change with each business process instance run. The PreProcessEditForm should be set to an edit data form which has been built to save parameter values to the parameter set table or other related parameter table(s).

Here is an example of a business process named “Print Membership Cards Process” that comes with Blackbaud CRM. A new parameter set is added prior to starting the business process.

After the parameter set is saved to the database a “Start process” button is selected, the action has been configured to display the pre-process edit form prior to starting the process. The pre-process edit form allows the user to modify parameter values that change with each business process run. See below.


Figure 15 - Adding a Parameter Set for the Print Membership Card Process

Figure 16 - Configuring the "Start process" action button’s PreProcessEditForm property

Below a pre-process edit form allows an end user to name and create a constituent selection from the results of the business process. After the pre-process edit form saves the settings to the database, the action will launch the BP and navigate the end user to the status page.


Figure 17 - An example of a pre-process edit form

4.4 Using a QueryViewSpec as a Parameter for Output Formatting

A QueryViewSpec is traditionally used to provide tables and fields to select within Blackbaud Enterprise CRM’s ad-hoc query tool. As an example, within the food bank source code, the FoodBank.Query.xml file contains a QueryViewSpec which leverages the custom USR_FOODBANK and USR_FOODBANKTYPECODE tables. The FoodBank.Query.xml file can be found within the food bank source code’s catalog project. The USR_FOODBANK table extends the constituent table in a one to one relationship providing additional columns of data for a food bank organization. When the QueryViewSpec is loaded into the Infinity catalog (database), we can see the result by creating a new ad-hoc query that is based on the Constituent source view. Below we can see the additional food bank columns as defined by the custom QueryViewSpec:


Figure 18 - The traditional use of a QueryViewSpec is to support ad-hoc query.

But, how can a software developer use a QueryViewSpec in conjunction with a business process? While not required, a best practice is to use a QueryViewSpec to define the output format of a business process. Typically, before starting an instance, an end user may select a reference to a specific QueryViewSpec as one of the input parameters into a process. Different parameter sets can contain references to different QueryViewSpecs which will in turn affect how the data is processed and which columns will appear within the final output. In short, a QueryViewSpec can be used to drive the columns of data created by a business process.

The best practice to define the output columns is to utilize a reference to an “Output Format” QueryViewSpec as a parameter value into the business process instance. The QueryViewSpec is used to define a database view.


Once a parameter set is selected and a business process instance is started, the Infinity platform will call upon .NET code to process a set of records. Within the business process vb code, a base set of record may be combined with the records and columns defined by the QueryViewSpec. If necessary, the T-SQL logic within the QueryViewSpec influences the processing of data within the business process. The output fields defined within the QueryFiewSpec determine the columns of data created as the output from the business process.

Below is an example of a QueryViewSpec that is used to drive the output format for the food bank inventory business process that we will be building. Specific tags within the QueryViewSpec help relate the query to a specific business process and the processing that occurs therein:


The figure below displays the same QueryViewSpec shown above along with the BusinessProcessSpec spec. The highlighted areas illustrate the relationships between the two specs.


4.4.1 Understanding the QueryViewSpec’s JoinFieldLook again at the sample QueryViewSpec used to provide the output formatting for a business process. We can see the JoinField element within the BusinessProcessOutput element. Within the business process code a base set of records may be combined with the records defined by the QueryViewSpec via this join field.

The business process class the developer creates must inherit from Blackbaud.AppFx.Server.AppCatalog.AppBusnessProcess. The JoinField value defines how these two record sets can be joined together across a common field. See below for an example of how the vb class uses the JoinField property. The JoinField value within the spec is directly related to the value within the AppBusinessProcess.OutputView’s JoinField property which is used to join the records defined within the QueryViewSpec’s view to the processing that occurs within the business process code. See below.


4.5 Using a Selection as a Parameter to Restrict the Row Set

Another common situation a developer will run into is the necessity to restrict the row set to a specified set of records. A selection is a set of record id’s for a particular record type. A selection can be a static or unchanging list of record ids or it can be a dynamic list of record ids which are derived when called upon by a business process. Selections can be created using Blackbaud’s query tool by first creating either an ad-hoc query or smart query and then saving the query results as a selection. Selections can also be created by other business processes. Check out the following materials on query and selections within the Query and Export Guide if you are unfamiliar with either topic.

Different parameter sets can contain references to different selections which will in turn affect the restriction of rows within the output of the business process. In short, a selection can be used to rows of data created by a business process.

Once a parameter set is selected and a business process instance is started, the Infinity platform will call upon .NET code to process a set of records. Within the business process vb code, a base set of record may be restricted by the set of ids defined by the “Selection” parameter. Below is an example of the “selection” parameter is used within the join clause to filter the rows. A standard user defined function named UFN_IDSETREADER_GETRESULTS is used to read the GUIDs from an IDSET (selection) in the database using the id of the selection (IDSETID).

Figure 19 - Restricting the rows using a join clause and the selection parameter


http://www.blackbaud.com/files/support/guides/enterprise/queryex.pdf


5 Building the Business Process Processing Logic

We will now walk through a business process code example. The goal is to highlight typical activities and patterns an Infinity developer would encounter when building a business process. The business process code exists as a .NET class that lives within an assembly which is deployed on the Infinity web server. Typically this is the “catalog” assembly where your other xml specs reside. Your .NET class must inherit from the base class Blackbaud.AppFx.Server.AppCatalog.AppBusinessProcess that is housed within the Blackbaud.AppFx.Server.dll assembly. Inheritance is the ability to use all of the functionality of an existing class, and extend those capabilities without re-writing the original class.10For brevity, we will refer to the inherited class as AppBusinessProcess.

5.1 When a business process instance starts…

When a business process instance begins the inherited (Blackbaud) code within the AppBusinessProcess base class will do the following:

5.1.1 Application Lockso The system uses the sp_getapplock() system stored procedure to create an exclusive application lock using the

BUSINESSPROCESSSTATUSID as the lock’s resource name (@Resource). Using sp_getapplock guarantees serial access to application database code and database objects by issuing an application lock . This is a way to synchronize code and it effectively blocks other users from entering the section of code until the lock is released. Any process calling sp_getapplock with the same @Resource variable will be blocked until the app lock is released. The resource/lock name is a unique string specifying a name that identifies the lock resource. The application lock is made on the database connection. Since the BUSINESSPROCESSSTATUSID is a global unique identifier the resource/lock name will be unique. The lock mode is exclusive. The lock owner is set to ‘Session’ meaning the code will ultimately have to call sp_releaseapplock() to release the lock.

5.1.2 Infinity ASP.Net WebHealth Eventso Before creating the app lock, the code will raise an ASP.NET WebHealth event named

InfoBusinessProcessDetailMessage stating "Business process: CreateAppLock entered".

o Once the lock is acquired an ASP.NET WebHealth Event is raised named InfoBusinessProcessDetailAppLockAcquired stating "Business process status app lock acquired".

o The code will then attempt to get an application lock for the specific parameter set using "BPappLock:" & ParameterSetID as the lock name. Before the lock is attempted a "Business process: CreateParameterSetAppLock entered", WebHealth InfoBusinessProcessDetailMessage is raised. Web events will be raised if a lock could not be achieved. If the business process is already running a message of "Business process parameter set app lock not acquired, return code=X" along with error information including “The buisness process ‘<Your BP Spec Name>’ is already running.

Database Application Lock Status Codes

0 'Lock was successfully granted synchronously.

1 Lock was granted successfully after waiting for other incompatible locks to be released.

-1 Lock request timed out


http://msdn.microsoft.com/en-us/library/ms178602.aspx



-2 Lock request was cancelled

-3 Lock request was chosen as a deadlock victim.

-999 Parameter validation or other call error.

The Infinity Platform and the applications that are built on it have been instrumented using the standard ASP.Net WebHealth system. This system allows the application developer (Blackbaud) to efficiently surface diagnostic, security, auditing, and logging information about the inner

workings of the application. An administrator then uses a built in configuration system to tap into this stream of information and route the particular events of interest to various consumers of the information. See Monitor Infinity Web Server Events with PowerShell and WMI for more information.

5.1.3 Status Updatedo A row is inserted into the BUSINESSPROCESSSTATUS table and a row is inserted into the custom Business

Process Parameter Status Table. This signifies that the BP instance started with the selected parameter set.

5.1.4 Simultaneous Run Checko A check for simultaneous runs of the business process instance is performed. The BusinessProcessSpec’s

AllowSimultaneousExecution attribute determines whether instances business process should be allowed to be started if another business process of the same type is already running. If the attribute is set to False then the code will check the BUSINESSPROCESSSTATUS table using the BUSINESSPROCESSSTATUSID where the StatusCode is 1 (Running) and an application lock is currently in effect for the resource.

5.1.5 Validate() and Retrieving the Parameterso Validate() subroutine is called which is marked as Overridable. The Overridable keyword specifies that a

property or method can be overridden in a sub class. Meaning your sub class, the class that inherits from the AppBusinessProcess base class, can override or replace its code. By Overridding Validate() you can ensure that your business process is prepared to do its work. A typical task for Validate is to retrieve the parameters from the parameter set. See Retrieve and Validate the Parameters. Once validation has passed the base class will an raise an ASP.NET WebHealth Event named InfoBusinessProcessDetailUserCodeStarted.

5.1.6 StartBusinessProcess() Performs the Bulk of Data Processingo After Validate() has occurred, the base class will start the business processing by making a call to the

StartBusinessProcess() function which is marked as MustOverride. The MustOverride keyword specifies that a property or procedure in a base class must be overridden in a derived class before it can be used. This means you must provide the code for the StartBusinessProcess() function within your sub class. See Start the Business Process. It is here where the bulk of the data processing is conducted.

o After processing has completed, the base class will raise an ASP.NET WebHealth Event named InfoBusinessProcessDetailUserCodeCompleted. Followed by marking the business process instance as completed by updating the BUSINESSPROCESSSTATUS table with a STATUSCODE of zero (), updating the NUMBERPROCESSSED, NUMBEROFEXCEPTIONS, and ENDEDON values.


http://msdn.microsoft.com/en-us/library/hyb29zk8(v=VS.71).aspx

http://msdn.microsoft.com/en-us/library/zcfd2sa9(v=vs.71).aspx

http://www.bbdevnetwork.com/content/monitor-infinity-web-server-events-powershell-and-wmi

http://www.bbdevnetwork.com/content/monitor-infinity-web-server-events-powershell-and-wmi

5.2 Typical Duties for your Sub Class

Your business process sub class will need to accomplish the following duties:

o Retrieve and validate the parameters

o Start the business process and process the data

o Create some type of output with columns

o Optionally create a selection of the results

o Return a Result

5.2.1 Retrieve and Validate the Parameters: Validate()The base class from which your sub class inherits will call your Validate() sub routine to begin processing. Overriding the Validate() sub routine provides the developer with the opportunity to retrieve parameters and perform any other validation duties for the business process. If there is an issue with parameter retrieval or validation, then throw an exception.

In the sample below, we are using an InventoryParameters class to retrieve the name of the “output format” query view (OUTPUTVIEWID) and the “Selection” (IDSETID) parameters.


Figure 20 - Overriding the Validate() Sub

5.2.2 Start the Business Process: StartBusinessProcess()Prior to starting the business process, we should have the parameters retrieved and validated. See Retrieve and Validate the Parameters: Validate() for details.

Generally speaking the most typical use of a business process is to create some type of output that contains database records. The format of the output depends on your requirements. A common practice, although not required, is to product a database table containing your processing results. No matter what format you choose for your business process output, there is a good chance you will need to define the columns for the output.

The best practice to define the output columns is to utilize a reference to an “Output Format” QueryViewSpec as a parameter value into the business process instance. The QueryViewSpec is used to define a database view. See Using a QueryViewSpec as a Parameter for Output Formatting for more information.


5.2.2.1 Grab the Output Format View Name and Join FieldSo, our first major step within the StartBusinessProcess function is to take the id of “Output Format” QueryViewSpec and retrieve the name of the view and its join field. A helper function within the base class named OutputView is used to retrieve both the name of the view and the join field.

See AppBusinessProcess base class' OutputView property for more details on retrieving the query view name and join field.

5.2.2.2 Create the Output Table Using the “Output Format” View NameOften the result of a business process is the creation of a database table which contains the resulting data of your process. CreateOutputTableFromView() creates an output table in the business processor database based on a view in the application database. The function will return the name of the created database table and a ByRef array of TableColumns.

See Creating an Output Table via the CreateOutputTableFromView() function for more details.

5.2.2.3 Building the SQL to Populate the Output Table: Building a Field ListUsing the table name and the ByRef array of TableColumns returned from the base class’ CreateOutputTableFromView() function, begin the process of populating the output table by building an INSERT T-SQL statement. Pass the table columns into the base class’ CreateFieldsList() function which will return a comma delimited list of columns.

See AppBusinessProcess base class’ CreateFieldsList Function and Creating an Output Table via the CreateOutputTableFromView() function for details.


TripOt, 09/28/11,

Don’t break up into smaller pieces of content. Keep these section under the entire “Start the Business Process: StartBusinessProcess()

TripOt, 09/28/11,


TripOt, 09/28/11,


5.2.2.4 Building the SQL to Populate the Output Table: Joining the “Output Format” and “Selection” Row Sets

After the field list has been built, the next step is to build the JOIN clauses that pulls in the records from “Output Format” view parameter utilizing the join field and also restricts the row set using the “Selection” parameter. The table valued UFN_IDSETREADER_GETRESULTS user defined function is leveraged to build a table of guids represented by the “Selection” parameter (IDSETID).

5.2.2.5 Executing the SQL Command to Populate the Output Table and Return a ResultAfter the SQL has been dynamically built, we open a SQL connection to the database where we created the output table. We execute the command, which is an INSERT SQL Statement. This populates the output table. Finally, the StartBusinessProcess() funciton should return an object of type Blackbaud.AppFx.Server.AppCatalog.AppBusinessProcessResult which includes the number of records processed and the number of exceptions, if any.


TripOt, 09/28/11,


TripOt, 09/28/11,


5.3 AppBusinessProcess base class’ OutputView Property

OutputView is a member of the inherited Blackbaud.AppFx.Server.AppCatalog.AppBusinessProcess base class. The OutputView property is used to retrieve both the name of the view and the join field used to join the row set generated by the view to the base SQL that is dynamically created within the business processor code. The AppBusinessProcess base class’ OutputView property accepts the ID of a QueryViewSpec which represents the selected “Output Format” parameter and returns an object of type OutputViewInformation. A stored procedure named USP_BUSINESSPROCESSVIEW_GETVIEWINFORMATION is used to retrieve the view db object name, join field, and query view spec information form the BUSINESSPROCESSVIEW and QUERYVIEWCATALOG tables for the given ID.

See the appropriate business process subject area ERD for details on the tables surrounding business processes.

Use the T-SQL View Defined by the QueryViewSpec to output format/columns


TripOt, 11/01/11,

Need link to ERDs within new html web help output

Figure 21 - Leveraging the Base Class' OutputView property to retrieve the name of the "Output Format" view name and join field

5.4 Creating an Output Table via the CreateOutputTableFromView() function

Often the result of a business process is the creation of a database table which contains the resulting data of your process. CreateOutputTableFromView() creates an output table in the business processor database based on a view in the application database. A view is a virtual table that consists of columns from one or more tables. The CreateOutputTableFromView() function will utilize the columns defined within the view to create the structure/columns of the table. The table will be created with no data. Once created, you can populate the table with data within your business processor code.


The function is overloaded meaning there is more than one definition of the function. The table name will have a suffix containing the primary key of the current business process status. The length of the table name should not exceed 128 characters.

The CreateOutputTableFromView() function accepts a ByRef array of TableColumn classes as a parameter. Since this parameter is marked as ByRef, your business processor code can pass the “returned” array of columns into the base class’ CreateFieldsList() function which builds a comma delimited list of fields. The comma delimited list of fields can be used within a T-SQL data manipulation statement, such as an INSERT statement, to populate the table with data.

Below is a table with a description of the parameters for the version of the CreateOutputTableFromView function that we are using in the code sample below.Blackbaud.AppFx.Server.AppCatalog.AppBusinessProcess.CreateOutputTableFromView() Function’s ParametersParameter Name

Description ByVal/ByRef

viewName The name of the source view to be used to populate the table fields ByValtableNamePrefix

The prefix of the table name to be created. Table name prefix will be concatenated with the id of the current business process run. The length of the table name should not exceed 128 characters

ByVal

tableKey Used to uniquely identify the output table when a business process creates multiple output tables in a single process run.

ByVal

tableColumns A ByRef array of TableColumn classes that make up the output table. In the example below this collection is passed to the CreateFieldsList function which returns a string of column named used within the dynamically generated SQL.

ByRef

Below is a code sample from the subclass which inherits from AppBusinessProcess. Note where we override the StartBusinessProcess() funciton. In the blue highlight, we pass the name of the view. The view name is derived from the “Output format” parameter. The function returns the name of an output table named USR_INVENTORYPROCESS_<guid> table name. The value "USR_INVENTORYPROCESS" is used for the tableNamePrefix parameter. Within the base class’ CreateOutputTableFromView function, the BusinessProcessStatusID value will be concatenated to the end of the table prefix.

Example: USR_INVENTORYPROCESS_03aab75b_798a_404b_962b_63a4f0ddcc10


Figure 22 - Creating the output table using the columns defined within the "Output Format" query view.

5.5 Optionally Creating a Selection of Processed Records via CreateIDSet() Function

The CreateIDSet() creates a selection which contains the ids of the records processed for a particular record type. CreateIDSet() function is used to support the "Create selection of processed records" option found on most business process definitions. A selection can be used as an input into a business process or created by a business process.

Selections can also be created using Blackbaud’s query tool by first creating either an ad-hoc query or smart query and then saving the query results as a selection. A selection may be created by other business processes as some processes employ an option to "Create selection of processed records”. Within the food bank inventory business process, the IDSETREGISTERID field points to a system table named IDSETREGISTER. Each row in the IDSETREGISTER table corresponds to a view or table-valued function that returns a list of Primary Key ID values of a particular record type (database table), such as Constituent or Revenue.


Note: Selections can be created via Blackbaud’s Query tool. A selection can be used as an input parameter into a business process instance. A selection is a list of record ids used within the business process .net code to restrict the number of rows processed via a SQL JOIN or WHERE clause.

Check out the following materials on query and selections within the Query and Export Guide if you are unfamiliar with either topic.

5.6 Creating an Output Table via the CreateOutputTable() function

Often the result of a business process is the creation of a database table which contains the resulting data of your process. The CreateOutputTable() function creates a table in the business process database based on a list of TableColumn classes which are passed into the function as a parameter. This function is similar to the CreateOutputTableFromView() function in that it creates a table, accepts a name prefix and key parameters to build the table name. Table name prefix will be concatenated with the id of the current business process run. The table name can not exceed 128 characters. The USP_BUSINESSPROCESS_CREATEOUTPUTTABLE stored procedure is used to create the table. The table will be created with no data. The function returns the name of the database table created. Using the returned database table name, you can populate the table with data within your business processor code.

A primary difference between the CreateOutputTable() function and the CreateOutputTableFromView() function is the CreateOutputTable() function accepts a ByVal Generic.IList(Of TableColumn) while the CreateOutputTableFromView() function accepts a ByRef array of TableColumn classes. Blackbaud.AppFx.Server.AppCatalog.AppBusinessProcess.CreateOutputTable() Function’s ParametersParameter Name Description ByVal/

ByRef tableNamePrefix The prefix of the table name to be created. Table name

prefix will be concatenated with the id of the current business process run.

ByVal

tableKey Used to uniquely identify the output table when a business process creates multiple output tables in a single process run.

ByVal

columns List of TableColumn classes to define the columns to be added to the output table.

ByVal

overrideSuffixWithNewGuid

If true, name the table with a unique GUID suffix; if false, use the primary key of the current business process status as the GUID suffix. If overrideSuffixWithNewGuid is true, the table name will have a unique GUID suffix; if it is false, its suffix will be the primary key of the current business process status.

ByVal

5.7 AppBusinessProcess base class’ CreateFieldsList Function

Your business processor code can pass an array of columns into the base class’ CreateFieldsList() function which builds a comma delimited list of fields. Within your business processor code, the comma delimited list of fields can be used within a T-SQL data manipulation statement, such as an INSERT statement, to populate the table with data.

See Creating an Output Table via the CreateOutputTableFromView() function for an example.


http://msdn.microsoft.com/en-us/library/ddck1z30(v=vs.71).aspx


6 Business Process Instance Status Page

A business process (BP) is started by selecting a parameter set followed by starting the BP via one of the following options:

Manually from the business process parameter set page

Job schedule

Queue

Windows script file

Infinity Task (Manually)

A business process instance status page or also known as the ‘status page’ is primarily used to view the recent and historical statuses for a business process and its associated parameter set. After a business process is started manually, the task or action typically will redirect the user to the status page. Users typically navigate to the status page from the parameter set page or from other pages or tasks, if needed.

How you design your status page is up to you. Keep in mind that a typical business process instance status page should provide the ability to:

1. View business process instance parameter set information via a custom view data form

2. View the recent status of the business process instance by leveraging an out of the box view data form

3. Re-Start the most recent business process instance using the parameter set provided for the instance via a Start Process action button

4. Edit the parameter set for the business process via an action that calls upon an edit data form

5. Generate a windows script file that launches the business process with the current parameter set. The script generation is kicked off via an action that calls upon out of the box CLR code.

6. Create a job schedule to launch the business process with the current parameter set by leveraging an out of the box add data form

7. Create an Infinity Task that launches the business process with the current parameter set via an action that calls upon an out of the box add data form

8. Delete the current parameter set for the business process


Figure 23 - Status page, recent status tab, and actions

9. View historical business process instances via a custom data list. See below.

10. Delete status history and any related output tables, if they exist, by leveraging an out of the box record operation. See below.

Figure 24 - Status history requires a custom data list and an action to call a record operation that deletes the selected history

11. View and manage job schedules by leveraging out of the box data list, add data form, edit data form, and delete record operation


Figure 25 - Job Schedules tab on the status page

Below is a UML Use Case diagram that represents a typical business process instance status page. Each oval represent a Use Case. A Use Case is a UML modeling element that describes how a user of the proposed system interacts with the system to perform a discrete unit of work. It describes and signifies a single interaction over time that has meaning for the end user (person, machine or other system). In this case the end user (actor) would typically be a system administrator (not shown) or other role that has permission to the feature or ability to perform an action on the page. The use case ovals represent a feature or an action that references a feature. Green use case ovals depict custom features while blue use case ovals depict existing features created by Blackbaud.

uc Business Process Instance Status Page

«View Data Form»Inventory Business Process View Data

Form

«View Data Form»View BP Instance

Recent Status

«Data List»Inventory Process Business Process

Status List

«Data List»View BP Job Schedule List

«Delete Record Operation»

Delete Status History and Related Output

Table

«Edit Data Form»Edit Job Schedule


Delete Job Schedule

«Business Process»

Start Process

«Edit Data Form»Inventory Process Business Process

Edit Form

«CLR Action»Generate WSF

Recent Status Tab

Summary Section

History Tab Job Schedules Tab

«Add Data Form»Create Job Schedule

«Add Data Form»Create Task to

Launch BP


Delete Process

Actions ("Tasks" Action Group)

Blackbaud Product Development Feature

Custom Feature

Legend

«Add Data Form»Add Job Schedule

Expression Data Forms

«Expression Data Form»

Inventory Process Business Process Status View Form

Data form for editing inventory process business process parameters. Edits the parameter set for the business process.

Expression Data Form used by the status page. Provides data for use on the inventory process business process status page.

Summary View Data Form used by the status page to view BP Parameter Set Information.

Returns a status l ist for the inventory process business process. Referenced within the page’s History tab

Deletes the specified inventory process business process.

This action starts our custom business process that we build using a BusinessProcessSpec and CLR code.

Figure 26- UML use case diagram depicting the status page


6.1 Expression Data Form Drives Expressions on the Status Page

A page may contain a reference to an Expression Data Form which is a type of ViewDataForm. An Expression Data Form is never actually displayed in the UI. Instead it acts behind the scenes to gather important information about the displayed record and make it available to the page. This allows the page author to write regular expressions to dynamically alter what is displayed on the page.

Within the PageDefinitionSpec xml element is an attribute named ExpressionDataFormID. The ExpressionDataFormID attribute specifies a View Data Form instance which can be used as a source for expressions within a page. The expression model similar to the one found in Microsoft Reporting Services or in various dialects of Visual Basic.

Looking at the metadata for the completed food bank inventory business process status page below, we can see it leverages an expression data form named ‘Inventory Process Business Process Status View Form’.

Figure 27 - The status pages utilizes and expression view data formWe can click on the link for the expression data form (Inventory Process Business Process Status View Form) to view its metadata. See below.

Figure 28 - Expression data form metadata page displays the form fields retrieved


Three fields are provided by the data form: Name, BusinessProcessCatalogID, and ParameterSetID. The Name form field represents the value of the USR_INVENTORYPROCESS.Name column which is the name of the parameter set used to by this business process instance. The Name form field is used to dynamically display the caption for page. The BusinessProcessCatalogID form field represents the ID attribute value from the BusinessProcessSpec used to create the food bank inventory business process. The ParameterSetID form field represents the primary key value of the parameter set used to by this business process instance. The ParameterSetID form field value is used within an expression to provide the context for the Create job schedule action within the Tasks action group on the left hand side of the page. See below.

Figure 29 - Expression data dorm fields drive expressions on the status page

6.2 Summary View Data Form

The summary section below the caption of the status page should orient the user to the business process instance including the any details on the parameters set. Our status page uses a custom view data form to retrieve the parameter set for a given parameter set id. For this business process, the parameter sets are stored within a custom table named USR_InventoryProcess. See the section titled Tables for more information on the entity relationship diagram supporting business processes.


Figure 30 - Summary View Data Form

6.3 Recent Status Tab

The Recent Status tab contains a single section that displays view data form provided by Blackbaud named ‘Business Process Parameter Set Recent Status View Form’. This view data form displays the most recent status information for the given business process parameter set. By passing in the parameter set id, the view data form will join the information from your custom business process parameter set table with the BusinessProcessStatus table and retrieve the relevant status information.


6.4 History Tab

The history tab typically contains one section referencing a custom datalist that returns a status list for the business process.

The data list is a custom CLR based data list meaning the code to retrieve the data for the datalist is implemented as a .NET CLR class. While the data list is a custom list, Blackbaud recommends leveraging this CLR class that comes with the product which does the dirty work of retrieving the status history.

A CLR based spec type defines the server-side catalog implementation that will be used to fetch the data for the list. Use this spec type when complex logic is required or when you need to pull data together from atypical data sources. A CLR Data list Spec requires an XML element named CLRDataList which is used to describe a data list based on CLR code. The CLR code is implemented within a .NET class that resides within a .NET CLR assembly hosted in the web service layer. The .NET class should inherit Blackbaud.AppFx.Server.AppCatalog.AppDataList. The CLRDataList XML element can contain a list of parameters that match a set of public variables within the .NET CLR class file. When the Infinity user interface calls upon the CLR data list to display a list of data, the GetListResults() function is called on the .NET CLR class file. GetListResults() is responsible for gathering the data for the data list and returning the data as type Blackbaud.AppFx.Server.AppCatalog.AppDataListResult. The CLR code will pull a status history from the BusinessProcessCatalog and BusinessProcessStatus tables for a given specific BusinessProcessCatalog.ID. Below is a sample data list spec. The CLR class assembly and class name is highlighted in yellow. The parameters passed to the class are highlighted in blue. <DataListSpec

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" ID="7ff36611-ac9d-4ae2-a3f8-900fca2f24c2" Name="Inventory Process Business Process Status List" Description="Returns a status list for the inventory process businessbusiness process." Author="Technical Training" common:SecurityUIFolder="Constituent\Food Bank\Inventory" xmlns:common="bb_appfx_commontypes" xmlns="bb_appfx_datalist">

<CLRDataList AssemblyName="Blackbaud.AppFx.Platform.Catalog" ClassName="Blackbaud.AppFx.Platform.Catalog.BusinessProcessStatusDatalist">

<common:GrantSelectList><common:GrantSelect>BUSINESSPROCESSCATALOG</common:GrantSelect><common:GrantSelect>BUSINESSPROCESSSTATUS</common:GrantSelect><common:GrantSelect>APPUSER</common:GrantSelect>

</common:GrantSelectList><common:StaticParameters>

<common:ParameterList><common:Param ID="BusinessProcessCatalogID">


<common:Value>a28d4f17-53fe-48d9-85bc-37e12884dc00</common:Value></common:Param><common:Param ID="ApplyParametersIDFilter">

<common:Value>True</common:Value></common:Param>

</common:ParameterList></common:StaticParameters>

</CLRDataList><Parameters>

<common:FormMetaData><common:FormFields>

<common:FormField FieldID="StatusCode" Caption="Status"><common:ValueList>

<common:Items><common:Item>

<common:Value>0</common:Value><common:Label>Completed</common:Label>

</common:Item><common:Item>

<common:Value>1</common:Value><common:Label>Running</common:Label>

</common:Item><common:Item>

<common:Value>2</common:Value><common:Label>Did not finish</common:Label>

</common:Item></common:Items>

</common:ValueList></common:FormField>

</common:FormFields></common:FormMetaData>

</Parameters><Output>

<OutputFields><OutputField FieldID="ID" Caption="ID" IsHidden="true" DataType="Guid" /><OutputField FieldID="Process name" Caption="Process name" IsHidden="true" DataType="String" /><OutputField FieldID="Status" Caption="Status" DataType="String" /><OutputField FieldID="Status message" Caption="Status message" DataType="String" /><OutputField FieldID="Started by" Caption="Started by" DataType="String" /><OutputField FieldID="Started on" Caption="Started on" DataType="Date" /><OutputField FieldID="Ended on" Caption="Ended on" DataType="Date" /><OutputField FieldID="Duration" Caption="Duration" DataType="String" /><OutputField FieldID="Number of records processed" Caption="Number of records processed"

DataType="String" /><OutputField FieldID="NumberOfExceptionRecords" Caption="Number of exception records" DataType="String"

/><OutputField FieldID="Total count" Caption="Total count" IsHidden="true" DataType="String" /><OutputField FieldID="Server name" Caption="Server name" DataType="String" /><OutputField FieldID="ImageKey" Caption="ImageKey" IsHidden="true" DataType="String" /><OutputField FieldID="Completed" Caption="Completed" IsHidden="true" DataType="String" /><OutputField FieldID="EnableDownload" Caption="EnableDownload" IsHidden="true" DataType="String" /><OutputField FieldID="EnableLetterMailMerge" Caption="EnableLetterMailMerge" IsHidden="true"

DataType="String" /><OutputField FieldID="EnableLabelMailMerge" Caption="EnableLabelMailMerge" IsHidden="true"

DataType="String" /></OutputFields>

</Output></DataListSpec>

Below is the code for the Blackbaud.AppFx.Platform.Catalog.BusinessProcessStatusDatalist class which does the heavy lifting of retrieving the status history data for the data list. Within the class, GetListResults() is responsible for gathering the data for the data list and returning the data as type Blackbaud.AppFx.Server.AppCatalog.AppDataListResult. Imports Blackbaud.AppFx.ServerImports System.Data.SqlClient

Public NotInheritable Class BusinessProcessStatusDatalist Inherits AppCatalog.AppDataList


Public FilterBusinessProcessInstanceID As Guid = Guid.Empty 'this is passed from the filter panel Public BusinessProcessCatalogID As String = String.Empty Public StatusCode As Nullable(Of Integer) Public ApplyParametersIDFilter As Boolean = False Public RowsToReturn As Nullable(Of Integer) Public StartedDateRangeType As Nullable(Of Integer) Public StartedDateSpecificDate As Nullable(Of Date)

Public Enum ProcessStatusImage check = 0 businessprocessspec warning x_16 End Enum

'Private Const STATUSTABLESUFFIX As String = "STATUS"

Private Enum FieldsList ID ProcessName Status StatusMessage StartedBy StartedOn EndedOn Duration NumberOfRecordsProcessed NumberOfExceptionRecords TotalCount ServerName ImageKey Completed EnableDownload EnableLetterMailMerge EnableLabelMailMerge 'EnableMultipleLetterMailMerge deprecated ParameterSetName BusinessProcessCatalogID ParameterSetID End Enum

Public Overrides Function GetListResults() As AppFx.Server.AppCatalog.AppDataListResult

If BusinessProcessCatalogID = "=ContextID" Then BusinessProcessCatalogID = ProcessContext.ContextRecordID Else If FilterBusinessProcessInstanceID <> Guid.Empty Then BusinessProcessCatalogID = FilterBusinessProcessInstanceID.ToString() End If End If

Dim builder As New Text.StringBuilder With builder .Append("select ID, ") .Append("ProcessName, ") .Append("Status, ") .Append("StatusMessage, ") .Append("StartedBy, ") .Append("StartedOn, ") .Append("EndedOn, ") .Append("Duration, ") .Append("NumberOfRecordsProcessed, ") .Append("NumberOfExceptionRecords, ") .Append("TotalCount, ") .Append("ServerName, ") .Append("ImageKey, ") .Append("Completed, ") .Append("EnableDownload, ") .Append("EnableLetterMailMerge, ") .Append("EnableLabelMailMerge, ") '.Append("EnableMultipleLetterMailMerge, ") deprecated


.Append("coalesce(ParameterSetName,'') ") .Append("from dbo.UFN_BUSINESSPROCESSSTATUS_STANDARDDATALISTVALUES_ROWSTORETURNSTARTEDDATE(@BUSINESSPROCESSCATALOGID, @PARAMETERSETID, @STATUSCODE, @ROWSTORETURN, @STARTEDDATERANGETYPE, @STARTEDDATESPECIFICDATE) ") .Append("order by StartedOn desc") End With

Dim command As New SqlCommand(builder.ToString) If ApplyParametersIDFilter Then

Dim ctxID As String = Me.ProcessContext.ContextRecordID If String.IsNullOrEmpty(ctxID) Then Throw New ServiceException("The ContextRecordID must be specified for this BusinessProcessStatusDataList", ServiceErrorCode.InvalidAPIUse) End If

command.Parameters.AddWithValue("@PARAMETERSETID", New Guid(ctxID)) Else command.Parameters.AddWithValue("@PARAMETERSETID", DBNull.Value) End If

If BusinessProcessCatalogID <> String.Empty Then command.Parameters.AddWithValue("@BUSINESSPROCESSCATALOGID", New Guid(BusinessProcessCatalogID)) Else command.Parameters.AddWithValue("@BUSINESSPROCESSCATALOGID", DBNull.Value) End If

AddNullableIntegerParameter(command, "@STATUSCODE", StatusCode) AddNullableIntegerParameter(command, "@ROWSTORETURN", RowsToReturn) AddNullableIntegerParameter(command, "@STARTEDDATERANGETYPE", StartedDateRangeType)

AddNullableDateParameter(command, "@STARTEDDATESPECIFICDATE", StartedDateSpecificDate)

Dim reader As SqlDataReader Dim resultList As New Generic.List(Of DataListResultRow)

Using conn As SqlClient.SqlConnection = Me.RequestContext.OpenAppDBConnection SpWrap.USP_BUSINESSPROCESSSTATUS_VALIDATESTATUS.ExecuteNonQuery(conn)

command.Connection = conn reader = command.ExecuteReader(CommandBehavior.CloseConnection)

Do While reader.Read Dim result As New DataListResultRow

Dim valueList As New Generic.List(Of String) valueList.Add(reader.GetGuid(FieldsList.ID).ToString) valueList.Add(reader.GetString(FieldsList.ProcessName)) valueList.Add(reader.GetString(FieldsList.Status)) valueList.Add(reader.GetString(FieldsList.StatusMessage)) valueList.Add(reader.GetString(FieldsList.StartedBy)) valueList.Add(FormatFieldForList(reader.GetDateTime(FieldsList.StartedOn)))

If reader.IsDBNull(FieldsList.EndedOn) Then valueList.Add(String.Empty) Else valueList.Add(FormatFieldForList(reader.GetDateTime(FieldsList.EndedOn))) End If

valueList.Add(reader.GetString(FieldsList.Duration)) valueList.Add(reader.GetInt32(FieldsList.NumberOfRecordsProcessed).ToString) valueList.Add(reader.GetInt32(FieldsList.NumberOfExceptionRecords).ToString) valueList.Add(reader.GetInt32(FieldsList.TotalCount).ToString) valueList.Add(reader.GetString(FieldsList.ServerName)) valueList.Add(reader.GetString(FieldsList.ImageKey)) valueList.Add(reader.GetBoolean(FieldsList.Completed).ToString) valueList.Add(reader.GetBoolean(FieldsList.EnableDownload).ToString) valueList.Add(reader.GetBoolean(FieldsList.EnableLetterMailMerge).ToString) valueList.Add(reader.GetBoolean(FieldsList.EnableLabelMailMerge).ToString) valueList.Add(Boolean.FalseString) ' deprecated -- left in so as not to break dependent specs valueList.Add(reader.GetString(FieldsList.ParameterSetName).ToString)


valueList.Add(BusinessProcessCatalogID)

If ApplyParametersIDFilter Then valueList.Add(Me.ProcessContext.ContextRecordID) End If

result.Values = valueList.ToArray

resultList.Add(result)

Loop End Using

Return New AppCatalog.AppDataListResult(resultList)

End Function

Private Sub AddNullableIntegerParameter(ByVal command As SqlClient.SqlCommand, ByVal parameterName As String, ByVal integerValue As Nullable(Of Integer)) If Not integerValue.HasValue Then integerValue = -1 End If

command.Parameters.AddWithValue(parameterName, integerValue) End Sub

Private Sub AddNullableDateParameter(ByVal command As SqlClient.SqlCommand, ByVal parameterName As String, ByVal dateValue As Nullable(Of Date)) If dateValue.HasValue Then command.Parameters.AddWithValue(parameterName, dateValue.Value) Else command.Parameters.AddWithValue(parameterName, DBNull.Value) End If End SubEnd Class

6.4.1 Deleting HistoryThe delete section action calls on a Blackbaud delete record operation named ‘Business Process Status: Delete’ to delete a business process instance’s history. The feature uses the USP_BUSINESSPROCESSSTATUS_DELETE stored procedure to delete a row in the BusinessProcessStatus table for the given ID. When a row is deleted from the BusinessProcessStatus table the related child records are deleted within the BusinessProcessOutput table via a foreign key with a cascade delete. The BusinessProcessOutput table’s TableName column refers to the output table generated by the business process CLR code. When a row within BusinessProcessOutput table is deleted a trigger attempts to delete the associated output table.

6.5 Job Schedules

Within the Job Schedules tab resides a data list that displays a list of SQL job schedules for a given business process. The data list is named ‘Business Process Job Schedule List’ and is provided by Blackbaud. The data list utilizes the USP_BUSINESSPROCESSJOBSCHEDULE_GETLISTBYPARAMETERSETID stored procedure to retrieve the job schedules for a given business process parameter set.


Figure 31 - Job Schedules Tab

6.5.1 Add, Edit, and Delete Job Schedule ActionsWithin the Job Schedules section and above the data list are the actions to manage job schedules. Below is a listing of the features referenced by each action:

Action Action Type Feature – Description

Is Custom?

Context Value

Add ShowAddDataForm Business Process Job Add Form - Creates a SQL job for a business process using a given SSIS package.

No Expression

=IIf(String.IsNullOrEmpty(Page.Fields!PARAMETERSETID.ToString()), "", String.Concat("Exchange Contact Synchronization Process|B531B950-2534-4E95-B104-805DB1328806|", Page.Fields!PARAMETERSETID.ToString())).ToString()

Edit ShowDataForm Business Process Job Edit Form - Edits a job schedule for a business process.

No Section Field: Schedule ID

Delete ExecuteRecordOperation Business Process Job Schedule: Delete - Deletes a SQL Server Agent job for a business process.

No Section Field: Job ID


Table 1 – Context Values for the Job Schedule Add, Edit, and Delete Actions

6.6 Action Group

6.6.1 Start Process ActionThe Start Process action starts our custom business process that we build using a BusinessProcessSpec and CLR code. The action has an action type equal to StartBusinessProcess. The action navigates the user back to the same page and thereby causes a refresh on the page to display the most recent status for the business process.

Figure 32 - Start Process Action’s Properties

6.6.2 Edit Process ActionThe Edit Process action opens the “Inventory Process Business Process Edit Form”. This is a custom edit data form that allows an end user to edit the parameter set associated with the business process. The data form accepts in a record type id of Inventory Process Parameter.


Figure 33 - The Inventory Process Business Process Edit Form

Figure 34 - The Edit Process Action's Properties

6.6.3 Generate WSF ActionA script is a file you create that describes the steps required to complete a task. A Windows Scripting File (.wsf) is an executable script file format for Windows that can incorporate VBScript (.vbs) routines and include XML elements. After you create the script, you can "run" that script, and it will perform all of the steps for you, saving you a great deal of time. You can use Microsoft Windows Task Scheduler to schedule tasks to run the Windows Scripting File through the other application at a time that is most convenient to your organization. You need only create the script once, and then you can reuse it any time you need to perform that task.1 It


incorporates several features that offer you increased scripting flexibility. Because Windows script files are not engine-specific, they can contain script from any Windows Script compatible scripting engine.2

Figure 35 - Generating a Windows Scripting File

Selecting the Generate WSF action, creates a Windows Scripting File which can be run once or scheduled using Windows Task Scheduler. In short, the generated script file consists of sending an HTTP request to the Infinity web server which houses the BusinessProcessInvoke.ashx web service handler. An .ashx is an ASP.NET HTTP handler is the process (frequently referred to as the "endpoint") that runs in response to a request made to an ASP.NET Web application.3 The BusinessProcessInvoke.ashx endpoint is used to start a business process using a pre-defined parameter set. This endpoint is designed to be accessed from any tool that can issue HTTP requests. It is used by the vbscript and jscript files that the platform generates for business processes. <?xml version="1.0" encoding="utf-8"?>

<job id="main">

<script language="VBScript">

<![CDATA[

Const SECURITY_FLAG_IGNORE_CERT_CN_INVALID = &h00001000

Const SECURITY_FLAG_IGNORE_CERT_DATE_INVALID = &H2000

Const SECURITY_FLAG_IGNORE_UNKNOWN_CA = &H100

Const WINHTTPREQUESTOPTION_SSLERRORIGNOREFLAGS = 4

Dim url

Dim xml

Dim responseText

url = "http://localhost/bbinfinity/BusinessProcessInvoke.ashx?DatabaseName=BBInfinity&BusinessProcessID=a28d4f17-53fe-48d9-85bc-37e12884dc00&ParameterSetID=aab44bb5-0277-47de-a6b4-3235bcecb5e7"

Set xml = CreateObject("WinHttp.WinHttpRequest.5.1")

Dim options

options = SECURITY_FLAG_IGNORE_CERT_CN_INVALID or SECURITY_FLAG_IGNORE_CERT_DATE_INVALID or SECURITY_FLAG_IGNORE_UNKNOWN_CA

xml.Option(WINHTTPREQUESTOPTION_SSLERRORIGNOREFLAGS) = options

xml.SetTimeouts 0, 60000, 30000, 604800000

xml.SetAutoLogonPolicy(0)

xml.Open "GET", url, False

xml.Send

xml.WaitForResponse

responseText = xml.ResponseText


If xml.Status <> 200 Then Err.Raise -2147221504 + 100, "Business process invoke step failed", responseText

Set xml = Nothing

]]>

</script>

</job>

6.6.3.1 Running the WSF Script FileWithin your Windows environment you can quickly run the script using of these methods:

Double-click the icon of the script file just as you would with an executable file

Click the start button, and then click Run. In the Open field of the Run dialog box, type the full path of the script and click OK.

From the command line, type the name of the script.

Schedule the script using Windows Task Scheduler

The Task Scheduler enables you to automatically perform routine tasks on a chosen computer. The Task Scheduler does this by monitoring whatever criteria you choose to initiate the tasks (referred to as triggers) and then executing the tasks when the criteria is met.4 Task Scheduler is started each time the operating system is started. It can be run either through the Task Scheduler graphical user interface (GUI) or through the Task Scheduler API.5

6.6.4 Create Job Schedule Action Selecting the Create Job Schedule action on a business process status page opens the Business Process Job Add Form which is a data form that ships with Blackbaud Enterprise CRM.


Figure 36 - Business Process Job Add Form

When the data form is saved, the data form’s save implementation code (business logic layer) will create a SQL job to execute the business process using a specific parameter set. The creation of the SQL job is a two step process:

1. When the data form is saved, a business process SQL job script is generated using the ID of the business process, the ID of the parameter set. A SQL job will call upon this script to execute the business process. The generated script can be used to make a web request to execute a business process. The web request consists of a URL that includes a query string that contains the database name, business process id, and parameter set id.

2. Once the script is built the script text is passed to a call to the USP_BUSINESSPROCESSJOBSCHEDULE_ADD stored procedure along with the job name, description, and schedule information. USP_BUSINESSPROCESSJOBSCHEDULE_ADD calls upon the sp_add_job and sp_add_jobstep and sp_add_jobschedule and sp_add_jobserver stored procedures that ship with SQL Server. sp_add_job adds a new job executed by the SQLServerAgent service. After sp_add_job has been executed to add a job, sp_add_jobstep can be used to add steps that perform the activities for the job. sp_add_jobstep adds a step (operation) named ‘Business process invoke’ to the job. It is in the call to sp_add_jobstep that the generated script is passed via the @COMMAND parameter. sp_add_jobschedule can be used to create the schedule that






the SQL Server Agent service uses to execute the job. sp_add_jobserver sets the SQL Server instance where the job executes.

6.6.4.1 Viewing the Job ScheduleOnce the job schedule has been created it can be viewed, edited, and deleted from the page’s Job Schedules tab:

Figure 37 - Created job schedules are managed from the Job Schedules tab

Note: The job schedule should be marked as “Enabled” before the SQL Server Agent will process the job. Also, the SQL Server Agent service will need to be running in order for SQL Server to process the active job schedule.

6.6.4.2 Viewing and Troubleshooting the Job ScheduleOnce the job has been created, the job and its history can be viewed within SQL Server Management Studio under the appropriate database server’s SQL Server Agent node. The Jobs folder within the SQL Server Agent node lists all the scheduled jobs. Viewing the history for the job is an excellent place to troubleshoot any problems with the execution for the scheduled job. See below:



Figure 38 - Viewing the job history to investigate errors with the SQL job

6.6.4.3 Viewing the Job HistoryOnce the job schedule has been successfully run by the SQL Server Agent service, the history of the execution will be visible within the History tab on the page.

6.6.5 Create Task ActionSelecting the Create Task action on the business process status page opens the “Run Business Process task Add” form which ships with Blackbaud Enterprise CRM. This data form allows the user to create a task that will allow users to run the business process with the current parameter set. One of the steps in completing the “Run Business Process task Add” form is to provide a launch page which is designated by the Page property within the BusinessProcess property group. A Page Search for the Page property allows the user to search for a launch page that shares the same record type as the business process. In the example below our own status page is doing double duty as the launch page.


Figure 39 - Completing the data form opened via the Create task action

When the data form shown above is saved, the end results will be a new task that will utilize and action type of “RunBusinessProcess”. Navigating back to the food bank functional area and refreshing shell navigation reveals the new task:

Using design mode, we can right click the task and examine its properties. As you can see in the figure below the task utilizes an action type of RunBusinessProcess. For more information regarding the RunBusinessProcess action type see Using a Task’s RunBusinessProcess Action Type.


Figure 40 - The newly created task

6.6.6 Delete Process ActionClicking the “Delete process” action within the Tasks action group on our status page will call upon a custom record operation to delete the parameter set for the business process. In the case of our custom record operation a stored procedure is used to delete a row from the custom USR_INVENTORYPROCESS table which is used to store the parameter data for a specific business process.

Figure 41 - Delete process action

For more information see Business Process Parameter Set Table.


7 Typical Catalog Project Specs and Code

The table below lists the specs and class file used to create a typical business process. These files should be located within your catalog project along with your other catalog items. References to specific samples are included. Use this table to help scope the number of artifacts required for your particular situation.

The source code for the food bank customization can be found within the Blackbaud Developer Network (BBDN).

7.1 BusinessProcessSpec

The BusinessProcessSpec describes a custom processor to be used to process data. This spec contains a ProcessorComponent child element which describes the processor which is based on Microsoft .NET CLR code. The code is housed within a .NET CLR assembly hosted in the web service layer. Also contains a BusinessProcessOutputHeader child element that describes how to designate one or several QueryViewSpecs which are used to generate an output format for the business process.

Sample Food Bank Spec File Name: InventoryProcess.BusinessProcess.xml<BusinessProcessSpec

xmlns="bb_appfx_businessprocess"xmlns:common="bb_appfx_commontypes"ID="a28d4f17-53fe-48d9-85bc-37e12884dc00"Name="Inventory Process Business Process"Description="Business process to get the inventory report for food banks."Author="Technical Training"GeneratesOutput="true"ParameterTableName="USR_INVENTORYPROCESS"RecordType="Food Bank" common:SecurityUIFolder="Food Bank\Inventory">



<ProcessorComponent AssemblyName="Blackbaud.CustomFx.FoodBank.Catalog" ClassName="Blackbaud.CustomFx.FoodBank.Catalog.InventoryProcessBusinessProcess">

<common:GrantExecuteList><common:GrantExecute>USR_USP_INVENTORYPROCESS_GETPARAMETERS</common:GrantExecute>

</common:GrantExecuteList><common:GrantSelectList>

<common:GrantSelect>UFN_IDSETREADER_GETRESULTS</common:GrantSelect> <common:GrantSelect>USR_UFN_FOODBANKSELECTION</common:GrantSelect>

</common:GrantSelectList>

</ProcessorComponent> 

<BusinessProcessOutputHeader><OutputQueryViewList>

<OutputQueryView OutputViewMetaTag="Inventory" /></OutputQueryViewList>

</BusinessProcessOutputHeader></BusinessProcessSpec>


http://bbdevnetwork.com/content/food-bank-source-code

For more information see Business Process Overview, Processing the Data, Business Process Logic, and Building the Business Process Processing Logic, and Exercise - Building the Processing Logic for the Food Bank Inventory Business Process

7.1.1 BusinessProcessSpec XML ElementThe BusinessProcessSpec element describes a custom processor to be used to process data.

7.1.1.1 BusinessProcessSpec Element’s ParameterTableName AttributeOptional. Name of the table where parameters for this business process are saved. Up to 100 characters, beginning with A-Z, followed by one or more upper case letters and digits. The parameter table must be created in the database prior to loading the BusinessProcessSpec with this attribute. When the spec is loaded into the catalog a status table is created for this business process. For example, if the ParameterTableName is USR_BUSINESSPROCESSTEST then a table named USR_BUSINESSPROCESSTESTSTATUS will be created. This status table serves as a join table to the BUSINESSPROCESSSTATUS table for the table named within the ParameterTableName Attribute. <BusinessProcessSpec

xmlns="bb_appfx_businessprocess"xmlns:common="bb_appfx_commontypes"ID="a28d4f17-53fe-48d9-85bc-37e12884dc00"Name="Inventory Process Business Process"Description="Business process to get the inventory report for food banks."Author="Technical Training"GeneratesOutput="true"ParameterTableName="USR_INVENTORYPROCESS"RecordType="Food Bank" common:SecurityUIFolder="Food Bank\Inventory">

See these tables within Business Process Subject Area ERD for more details.

7.1.1.2 BusinessProcessSpec Element’s GeneratesOutput AttributeOptional. Default value = "false". The GeneratesOutput attribute indicates whether the process generates output via a database table that can be exported later. When this attribute is set to “true” and the spec is loaded into the catalog system, the system will create an export table. The system appends “EXPORTFORMAT” to the name of the database table defined within the ParameterTableName attribute. Ex: USR_INVENTORYPROCESSEXPORTFORMAT.

If you want to support export formatting, then you will need to provide a mechanism, such as the data forms that manage the adding and editing of a parameter set, to add a row into the BUSINESSPROCESSEXPORTFORMAT table and your custom export format table (example: USR_INVENTORYPROCESSEXPORTFORMAT). See the trigger TR_EXPORTPROCESS_INSERT on the EXPORTPROCESS Tables on an example of how to add a default record into the BUSINESSPROCESSEXPORTFORMAT table.

When your custom business process processing logic code executes and you are supporting export formatting your code should retrieve data from your custom export format table (Ex: USR_INVENTORYPROCESSEXPORTFORMAT) and the BUSINESSPROCESSEXPORTFORMAT table to determine the formatting of your data during the output generation. <BusinessProcessSpec

xmlns="bb_appfx_businessprocess"xmlns:common="bb_appfx_commontypes"ID="a28d4f17-53fe-48d9-85bc-37e12884dc00"Name="Inventory Process Business Process"Description="Business process to get the inventory report for food banks."Author="Technical Training"


TripOt, 11/01/11,


GeneratesOutput="true"ParameterTableName="USR_INVENTORYPROCESS"RecordType="Food Bank" common:SecurityUIFolder="Food Bank\Inventory">

See these tables within Business Process Subject Area ERD for more details.

7.1.1.3 BusinessProcessSpec Element’s AllowOutputTableRemoval AttributeOptional. Default value = "false". This attribute indicates whether the process that generates output allows the output tables to be dropped as part of the system clean up tasks. This does not remove the status row that indicates that the process has been run. Also, the process needs to make sure that no assumptions are made regarding the existance of the output tables before setting this to true.

7.1.1.4 BusinessProcessSpec Element’s ParameterLabelField AttributeOptional. Default value = "NAME". The name of the field in the parameter table which represents the label for the business process parameter set. Up to 100 characters, beginning with A-Z, followed by one or more upper case letters and digits.

7.1.1.5 BusinessProcessSpec Element’s RecordType AttributeRequired. Indicates the record type, which is the primary type of record used in the process.

7.1.1.6 BusinessProcessSpec Element’s AllowSimultaneousExecution AttributeOptional. Default value = "false". This attribute indicates whether the business process should be allowed to be started if another process of the same type is already running.

See Simultaneous Run Check and When a business process instance starts… for details.

7.1.2 ProcessorComponent ElementThis element describes the processor based on CLR code. Information for catalog feature implemented in a .NET CLR assembly hosted in the web service layer.

See Business Process Logic and Building the Business Process Processing Logic for details.

7.1.2.1 ProcessorComponent Element AssemblyName and ClassName AttributesThe name of the assembly which contains the catalog feature code. The name of the class within the assembly that contains the catalog feature code.

7.1.2.2 ProcessorComponent Element’s GrantExecuteList Child ElementContains a list of the database procedure names that require EXECUTE rights for the executing code via child GrantExecute elements. Typical entries include references to stored procedures call by the processing logic including those that retrieve business process parameters.


TripOt, 11/01/11,


7.1.2.3 ProcessorComponent Element’s GrantSelectList Child ElementContains a list of database tables or views (including columns) that require SELECT rights for the executing code via child GrantSelect elements.


7.1.2.4 ProcessorComponent Element’s GrantUpdateList Child ElementContains a list of the database tables that require UPDATE rights for the executing code via child GrantUpdate elements.

7.1.2.5 ProcessorComponent Element’s GrantInsertList Child ElementContains a list of the database tables that require INSERT rights for the executing code via GrantInsert child elements.

7.1.2.6 ProcessorComponent Element’s GrantDeleteList Child ElementContains a list of the database tables that require DELETE rights for the executing code via GrantDelete child elements.

7.1.2.7 ProcessorComponent Element’s StaticParameters Child ElementIndicates fixed-value parameters to pass to the CLR object.

7.1.3 BusinessProcessOutputHeader ElementDescribes how to designate a view to generate and output header file for a business process.

7.1.3.1 BusinessProcessOutputHeader Element’s OutputQueryviewList ElementContains a list of QueryViewSpecs that can be associated with the business process to generate the output header file.


7.1.4 FormMetaData ElementThis element is used to define a pre-process edit data form to be used when the business process does not have parameters saved to a database table. This is a mechanism to display a form fields in the user interface after the business process has been started but prior to processing shifting to the business processor code on the web server.

Note: Blackbaud does not currently use this element to represent a pre-process edit data form. Instead, Blackbaud recommends the using of a separate edit data form to represent the pre-process data form. See Business Process Parameters and Configuring Parameter Sets and Starting a Business Process without a Pre-Process Edit Data Form for more information.

7.1.5 QueryViewSpec(s) to Define the Output Format (Optional)Optional. Query view used to define the output format for the business process. Can be used to create a query view that is in turn referenced as a parameter within the parameter set. Be sure to use a MetaTag within the QueryViewSpec. Be sure to use a BusinessProcessOutput tag within the QueryViewSpec. See Using a QueryViewSpec as a Parameter for Output Formatting for more information.

Food Bank Sample Spec File Names:

InventoryProcessLowInventoryOutput.Query.xml, InventoryProcessCurrentInventoryOutput.Query.xml

7.1.6 SQLFunctionSpec to Limit the OutputUse a SQLFunctionSpec with a CreateSelection tag to define and limit a set of rows upon which business process will act. Used to describe a SQL Server user defined function that creates a selection of records. This selection may be used as input within an ad-hoc query or smart query or other process to limit the amount of rows acted upon. The query may be used to generate a selection of rows that are used as input into a business process. See the section titled Using a Selection as a Parameter to Restrict the Row Set and IDSETREGISTER Table Contains a List of Selections for more information.

Food Bank Sample Spec File Name: USR_UFN_FOODBANKSELECTION.xml

7.1.7 SQLStoredProcedureSpec to Retrieve the Parameters within the Processing CodeThe SQLStoredProcedureSpec is used to defines a stored procedure that is used within the business process .NET CLR code to retrieve the instance parameters for a given id. See Retrieve and Validate the Parameters: Validate() for more information.

Food Bank Sample File Name: InventoryProcessBusinessProcess.vb

Food Bank Sample Spec File Name: USR_USP_INVENTORYPROCESS_GETPARAMETERS.xml

7.2 Specs to Manage the Parameter Sets

One of the tasks a business process administrator/end user will need to accomplish is managing parameter sets for a given business process.

See Parameter Set Page.

7.2.1 TaskSpec to Launch the Parameter Set PageOne of the tasks a business process administrator/end user will need to accomplish is managing parameter sets for a given business process. Once a parameter set has been established, the user should be able to launch a new instance of the business process and direct the user to a separate page to view history of previous business process instances. The task is used to open the page which manages parameter sets.


TripOt, 10/11/11,

Link to appropriate place within new HTML help

TripOt, 10/11/11,


Food Bank Sample Spec File Name: ManageBusinessProcesses.Task.xml.

See SDK Developer Responsibilities, Parameter Set Page, and Business Process Tasks

7.2.2 PageDefinitionSpec for the Parameter Set PageDisplays configured parameter sets for the business process. One of the tasks a business process administrator/end user will need to accomplish is managing parameter sets for a given business process. Once a parameter set has been established, the user should be able to launch a new instance of the business process and direct the user to a separate page to view history of previous business process instances.

Food Bank Sample Spec File Name: InventoryProcessParameterSet.Page.xml

See SDK Developer Responsibilities and Parameter Set Page

7.2.3 TableSpec for the Custom Parameter Set TableUse a TableSpec to stored business process parameters for a given business process. The business process parameter table may have any number of fields to hold the parameter values for the business process. See Parameter Set Table and the Parameter Set Page sections for more information.

Food Bank Sample Spec File Name: InventoryProcess.Table.xml

7.2.4 AddDataFormTemplateSpec to Add a Parameter SetData form for adding inventory process business parameter information into the table that stores business process parameters for a given business process. Used within the Parameter Set Page.

Food Bank Sample Spec File Name: InventoryProcess.Add.xml

7.2.5 EditDataFormTemplateSpec to Edit a Parameter SetData form for editing inventory process business process parameters. Used within the Parameter Set Page.

Food Bank Sample Spec File Name: InventoryProcess.Edit.xml

7.2.6 EditDataFormTemplateSpec for the Pre-Process Edit Data Form Through configuration a SDK developer or anyone familiar with the capabilities of page designer can provide additional parameters for the “Start process” action button to include a pre-process edit form. See Business Process Parameters and Managing Parameter Sets and Starting a Business Process with a Pre-Process Edit Data Form

Food Bank Sample Spec File Name: None. See the BBEC Feature Named ‘Print Membership Cards Preprocess Edit Form’ within for an example.

7.2.7 RecordOperationSpec to Delete a Parameter SetDeletes the parameter set for a business process. Used on the Parameter Set Page and the business process instance status page.

Food Bank Sample Spec File Name: InventoryProcessDelete.RecordOperation.xml

7.2.8 DataListSpec to List the Parameter SetsReturns a list of parameter sets for the business process. Data list is filtered based on security permissions for the current application user. Used on the Parameter Set Page. See Parameter Set Table for more information.

Food Bank Sample Spec File Name: InventoryProcesses.DataList.xml


TripOt, 10/11/11,


7.3 Specs to Manage the Business Process Status

A business process instance status page or also known as the ‘status page’ is primarily used to view the recent and historical statuses for a business process and its associated parameter set. After a business process is started manually, the task or action typically will redirect the user to the status page.

See Business Process Instance Status Page.

7.3.1 TaskSpec to Launch the Status PageSee TaskSpec, SDK Developer Responsibilities and Business Process Tasks

7.3.2 PageDefinitionSpec for the Status PageA custom page to displays information about the status of a business process instance. The ‘status page’ is primarily used to view the recent and historical statuses for a business process and its associated parameter set. After a business process is started manually, the task or action typically will redirect the user to the status page.

Food Bank Sample Spec File Name: InventoryProcessStatus.Page.xml

See Business Process Instance Status Page.

7.3.3 ViewDataFormTemplateSpec for the Summary Section on the Status PageView data form for an inventory business process parameter set. Simple view data form that is shown on the business process instance status page within the summary section at the top of the page.

Food Bank Sample Spec File Name: InventoryProcess.View.xml\

7.3.4 ViewDataFormTemplateSpec for the Expression View Data Form on the Status PageA page may contain a reference to an Expression Data Form which is a type of ViewDataForm. An Expression Data Form is never actually displayed in the UI. Instead it acts behind the scenes to gather important information about the displayed record and make it available to the page.

Food Bank Sample Spec File Name: InventoryProcessPageExpression.View.xml

See Expression Data Form Drives Expressions on the Status Page

7.3.5 DataListSpec to Return a Status ListThe Infinity SDK developer will need to build a business process instance status page to view the status of current and historical processes. Within that page will be a data list which displays a historical list of business process runs. For more information see the History Tab within Business Process Instance Status Page.

Food Bank Sample Spec File Name: InventoryProcessStatus.DataList.xml


TripOt, 10/11/11,


TripOt, 10/11/11,


TripOt, 10/11/11,


TripOt, 10/11/11,


TripOt, 10/11/11,


TripOt, 10/11/11,


TripOt, 10/11/11,


8 Tables

8.1 Overview

Before we describe each of the tables used to support business processes, let’s take a moment and discuss the general needs and requirements of business processes and how tables are used to support these requirements. A business process is defined by an Infinity SDK software developer through the creation of a BusinessProcessSpec. When loaded into the Infinity database, this spec’s metadata will wind up within the BusinessProcessCatalog table. See the section titled BusinessProcessCatalog table for more details.

When a business process is started, an instance of that business process is created. When an instance is started, the status of a business process instance is tracked within the BusinessProcessStatus table. This table may contain many rows for a given BusinessProcessCatalog table row. Of great importance is the fact that the BusinessProcessStatus table tracks the parameter set selected for a given business process instance.

A business process instance may require input parameters. Along with the status, the selected parameter set chosen for the instance can be tracked. During configuration and before a business process instance is started, individual input parameters are grouped together into a set and the set is labeled with a name. The table that holds the parameter sets is a custom table that is specific to a business process and is referenced by the ParameterTableName attribute within the BusinessProcessSpec. Within the system, an end user can configure and secure multiple parameter sets for a given business process. Before a business process instance can be started, an end user must select a specific parameter set. See the section titled Business Process Parameter Table for more details.

Typically, before starting an instance, an end user may select a reference to a specific QueryViewSpec as one of the input parameters into a process. Once a parameter set is selected and a business process instance is started, the Infinity platform will call upon .net code to process a set of records. The basis for the set of records to be retrieved and processed by the .net code is defined with a QueryViewSpec. The selected QueryViewSpec for a business process also determines the columns for the output of a business process. A business process instance may be run with one of several associated QueryViewSpecs which are tracked within the BusinessProcessView table.

A business process may be designed to produce one or several tables filled with data as its output. This is where the BusinessProcessOutput table comes into play. Each table or tables that are created by a business process should have a representative row within the BusinessProcessOutput table. This table is a child table of the BusinessProcessStatus table and aids the developer in finding the table or tables generated by a specific business process instance.

Each business process will have one or more sets of parameter data. A business process should be secured at the parameter set level. The BusinessProcessInstance table supports the securing of a parameter set for a business process to a particular site and/or selected security roles. For more information on securing parameter sets for a business process see the section titled BusinessProcessInstance table.

8.2 BusinessProcessCatalog Table

A business process is defined by an Infinity SDK software developer through the creation of a BusinessProcessSpec. When loaded, this spec will wind up within the BusinessProcessCatalog table. The BusinessProcessCatalog table is used to catalogue business processes as defined by a BusinessProcessSpec.

The ParameterTableName field denotes the name of the table which stores the parameter sets for the business process. The AllowSimultaneousExecution field designates whether or not multiple instances of the


same process type can be run simultaneously. A one-to-many relationship exists between the BusinessProcessCatalog table and the BusinessProcessInstance, BusinessProcessStatus, QueueProcessResult and BusinessProcessView tables.

erd Business Process ERD

BUSINESSPROCESSCATALOG

«column»*PK ID :uniqueidentifier = (newid())* ALLOWSIMULTANEOUSEXECUTION :bit = ((0))* NAME :nvarchar(60)* DESCRIPTION :nvarchar(1000) = ('')* BUSINESSPROCESSSPECXML :xml*FK RECORDTYPEID :uniqueidentifier PARAMETERTABLENAME :nvarchar(100) = ('')* PARAMETERLABELFIELD :nvarchar(100)* SECURITYUIFOLDER :nvarchar(255) = ('')*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

Figure 42 - BusinessProcessCatalog table

8.3 BusinessProcessStatus Table

The BusinessProcessStatus table contains information pertaining to the business process status information. A new row will be added for each created instance of a business process; therefore, this table is a child table of the BusinessProcessCatalog table.




BUSINESSPROCESSSTATUS

«column»*PK ID :uniqueidentifier = (newid())*FK BUSINESSPROCESSCATALOGID :uniqueidentifier* STATUSCODE :tinyint = ((0)) STATUS :nvarchar(25)* STARTEDON :datetime*FK STARTEDBYUSERID :uniqueidentifier ERRORMESSAGE :nvarchar(max)* SERVERNAME :nvarchar(255) NUMBERPROCESSED :int = ((0)) NUMBEROFEXCEPTIONS :int = ((0)) LETTERTEMPLATE :varbinary(max) LABELTEMPLATE :varbinary(max)*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint ENDEDON :datetime BUSINESSPROCESSPARAMETERSETID :uniqueidentifier

0..*

1

Figure 43 - BusinessProcessStatus table tracks business process instances


Most importantly the BusinessProcessParameterSetID field refers to a primary key of your custom parameter tables used by your custom business process; in the food bank inventory business process example this is the custom USR_INVENTORYPROCESS table. See the section titled Business Process Parameter Table for more details. The Status field stores the current status of the business process contains the following possible values: completed, completed with exceptions, running, did not finish, and results cleared. See table below. The ErrorMessage field contains the reason why the business process could not be completed. The NumberProcessed field represents the number of records successfully processed by the business process. The NumberOfExceptions field represents the number of record exceptions found during the business process. The StartedOn field designates the date and time that the business process instance was started. The EndedOn field designates the date and time that the business process instance ended.

BUSINESSPROCESSSTATUS STATUS Computed Column

Expression Computed Value

STATUSCODE= 0 AND NUMBEROFEXCEPTIONS =0

Completed

STATUSCODE=0 AND NUMBEROFEXCEPTIONS > 0

Completed with exceptions

STATUSCODE=1 Running

STATUSCODE=2 Did not finish

STATUSCODE=3 Results cleared

8.4 Business Process Parameter Set Table (USR_INVENTORYPROCESS)

The business process parameter set table stores parameter data for a specific business process. The table that holds the parameter sets is a custom table that is specific to a business process and is referenced by an attribute within the BusinessProcessSpec. The business process parameter set table is referenced by the ParameterTableName attribute of the BusinessProcessSpec. Below is an example of the ParameterTableName attribute.

Figure 44 - ParameterTableName attributeAn end user can configure multiple parameter sets for a given business process which are stored within the table reference by the ParameterTableName attribute. Before a business process instance can be started, an end user must select a specific parameter set.







USR_INVENTORYPROCESS

«column»*PK ID :uniqueidentifier = (newid())* NAME :nvarchar(100) = ('')* DESCRIPTION :nvarchar(255) = ('')*FK IDSETREGISTERID :uniqueidentifier*FK QUERYVIEWID :uniqueidentifier*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

The BUSINESSPROCESSSTATUS. BUSINESSPROCESSPARAMETERSETID field refers to a primary key of your custom parameter table used by your custom business process. The business process parameter table stores parameter data for a specific business process. This table is referenced by the ParameterTableName attribute of the BusinessProcessSpec. In this example, we represent a typical, custom parameter table via the USR_INVENTORYPROCESS table.

0..*

1

0.1:

Figure 45 – The USR_INVENTORYPROCESS table is used as the parameter set table for the food bank inventory business process

The business process parameter table is defined by the Infinity SDK software developer using a TableSpec. There are virtually no restrictions on the types of fields that can be added to this table other than those restrictions normally placed on table specs by the Infinity platform. The business process parameter table may have any number of fields to hold the parameter values for the business process. The upside is this provides an extremely flexible storage area to hold the parameters for any given business process. The downside is the structure of the business process parameter table will vary widely from business process to business process and therefore it will be impossible to predict its contents or references to other parameter metadata without an inspection of the BusinessProcessSpec xml and the associated table spec which creates the business process parameter table.

8.4.1 Sample Business Process Parameter TableBelow is an example of a table spec designed to hold the parameter values for a sample business process. This sample comes from the food bank inventory business process SDK sample code used by technical training personnel to teach Infinity SDK concepts. Each row within the USR_INVENTORYPROCESS table holds a reference to a parameter set that is passed to the business process when started. Therefore, you can deduce that a business process can be started from a choice of parameter sets.


Figure 46 - TableSpec Used to Build the Inventory Process Parameter Set Table

The NAME and DESCRIPTION fields within the table spec hold the name and description of the parameter set.

8.4.1.1 IDSETREGISTERID Field References the IDSETREGISTER Table The IDSETREGISTER table contains a list of selections used throughout the system. Often business processes will require a reference to what’s a known as a selection which is a set of record id’s for a particular record type. Selections can be created using Blackbaud’s query tool by first creating either an ad-hoc query or smart query and then saving the query results as a selection. A selection may be created by other business processes as some processes employ an option to "Create selection of processed records”. A selection contains the ids of the records to be used as input into and processed by a business process in order to restrict the number of rows processed.

Within the food bank inventory business process, the IDSETREGISTERID field points to a system table named IDSETREGISTER. Each row in the IDSETREGISTER table corresponds to a view or table-valued function that returns a list of Primary Key ID values of a particular record type (database table), such as Constituent or Revenue.


Note: Selections can be created via Blackbaud’s Query tool. A selection can be used as an input parameter into a business process instance. A selection is a list of record ids used within the business process .net code to restrict the number of rows processed via a SQL JOIN or WHERE clause.

Check out the following materials on query and selections within the Query and Export Guide if you are unfamiliar with either topic.

As an example of how a selection is used as a parameter within a parameter set for a business process, let’s take a look at a data form used to manage a parameter set. Within the Food Bank’s Inventory Process Business Process Add and Edit Forms, you can choose the selection to be used as input parameter into the business process. Once saved, the data from these data forms will be saved to a row USR_INVENTORYPROCESS table. See below.

Figure 47 - The Inventory Process Business Process Edit Form is used to edit a parameter set for the food bank inventory business process

Before starting a business process, a row must be selected from this table to provide the business process with the necessary input parameter data.

Figure 48 – Selecting a parameter set prior to starting a business process.

8.4.1.2 The QUERYVIEWID Field References the QUERYVIEWCATALOG tableThe QUERYVIEWCATALOG table holds the metadata for each query view defined within the system. In our sample custom business process we allow the end user to select specific query views which have been custom built to define the output format of the business process. See BUSINESSPROCESSVIEW table.



8.4.1.3 Business Process Parameter Table TriggerThe TableSpec used to create the business process parameter table contains a delete trigger used to delete related rows within the BusinessProcessInstanceTable. See below.

Figure 49 - Trigger on parameter set table deletes security rows within the BusinessProcessInstance table

8.4.2 Business Process Parameter Status Table (USR_INVENTORYPROCESSSTATUS)The data is this table holds the status information for the given business process parameter set. The table name is derived by concatenating the value of the ParameterTableName attribute of the BusinessProcessSpec with the word ‘STATUS’, for example: USR_INVENTORYPROCESSSTATUS. This table serves as a join table to the BUSINESSPROCESSSTATUS table for the business process parameter table (USR_INVENTORYPROCESS).


erd Business Process


«column»*PK ID :uniqueidentifier = (newid())*FK BUSINESSPROCESSCATALOGID :uniqueidenti fier* STATUSCODE :tinyint = ((0)) STATUS :nvarchar(25)* STARTEDON :datetime*FK STARTEDBYUSERID :uniqueidenti fier ERRORMESSAGE :nvarchar(max)* SERVERNAME :nvarchar(255) NUMBERPROCESSED :int = ((0)) NUMBEROFEXCEPTIONS :int = ((0)) LETTERTEMPLATE :varbinary(max) LABELTEMPLATE :varbinary(max)*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidenti fier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint ENDEDON :datetime BUSINESSPROCESSPARAMETERSETID :uniqueidentifier

notesContains information pertaining to the business process status information


«column»*PK ID :uniqueidenti fier = (newid())* NAME :nvarchar(100) = ('')* DESCRIPTION :nvarchar(255) = ('')*FK IDSETREGISTERID :uniqueidentifier*FK QUERYVIEWID :uniqueidentifier*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

notesTable to store business process parameters for the inventory business process.

USR_INVENTORYPROCESSSTATUS

«column»*pfK ID :uniqueidenti fier = (newid())*FK PARAMETERSETID :uniqueidentifier*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

notesServes as a join table to the BUSINESSPROCESSSTATUS table for the USR_INVENTORYPROCESS table.

The “Business Process Parameter Set Recent Status View Form”,which is typically placed on the Recent Status tab on the Status page, utilizes the data within Business Process Parameter Status Table. In addition the custom data list which is displayed on the History tab pulls data from the Business Process Parameter Status Table.

8.4.3 Business Process Parameter Export Format Table (USR_INVENTORYPROCESSEXPORTFORMAT)

This table serves as a join table to the BUSINESSPROCESSEXPORTFORMAT table for the Business Process Parameter Table (USR_INVENTORYPROCESS) table. The BUSINESSPROCESSEXPORTFORMAT table defines the format in which data from a business process's output will be displayed when exported. The export process helps you extract data from the program to use in other applications. For example, you may want to export data to send to a mailing house to update addresses. Once you create an export process, you can edit and reuse it as you update your data. When you add an export process, you assign it a name and description to help identify it and select the query to export.

For more information about Export. See the Query and Export Guide on Blackbaud.com. See also the BusinessProcessSpec’s GeneratesOuput attribute.


Figure 50 - 8.4.4 Business Process Parameter Export Format Table


erd Business Process

BUSINESSPROCESSEXPORTFORMAT

«column»*PK ID :uniqueidentifier = (newid())* CURRENCYSYMBOL :nvarchar(4) = ('')* CURRENCYGROUPSEPARATOR :nvarchar(4) = ('')* CURRENCYDECIMALSEPARATOR :nvarchar(4) = ('')* CURRENCYDECIMALDIGITS :tinyint = ((0))* DATEFORMAT :nvarchar(50) = ('')* FUZZYDATEFORMAT :nvarchar(50) = ('')* MONTHDAYFORMAT :nvarchar(50) = ('')* HOURMINUTEFORMAT :nvarchar(50) = ('')*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint* CURRENCYSYMBOLDISPLAYSETTINGCODE :tinyint = ((0)) CURRENCYSYMBOLDISPLAYSETTING :nvarchar(20)* CURRENCYGROUPSEPARATORDISPLAYSETTINGCODE :tinyint = ((0)) CURRENCYGROUPSEPARATORDISPLAYSETTING :nvarchar(21)* CURRENCYDECIMALSEPARATORDISPLAYSETTINGCODE :tinyint = ((0)) CURRENCYDECIMALSEPARATORDISPLAYSETTING :nvarchar(21)* CURRENCYDECIMALDIGITSDISPLAYSETTINGCODE :tinyint = ((0)) CURRENCYDECIMALDIGITSDISPLAYSETTING :nvarchar(20)

notesDefines the format in which data from a business process's output will be displayed when exported.


«column»*PK ID :uniqueidentifier = (newid())* NAME :nvarchar(100) = ('')* DESCRIPTION :nvarchar(255) = ('')*FK IDSETREGISTERID :uniqueidentifier*FK QUERYVIEWID :uniqueidentifier*FK ADDEDBYID :uniqueidenti fier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

notesTable to store business process parameters for the inventory business process.

USR_INVENTORYPROCESSEXPORTFORMAT

«column»*pfK ID :uniqueidentifier = (newid())*FK PARAMETERSETID :uniqueidentifier*FK ADDEDBYID :uniqueidenti fier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

notesServes as a join table to the BUSINESSPROCESSEXPORTFORMAT table for the USR_INVENTORYPROCESS table.

8.5 BusinessProcessView Table

Typically, before starting an instance, an end user will select a reference to a specific QueryViewSpec as one of the input parameters into a process. In this way, the end user may decide on which type of calculation is performed as well as which columns are created as an outcome of the business process instance. Once a parameter set is selected and a business process instance is started, the Infinity platform will call upon .NET


code to process a set of records. This .net code is the heart of the business process. The assembly and class containing this code and is referred to within the BusinessProcessSpec via the ProcessorComponent xml element. The basis for the set of records to be retrieved and processed by the .net code is defined with a QueryViewSpec. The QueryViewSpec also defines the format of the output of the business process via the columns referenced within the QueryViewSpec. A business process may have more than one associated QueryViewSpec which is tracked with the BusinessProcessView table. The BusinessProcessView table contains information pertaining to views used for output for a given business process. This table, shown to the right of the BusinessProcessCatalog table in the figure below, is a child table of the BusinessProcessCatalog table.



«column»*PK ID :uniqueidentifier = (newid())* ALLOWSIMULTANEOUSEXECUTION :bi t = ((0))* NAME :nvarchar(60)* DESCRIPTION :nvarchar(1000) = ('')* BUSINESSPROCESSSPECXML :xml*FK RECORDTYPEID :uniqueidentifier PARAMETERTABLENAME :nvarchar(100) = ('')* PARAMETERLABELFIELD :nvarchar(100)* SECURITYUIFOLDER :nvarchar(255) = ('')*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint



BUSINESSPROCESSVIEW

«column»*PK ID :uniqueidentifier = (newid())*FK BUSINESSPROCESSCATALOGID :uniqueidentifier*FK QUERYVIEWCATALOGID :uniqueidentifier* CAPTION :nvarchar(255) = ('')* JOINFIELD :nvarchar(128) = ('')*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

0..*

1

0..*

1

Figure 51 - BusinessProcessView table is populated when a QueryViewSpec contains a BusinessProcessOutput tag

The BusinessProcessView table is populated with a row when a QueryViewSpec which contains a BusinessProcessOutput tag is loaded into the catalog. This defines how the output format joins with the business process. For a given business process, the BusinessProcessView table can contain references to many QueryViewSpecs via the QueryViewCatalogID field. Once can deduce that a business process could be run with any one of the several query views referenced. Below is an example of QueryViewSpec used by the food bank inventory business process. Note the BusinessProcessOutput tag at the bottom of the spec. When the BusinessProcessOutput tag is included, a row is added to the BusinessProcessView table.


Figure 52 - The BusinessProcessOutput XML element links the query view to a business process


8.6 BusinessProcessOutput Table

Output tables may be created as a result of a business process. The BusinessProcessOutput table contains data describing the output of a particular business process run. The BusinessProcessOutput.TableName field refers to an output table for a given instance of a business process. The BusinessProcessOutput.TableKey field is the key by which this table will be referenced internally. Looking at the figure below you can see that the BusinessProcessOutput table is a child table of the BusinessProcessStatus table. The content and columns defined within each output table is typically determined by a QueryViewSpec referenced within the BusinessProcessView table. In the figure below, the yellow tables represent examples of the two different types of output tables that can be produced by the food bank inventory business process sample. Note the different columns in each table which are defined through two separate QueryViewSpecs.



«column»*PK ID :uniqueidenti fier = (newid())* ALLOWSIMULTANEOUSEXECUTION :bit = ((0))* NAME :nvarchar(60)* DESCRIPTION :nvarchar(1000) = ('')* BUSINESSPROCESSSPECXML :xml*FK RECORDTYPEID :uniqueidentifier PARAMETERTABLENAME :nvarchar(100) = ('')* PARAMETERLABELFIELD :nvarchar(100)* SECURITYUIFOLDER :nvarchar(255) = ('')*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

BUSINESSPROCESSINSTANCE

«column»*PK ID :uniqueidenti fier = (newid())*FK BUSINESSPROCESSCATALOGID :uniqueidentifier* BUSINESSPROCESSPARAMETERSETID :uniqueidentifier* SECURITYLEVEL :tinyint = ((0)) FK OWNERID :uniqueidenti fier*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint FK SITEID :uniqueidenti fier

BUSINESSPROCESSOUTPUT

«column»*PK ID :uniqueidenti fier = (newid())*FK BUSINESSPROCESSSTATUSID :uniqueidenti fier* TABLENAME :nvarchar(128) = ('')* TABLEKEY :nvarchar(50) = ('')*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint DOWNLOADPARAMETERS :xml COLUMNMETADATA :xml


«column»*PK ID :uniqueidenti fier = (newid())*FK BUSINESSPROCESSCATALOGID :uniqueidentifier* STATUSCODE :tinyint = ((0)) STATUS :nvarchar(25)* STARTEDON :datetime*FK STARTEDBYUSERID :uniqueidentifier ERRORMESSAGE :nvarchar(max)* SERVERNAME :nvarchar(255) NUMBERPROCESSED :int = ((0)) NUMBEROFEXCEPTIONS :int = ((0)) LETTERTEMPLATE :varbinary(max) LABELTEMPLATE :varbinary(max)*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint ENDEDON :datetime BUSINESSPROCESSPARAMETERSETID :uniqueidentifier

BUSINESSPROCESSVIEW

«column»*PK ID :uniqueidenti fier = (newid())*FK BUSINESSPROCESSCATALOGID :uniqueidentifier*FK QUERYVIEWCATALOGID :uniqueidenti fier* CAPTION :nvarchar(255) = ('')* JOINFIELD :nvarchar(128) = ('')*FK ADDEDBYID :uniqueidentifier*FK CHANGEDBYID :uniqueidentifier* DATEADDED :datetime = (getdate())* DATECHANGED :datetime = (getdate())* TS :timestamp TSLONG :bigint

USR_INVENTORYPROCESS_c404427d_e0f0_43a4_b122_1cd6514d7254

«column»*PK BUSINESSPROCESSOUTPUT_PKID :int ID :uniqueidenti fier NAME :nvarchar(154) FOODITEMNAME :nvarchar(100) LOWINVENTORYTHRESHOLD :smallint CURRENTINVENTORY :int INVENTORYSHORTAGE :int

Output tables may be created as a result of a business process. The BusinessProcessOutput.TableName field refers to an output table for a given instance of a business process. The content and columns defined within each output table is typically determinedby a QueryViewSpec referenced within the BusinessProcessView table.

USR_INVENTORYPROCESS_6fd84a6f_f20d_457a_95ab_141e338300e7

«column»*PK BUSINESSPROCESSOUTPUT_PKID :int ID :uniqueidenti fier NAME :nvarchar(154) FOODITEMNAME :nvarchar(100) FOODITEMCOUNT :int

0..*

1

0..*

1

0..*

1

0..*1

Figure 53 - The BusinessProcessOutput table contains data describing the output of a particular business process run


8.7 BusinessProcessInstance Table Secures Parameter Sets

Each business process will have one or more sets of parameter data. The parameter data exists within a Business Process Parameter Table that is created for and therefore tailored to a specific business process. The BusinessProcessInstance table supports the securing of a parameter set for a business process to a particular site and/or selected security roles. A parent/child relationship exists between the catalog table and the instance table.

On the page used to create and manage parameter sets for a business process, an action button should exist within the section that contains a data list of the parameter sets. Seleting a parameter set row within the datallist provides the context (parameter set id) for the action button. Clicking the action button opens the Edit Business Process Instance Permissions With Site data form. Once opened, a row will be added to the BusinessProcessInstance table. The BusinessProcessCatalogID field will be populated with the id for the business process as defined by the ID attribute of the BusinessProcessSpec. The BusinessProcessParameterSetID field will be populated via the context value (the column within the data list containing the parameter set id). The SECURITYLEVEL Field can have a value of either 0 - All roles or 1 - Selected Roles.

The SECURITYLEVEL field will default to 0 meaning initially all security roles will have access to run the BP with this parameter set.



EA 8.0 Unregistered Trial Version EA 8.0 Unregistered Trial Version EA 8.0 Unregistered Trial Version EA 8.0 Unregistered Trial Version EA 8.0 Unregistered Trial Version































«column»*PK ID: uniqueidentifier = (newid())* ALLOWSIMULTANEOUSEXECUTION: bi t = ((0))* NAME: nvarchar(60)* DESCRIPTION: nvarchar(1000) = ('')* BUSINESSPROCESSSPECXML: xml*FK RECORDTYPEID: uniqueidentifier PARAMETERTABLENAME: nvarchar(100) = ('')* PARAMETERLABELFIELD: nvarchar(100)* SECURITYUIFOLDER: nvarchar(255) = ('')*FK ADDEDBYID: uniqueidentifier*FK CHANGEDBYID: uniqueidentifier* DATEADDED: datetime = (getdate())* DATECHANGED: datetime = (getdate())* TS: timestamp TSLONG: bigint

BUSINESSPROCESSINSTANCE

«column»*PK ID: uniqueidentifier = (newid())*FK BUSINESSPROCESSCATALOGID: uniqueidenti fier* BUSINESSPROCESSPARAMETERSETID: uniqueidentifier* SECURITYLEVEL: tinyint = ((0)) FK OWNERID: uniqueidentifier*FK ADDEDBYID: uniqueidentifier*FK CHANGEDBYID: uniqueidentifier* DATEADDED: datetime = (getdate())* DATECHANGED: datetime = (getdate())* TS: timestamp TSLONG: bigint FK SITEID: uniqueidentifier

0..*1

Figure 54 - The BusinessProcessInstance table supports the securing of a parameter set

Figure 55 - Once the Edit Business Process Instance Permissions With Site data form is opened a row is added to the BusinessProcessInstance table

9 Queue Processes

Queues are used to set up a series of processes to run automatically and unattended. You can set up and run queues when you have large amounts of data to export, print, commit, import, or send as email. Because you create queues to work with large amounts of data, you can schedule the queue to run during a break in the day or when all your volunteers and employees have left for the day. For your convenience, you can create the queue and schedule a specific date and time to run it. You can also generate Windows Scripting files for use in scripts or with other task automation software.

A typical workflow could include setting up individual processes to refresh your segments and your mailings. These processes can then be implemented as a queue so that the segments are refreshed, then the mailings that use the segments are refreshed. The system administrator builds the processes and updates the system to make them available. If you choose to perform a time and resource intensive process, you may want to run the process when your office is closed for the day. With Queue, you can add all the necessary processes into a single queue, in a logical order of progression, and run them at off-peak dates and times.

For more information on Queue, see the Administration Guide for Blackbaud Enterprise CRM.


http://www.blackbaud.com/files/support/guides/enterprise/administ.pdf

10 Exercise 1 – Adding the Custom Parameter Set Table for the Business Process

Individual parameters are organized into a parameter set. A business process can be designed to accept zero, one or several parameters. The end user can define multiple parameter sets for a given business process.

Before a business process is started, the end user creates one or several parameter sets, selects a parameter set, and starts the business process instance. Using the parameter set for guidance, the business process instance will process the data.

When the business process processing starts, the parameter set values are retrieved and the processing on the data begins in earnest. The parameter set values are stored within a custom database table. See Business Process Parameter Set Table (USR_INVENTORYPROCESS) for details.

Step 1 – Prerequisites Ensure Blackbaud Enterprise CRM is open to the correct environment. If you are participating in instructor led

training, your instructor will direct you to the correct training environment which fulfills these prerequisite.

The examples in this document extend the capabilities of the food bank functional area which has been built to illustrate the customization and configuration capabilities of an Infinity based application. Ensure the features that represent the food bank sub application have been loaded into the database that you are using for this training. If you are working out of your own training software development environment, ensure the features that represent the food bank sub application have been loaded into the Infinity catalog system/database that you are using for this training

The FoodBank.Package.xml file within the project lists the required specs that should be loaded prior to starting the exercises outlined within this document . The features which make up the food bank sub application can be found within the Blackbaud.CustomFx.FoodBank.Catalog visual studio project within the source code.

Ensure you have several food bank organization records of varying food bank types added into the database. At least one food bank should be associated with a food bank type equal to “Ecumenical” or something similar. See the “Add Food Bank” task within the Food Bank Functional Area to add a new food bank to the system, if needed.

Each food bank should contain multiple food bank transactions of type “Receive” and “Distribute”.

Step 2 – Create an InventoryProcess Folder within the Catalog Project Open your Blackbaud.CustomFx.FoodBank.Catalog project. Check with your instructor for the correct

location of the visual studio solution.

Within your Visual Studio Blackbaud.CustomFx.FoodBank.Catalog project, ensure there is a folder named “InventoryProcess”. We will put our business process specs into this folder. If the folder does not exist, add the folder now by right clicking the visual basic project and select Add\new folder from the popup menu.


Figure - Parameter Sets

TripOt, 10/12/11,

This bullet is for the class room version student and instructor doc.

TripOt, 10/14/11,

This bullet is for the class room version student and instructor doc.

Figure - Add the InventoryProcess folder within the catalog vb project if it does not already exist

Step 2 – Add a TableSpec to the InventoryProcess Folder Right click the InventoryProcess folder and add a new item.

Select Blackbaud AppFx Catalog as the category and Table Spec as the item template. See TableSpecs for more information.

Name the spec file: InventoryProcess.Table.xml

Step 3 – Identify the Table At the top of the spec provide the following values in the TableSpec element to identify the Table in the system.

The Name attribute is the friendly name for the table within the system and defines the record type value that the end user see within the user interface. The Tablename attribute defines the database table name. The Tablename attribute value corresponds with the business process spec’s ParameterTableName attribute value.

<TableSpecxmlns="bb_appfx_table"xmlns:common="bb_appfx_commontypes"


TripOt, 10/12/11,

Add hyperlink to new html help file.

ID="e7d7fadd-b188-4bda-90b0-31b915a66f06"Name="Inventory Process Parameter"Description="Table to store business process parameters for the inventory business

process."Author="Technical Training"Tablename="USR_INVENTORYPROCESS">

Step 4 – Define the Fields within the Table to Support the ParametersAn end user will rely upon an add data form and an edit data form to save the parameter data into this custom database table. Add four fields into the table spec, one for each parameter. The parameter set this TableSpec supports includes:

1. A NAME text field is used to label the parameter set.

2. A DESCRIPTION text field to describe the business process instance

3. The IDSETREGISTERID foreign key field points to a system table named IDSETREGISTER. Each row in the IDSETREGISTER table corresponds to a view or table-valued function that returns a list of Primary Key ID values of a particular record type (database table), such as Constituent or Revenue. For more information see a Using a Selection as a Parameter to Restrict the Row Set.

4. A QueryViewSpec can be used to drive the columns of data also known as the “output format” which is created as a business process. The QUERYVIEWID foreign key field is used to reference to a query view to dictate the output format. For more information see Using a QueryViewSpec as a Parameter for Output Formatting.

While this exercise highlights the best practice of using a QueryViewSpec to help format the output and a selection to help restrict the row set of a business process, keep in mind you are free to develop whatever parameters you see fit to create your custom solution. You are also free to create any type of output your requirements dictate.

To define the columns for the USR_INVENTORYPROCESS table, add the Fields xml element and its child elements below the TableSpec xml element.

<TableSpec xmlns="bb_appfx_table"xmlns:common="bb_appfx_commontypes" ID="e7d7fadd-b188-4bda-90b0-31b915a66f06"Name="Inventory Process Parameter"Description="Table to store business process parameters for the inventory business

process."Author="Technical Training"Tablename="USR_INVENTORYPROCESS"><Fields>

<TextField Name="NAME" Length="100" Required="true" IsUnique="true" Description="The name of the parameter set"/>

<TextField Name="DESCRIPTION" Length="255" Description="Details describing this parameter set"/>

<ForeignKeyField

Name="IDSETREGISTERID" ForeignTable="IDSETREGISTER" Cardinality="ManyToOne"Required="true" OnDelete="CascadeDelete"/>

<ForeignKeyFieldName="QUERYVIEWID"Cardinality="ManyToOne"ForeignTable="QUERYVIEWCATALOG"Required="true"/>

</Fields>

Step 5 – Add a Trigger to Delete Related Records within BUSINESSPROCESSINSTANCEThe BUSINESSPROCESSINSTANCE supports the securing of a parameter set for a business process to a particular site and/or selected security roles. Therefore when a row is delete from our custom parameter set table we need to delete the relate rows within the BUSINESSPROCESSINSTANCE table.

Below the Fields xml element, add the following Triggers xml element to define a trigger which deletes related records within the BUSINESSPROCESSINSTANCE table.

Place the ending TableSpec xml tag below the Triggers xml tag to complete the spec.<TableSpec

xmlns="bb_appfx_table"xmlns:common="bb_appfx_commontypes" ID="e7d7fadd-b188-4bda-90b0-31b915a66f06"Name="Inventory Process Parameter"Description="Table to store business process parameters for the inventory business

process."Author="Technical Training"Tablename="USR_INVENTORYPROCESS"><Fields>

<TextField Name="NAME" Length="100" Required="true" IsUnique="true" Description="The name of the parameter set"/>

<TextField Name="DESCRIPTION" Length="255" Description="Details describing this parameter set"/>

<ForeignKeyField Name="IDSETREGISTERID" ForeignTable="IDSETREGISTER" Cardinality="ManyToOne"Required="true" OnDelete="CascadeDelete"/>

<ForeignKeyFieldName="QUERYVIEWID"Cardinality="ManyToOne"ForeignTable="QUERYVIEWCATALOG"Required="true"/>

</Fields><Triggers>

<Trigger Name="TR_USR_INVENTORYPROCESS_DELETE_BUSINESSPROCESSINSTANCE"

Enabled="true" Description="Used to delete the common business process records associated with this record.">

<CreateTriggerSQL><![CDATA[create trigger TR_USR_INVENTORYPROCESS_DELETE_BUSINESSPROCESSINSTANCE

on dbo.USR_INVENTORYPROCESS after delete not for replication

as begindelete from dbo.BUSINESSPROCESSINSTANCE

where BUSINESSPROCESSPARAMETERSETID in (select ID from deleted) and BUSINESSPROCESSCATALOGID = 'a28d4f17-53fe-48d9-85bc-37e12884dc00';

end ]]></CreateTriggerSQL>

</Trigger></Triggers>

</TableSpec>

Save and load the TableSpec to create the USR_INVENTORYPROCESS parameter set table and associated trigger within the database.


11 Exercise 2 - Adding the Selections for the Food Bank Inventory Business Processes

In this exercise, we will create two ad-hoc queries to create 2 selections which will be used as option for the “Selection” parameter.

Data processing for a business process occurs within a .NET CLR class that exists within an assembly which is deployed on the Infinity web server. This code runs within the web services layer. Within this CLR class file, the parameter set values are retrieved and the processing on the data begins in earnest. How the processing occurs is up to you and the output data format is completely open. See Processing the Data and Business Process Logic for more information.

Selections can be used as a parameter to restrict the number of rows processedOften business processes will require a reference to what’s a known as a “selection” which is a set of record id’s for a particular record type. Selections can be created using Blackbaud’s query tool by first creating either an ad-hoc query or smart query and then saving the query results as a selection. A selection contains the ids of the records to be used as input into and processed by a business process in order to restrict the number of rows processed.

Often business processes will require a reference to what’s a known as a selection which is a set of record id’s for a particular record type. Within the food bank inventory business process, the IDSETREGISTERID field points to a system table named IDSETREGISTER. Each row in the IDSETREGISTER table corresponds to a view or table-valued function that returns a list of Primary Key ID values of a particular record type (database table), such as Constituent or Revenue. Selections can be created using Blackbaud’s query tool by first creating either an ad-hoc query or smart query and then saving the query results as a selection. Selection may also be created by other processes. The IDSETREGISTER table is primarily populated through the saving of a selection from the query tool. A selection contains the ids of the records to be used as input into and processed by a business process in order to restrict the number of rows processed.

Note: Selections can be created via Blackbaud’s Query tool. A selection can be used as an input parameter into a business process instance. A selection is a list of record ids used within the business process .net code to restrict the number of rows processed. Restriction of the rows typically occurs within the SQL statement within the .net code with either a SQL JOIN or WHERE clause

See the section titled Business Process Overview for more information.

Step 1 – Configure the “All Food Banks (Static)” Ad-Hoc Query and the Static Selection for the “Selection” parameterBefore we can get to the business of creating the code for the business process, we must create some selections which can be created from Query within Blackbaud Enterprise CRM.

First let’s configure a static selection which contains at least one food bank organization. The number of rows will be a static snapshot of all the rows in the database. The selection will be used to narrow the number of food bank organizations processed by the business process.

Navigate to the “Analysis” functional area.


Select the Query task.

Figure 56 - Navigating to the Query task

Once you are on the “Query” page, select the “Queries” tab followed by selecting “Add\Ad-hoc query” action above the data list. See below.

Figure 57 - Adding an Ad-hoc query

A screen will appear that asks you to select a source view. Filter by the “Constituent” record type followed by selecting the source view named “Constituents”. See below. After you have selected the source view, press OK.


Figure 58 - Selecting a source view

See Query and Selections sections for more information on these topics.

The Ad-hoc query window will appear. Select the Food Bank node within the Field Explorer on the right hand side of the query window. (Note the Food Bank node will only appear if you have loaded the appropriate food bank specs into the Infinity catalog system. See prerequisites at the beginning of this exercise.)

Next we want to limit the results to only those constituents that are also food banks. Drag the System record ID system field from the middle column over to the Filters pane.


TripOt, 10/12/11,

This needs to be linked to new materials on Query and Selections

Figure 59 - Filtering by the food bank system record id

The Apply Criteria to System record ID screen will appear which allows you to filter the results of the query.

Figure 60 - Only need to see the food banks.

Keep the constituent Name field within the Output Fields pane. See below.


Figure 61 - The completed ad-hoc query

Run the query and view the results by selecting the Results tab. Your results will depend on the number of food banks within your database. If you have no results, add some food banks into the database by navigating to the Food bank functional area, selecting the Add a Food Bank task.

Figure 62 - Query results

Save the query by selecting File\Save from the ad-hoc query window. The Save Query As dialog window will appear.

Enter the following values for the Name/Description tab


Figure 63 - Save Query As

Select the Create selection tab and enter the following values. Choose to create a static selection. Press OK to save the query and the selection.


Figure 64 - Create the Selection

Close the ad-hoc query window. Back on the Query page, verify the new query within the Queries tab. Verify the new selection within the Selections tab.

Figure 65 - Query Page's Queries tab displays the new ad-hoc query used to create the static selection


Figure 66 - Query Page's Selections tab displays the new static selection created from the ad-hoc query

Step 2 – Create a SQLFunctionSpec to Generate a Dynamic SelectionSelections can be created using queries as in the previous step but you can also create a built-in selection by defining a SQLFunctionSpec. The SQLFunctionSpec is used to define a table valued user defined function. A child CreateSelection xml element within the SQLFunctionSpec indicates the function should be registered within the IDSETREGISTER table when the spec is loaded. The function defined within the SQLFunctionSpec must return a single column named or aliased as “ID”.

Create a new SQLFunctionSpec within the InventoryProcess folder.

Name the xml file: USR_UFN_FOODBANKSELECTION.xml

Review the xml for the SQLFunctionSpec below. Note the ID field being returned. Note the CreateSelection child tag. Replace the xml within the newly created SQLFunctionSpec with the xml below.

Save and load the SQLFunctionSpec<SQLFunctionSpec

xmlns="bb_appfx_sqlfunction"xmlns:common="bb_appfx_commontypes" ID="b7be3134-cf13-4467-8315-2a064406aa32"Name="USR_UFN_FOODBANKSELECTION"Description="SQL function to return all food banks as a selection."Author="Technical Training"DBFunctionName="USR_UFN_FOODBANKSELECTION">



<CreateFunctionSQL><![CDATA[

create function dbo.USR_UFN_FOODBANKSELECTION()returns tableas return

selectCONSTITUENTID as ID

fromdbo.USR_FOODBANK]]>


TripOt, 10/12/11,

Link out to SQLFunctionSpec within HTML help

</CreateFunctionSQL>

<CreateSelection

SelectionID="6862D349-D660-414B-9912-EE487EB47EC0" SelectionName="All Food Banks (Dynamic)" RecordTypeName="Constituent" Description="All constituents who are food banks."/>

</SQLFunctionSpec>

Let’s view the new selection on the Query page. To navigate to the Query page go to the Analysis functional area followed by selecting the Query task. Once on the Query page, select the Selections tab.

Figure 67 - The Selection Created Using the SQLFunctionSpec is Visible within the Selections Tab

Step 3 – Configure the “Ecumenical Food Banks” Ad-Hoc Query and a SelectionLet’s configure a third ad-hoc query and associated selection that narrows the food banks to those of a specific food bank type such as “Ecumenical”. This step is similar to step 2 above.

Navigate to the Analysis functional area and select the Query task which is used to open the Query page which is used to create and manage queries.

With the Query page open, select the Queries tab followed by selecting the Add/Ad-hoc query action. This will begin the process of adding another Ad-hoc query.

Base the ad-hoc query off of the Constituents source view as we did in the previous step.

With the New Ad-hoc Query window open, select the Food Bank node within the Field Explorer.

Within the middle pane, drag the Type field into the Filters pane and select a value for the food bank type, such as Ecumenical. See below.

Figure 68 - Limit the second ad-hoc query to just those food bank records of a specific food bank type


After the filter has been defined, select the Results tab and ensure you have rows returned.

Select File\Save to save the query and a selection

Figure 69 - Saving the Query

Figure 70 - Saving a static selection


12 Exercise 3 – Building the Processing Logic for the Food Bank Inventory Business Process

Before a business process is started, the parameter values are created and gathered into a parameter set which is saved to a custom parameter table. When the business process is started the ID of the parameter set is passed to the processing logic. The processing logic for a business process occurs within a .NET CLR class that exists within an assembly which is deployed on the Infinity web server. This code runs within the web services layer. Within this CLR class file, the parameter set values are retrieved and the processing on the data begins in earnest. How the processing occurs is up to you and the output data format is completely open.

We will build a server side processing logic for a custom business process within this exercise. The logic will utilize 4 parameter values as defined by a configured parameter set.

Figure 71 - A parameter set is defined and passed to a business process which creates an output such as a database table.

In this exercise, we will also utilize two QueryViewSpecs to use as choices for the “Output Format” parameter. We also create two ad-hoc queries to create 2 selections which will be used as option for the “Selection” parameter.

A QueryViewSpec can be used as a parameter to define the output format and help define the processing logicA common practice is to use a QueryViewSpec to define the output format/columns. A reference to the QueryViewSpec /output format can be passed to the business process instance as a parameter within the parameter set. Different parameter sets can contain references to different QueryViewSpec s which will in turn affect how the data is processed and which columns will appear within the final output.

Step 1 – Review the Business Process Logic Before building the code read the sections on Business Process Overview, Business Process Parameters, and

Building the Business Process Processing Logic.

Step 2 – Add the BusinessProcessSpec and associated vb class to the catalog project Within your Visual Studio catalog project, right click the InventoryProcess folder and select Add\New Item…

from the popup menu.

Within the Add New Item dialog window, select the Blackbaud AppFx Catalog category followed by selecting the Business Process Spec item template.

Name the xml file: InventoryProcess.BusinessProcess.xml and press the Add button. See below.


Figure 72 - Adding a new BP Spec

Two files are added to the project. One is a visual basic (.vb) file containing a class. The other is the spec file containing the BusinessProcessSpec.

Figure 73 - The Business Process Spec item template creates two files

Step 2 – Inspect the ProcessorComponent XML Element Open and inspect the BusinessProcessSpec. A BusinessProcessSpec is used to reference the .NET class. The

ProcessorComponent tag references the assembly name and a fully qualified class name that contains the processing logic. The fully qualified class name consists of the class name (InventoryProcessBusinessProcess) appended to the assembly name (Blackbaud.CustomFx.FoodBank.Catalog).

<BusinessProcessSpecxmlns="bb_appfx_businessprocess"xmlns:common="bb_appfx_commontypes"ID="069c24cc-1202-4f55-b701-f35e2f8b720c"Name="InventoryProcess Business Process"Description="REPLACE_WITH_DESCRIPTION"


Author="SALESDEMO\TechTrainUser10"GeneratesOutput="false"ParameterTableName="REPLACE_WITH_PARAMETERTABLENAME"RecordType="REPLACE_WITH_RECORDTYPE"common:SecurityUIFolder="REPLACE_WITH_SECURITYUIFOLDER">

<ProcessorComponent AssemblyName="Blackbaud.CustomFx.FoodBank.Catalog.dll" ClassName="Blackbaud.CustomFx.FoodBank.Catalog.InventoryProcessBusinessProcess" /> <common:FormMetaData>

<common:FormFields><common:FormField Caption="REPLACE_WITH_CAPTION"

DataType="REPLACE_WITH_DATATYPE" Description="REPLACE_WITH_DESCRIPTION" FieldID="REPLACE_WITH_FIELDID" />

</common:FormFields></common:FormMetaData>

</BusinessProcessSpec>

Figure 74 - Sample BusinessProcessSpec

Your business process processing will occur within a .NET class that inherits from Blackbaud’s AppCatalog.AppBusinessProcess class. Overriding the Validate() sub within this class enables you to retrieve the parameter set values for the instance. Overriding the StartFunctionBusinessProcess() function enables you to write code that processes the data and produce the output. StartFunctionBusinessProcess() will send back an object of type Blackbaud.AppFx.Server.AppCatalog.AppBusinessProcessResult which provides the Infinity platform with the number of record successfully process and the number of exceptions, if any.

For more information see Business Process Spec and Business Process Logic.

Step 3 – Modify the BusinessProcessSpec XML element Modify the values for the following attributes within the BusinessProcessSpec xml element. Use the example

below as a guide.

o Name

o Description

o Author

o GeneratesOutput

o ParameterTableName

o Record Type

o SecurityUIFolder

<BusinessProcessSpecxmlns="bb_appfx_businessprocess"xmlns:common="bb_appfx_commontypes"ID="a28d4f17-53fe-48d9-85bc-37e12884dc00"Name="Inventory Process Business Process"Description="Business process to get the inventory report for food banks."Author="Technical Training"GeneratesOutput="true"


ParameterTableName="USR_INVENTORYPROCESS"RecordType="Inventory Process Parameter" common:SecurityUIFolder="Constituent\Food Bank\Inventory">

<ProcessorComponent AssemblyName="Blackbaud.CustomFx.FoodBank.Catalog"

ClassName="Blackbaud.CustomFx.FoodBank.Catalog.InventoryProcessBusinessProcess">

…

Step 4 – Add the USR_USP_INVENTORYPROCESS_GETPARAMETERS Stored ProcedureWhen our business process logic is started, the parameters for the designated parameter set id will be retrieved from the custom business process parameter set table that we created in a previous exercise. In this step we will add a stored procedure that accepts a designated primary key value from the custom parameter set table (USR_INVENTORYPROCESS). This value represents a chosen parameter set which will be utilized by the business processing logic. The stored procedure will retrieve the IDSETREGISTERSETID which represents a selection used to limit the rows which require processing and the OUTPUTVIEWID which represents the output format or the columns created by the business process.

See SQLStoredProcedureSpec to Retrieve the Parametes within the Processing Code and Business Process: StartBusinessProcess() for more information on how the parameter set data is retrieved and utilized within the processing logic.

Let’s add a new SQLStoredProcedureSpec to our food bank catalog project.

Right click the InventoryProcess folder and select Add\New Item… from the context menu.

Select Blackbaud AppFx Catalog as the category on the left side of the Add New Item dialog window followed by selecting SQL Stored Procedure Spec as the template item.

Name the xml spec file: USR_USP_INVENTORYPROCESS_GETPARAMETERS.xml

The catalog item template SQL Stored Procedure Spec provides some default xml to help you define the stored procedure. Let’s replace this xml with the xml below:<SQLStoredProcedureSpecxmlns="bb_appfx_sqlstoredprocedure"xmlns:common="bb_appfx_commontypes" ID="1d8dac58-3685-4216-b515-ac150d08def3"


TripOt, 10/13/11,

Add link to new html help stuff.

Name="USR_USP_INVENTORYPROCESS_GETPARAMETERS"Description="Defines a stored procedure that is used

within the business process .NET CLR code to retrieve the instance parameters for a given id. See InventoryProcessBusinessProcess.vb"Author="Technical Training"SPName="USR_USP_INVENTORYPROCESS_GETPARAMETERS">



<CreateProcedureSQL><![CDATA[

create procedure dbo.USR_USP_INVENTORYPROCESS_GETPARAMETERS(@ID uniqueidentifier)asbeginselect

IP.IDSETREGISTERID,BPVIEW.ID as OUTPUTVIEWID

fromdbo.USR_INVENTORYPROCESS IP

joindbo.BUSINESSPROCESSVIEW BPVIEW on IP.QUERYVIEWID = BPVIEW.QUERYVIEWCATALOGID

whereIP.ID = @ID

end]]>

</CreateProcedureSQL></SQLStoredProcedureSpec>

Save and load the SQLStoredProcedureSpec

Step 5 – Modify the BusinessProcessSpec and Grant Permission to the Database Objects Used by the Processing LogicLet’s go back and modify the BusinessProcessSpec and add some xml which will grant permission to specific database object for our processing logic.

Modify the ProcessorComponent xml element such that it has a beginning and ending tag.

See the yellow highlight below.

Modify the BusinessProcessSpec by adding the GrantExecuteList xml child element to the ProcessorComponent xml element.

In the green highlight below notice the reference to the stored procedure we created in the previous step.

Modify the BusinessProcessSpec by adding the GrantSelectList xml child element to the ProcessorComponent xml element.

UFN_IDSETREADER_GETRESULTS is a built-in table valued user defined function used to retrieve a list of GUIDS for a given selection ID. Our processing logic will leverage this function within a SQL JOIN clause to narrow the database table rows returned. Review the blue highlight below and add the highlighted select list to the business process spec.

<BusinessProcessSpecxmlns="bb_appfx_businessprocess"xmlns:common="bb_appfx_commontypes"

ID="a28d4f17-53fe-48d9-85bc-37e12884dc00"Name="Inventory Process Business Process"Description="Business process to get the inventory report for food banks."Author="Technical Training"GeneratesOutput="true"ParameterTableName="USR_INVENTORYPROCESS"RecordType="Inventory Process Parameter"common:SecurityUIFolder="Constituent\Food Bank\Inventory">

<ProcessorComponent AssemblyName="Blackbaud.CustomFx.FoodBank.Catalog" ClassName="Blackbaud.CustomFx.FoodBank.Catalog.InventoryProcessBusinessProcess">

 <common:GrantExecuteList> <common:GrantExecute>USR_USP_INVENTORYPROCESS_GETPARAMETERS</common:GrantExecute> </common:GrantExecuteList>

<common:GrantSelectList> <common:GrantSelect>USR_FOODBANK</common:GrantSelect>

<common:GrantSelect>UFN_IDSETREADER_GETRESULTS</common:GrantSelect> <common:GrantSelect>USR_UFN_FOODBANKSELECTION</common:GrantSelect> </common:GrantSelectList> </ProcessorComponent>

Step 6 – Remove the FormMetaData Remove the default FormMetaData element and child xml elements from the BusinessProcessSpec.

This element is used to define a pre-process edit data form to be used when the business process does not have parameters saved to a database table. This is a mechanism to display a form fields in the user interface after the business process has been started but prior to processing shifting to the business processor code on the web server. We will not need the FormMetaData xml element so we are removing this tag. See FormMetaData for more information on this element and how to Managing Parameter Sets and Starting a Business Process with a Pre-Process Edit Data Form.

Step 7 – Add the BusinessProcessOutputHeader xml elementThe BusinessProcessOutputHeader xml element describes how to designate a view to generate an output header file for a business process.

Add the following BusinessProcessOutputHeader xml element to the spec. See below.

Note the value of the OutputViewMetaTag attribute.

Do you see how the value is equal to “Inventory”?


Step 8 – Save and Load the BusinessProcessSpecLoading the spec adds a row to the business process spec catalog table

Step 9 – Filter the Tables for our new Parameter Set Table Open SQL Server Management Studio, navigate to the appropriate database, and filter the

Tables folder to the name of our parameter set table: USR_INVENTORYPROCESS


Note the tables that were created. Besides the audit tables, you will notice the USR_INVENTORYPROCESS, USR_INVENTORYPROCESSEXPORTFORMAT, and USR_INVENTORYPROCESSSTATUS tables. USR_INVENTORYPROCESSEXPORTFORMAT is the custom export format table. The BUSINESSPROCESSEXPORTFORMAT table defines the format in which data from a business process's output will be displayed when exported. The BusinessProcessSpec’s GeneratesOuput attribute indicates whether the process generates output via this database table which can be exported later.

USR_INVENTORYPROCESSSTATUS is the custom status table. This table serves as a join table to the BUSINESSPROCESSSTATUS table for the business process parameter table (USR_INVENTORYPROCESS).

Step 10 – Review the ERD for the Business Process Take a few minutes and review the entity relationship diagram for the business process.

Step 11 – Add two QueryViewSpecs used for the “Output Format” parameterA best practice is to use a QueryViewSpec to define the output format of a business process. Typically, before starting an instance, an end user may select a reference to a specific QueryViewSpec as one of the input parameters into a process. Different parameter sets can contain references to different QueryViewSpecs which will in turn affect how the data is processed and which columns will appear within the final output. In short, a QueryViewSpec can be used to drive the columns of data created by a business process.

The best practice to define the output columns is to utilize a reference to an “Output Format” QueryViewSpec as a parameter value into the business process instance. The QueryViewSpec is used to define a database view.

See the following sections for more information: Business Process Parameters and Using a QueryViewSpec as a Parameter for Output Formatting

Open the InventoryProcess folder and ensure the existence of two Query xml files.


TripOt, 10/14/11,

I have a BP ERD that need to go in our new references sections. It should be on the technical training site for Meebee. Put a link to it here.

If these files do not exist, add them from the food bank source code. After adding the files, be sure to mark them as embedded resources by right clicking each file, viewing the properties, and modifying the Build Action property value from “Content” to “Embedded Resource”. These two QueryViewSpecs have a dependency on the custom business process spec. InventoryProcessCurrentInventoryOutput.Query.xml

o InventoryProcessLowInventoryOutput.Query.xml

Open up each QueryViewSpec and begin to investigate its contents.

Notice the following xml elements and attributes within the specs:

o PrimaryKeyField attribute

o MetaTags element

o ViewImplementation element and its contents

o OutputFields element and child elements

o BusinessProcessOutput element

For more information on how a QueryViewSpec can be used to participate in the BP processing logic, see the section Using a QueryViewspec as a Parameter for Output Formatting and Typical Duties for your Sub Class.

Review the MetaTags element in both QueryViewSpecs

Look closely at the value within the MetaTags xml element in both specs. Compare this value against the OutputViewMetaTag attribute within the BusinessProcessOutputHeader element near the bottom of the BusinessProcessSpec.

Did you notice the value for the BusinessProcessID attribute within the BusinessProcessOuput xml element? It has a dependency on the ID for the BusinessProcessSpec. Therefore, we can deduce that the BusinessProcessSpec will need to be loaded first prior to loading these QueryViewSpecs.

Use LoadSpec to load each QueryViewSpec

Step 12 – Add the code for the business process logic to the vb class file Copy the code below and replace the existing code within into the InventoryProcess.BusinessProcess.vb class. Imports System.TextImports System.Data.SqlClientImports Blackbaud.AppFx.Server

Public NotInheritable Class InventoryProcessBusinessProcess Inherits AppCatalog.AppBusinessProcess Private _parameters As InventoryParameters = Nothing

'Validate gets called first and if all goes well, it gets our parameters too. Public Overrides Sub Validate() MyBase.Validate() ' Get our business process parameters _parameters = New InventoryParameters(RequestArgs.ParameterSetID, Me.RequestContext) If _parameters Is Nothing Then Throw New Exception("No parameters found with the given parameter") End If


End Sub

' This is a class used for the inventory process instance parameters. Private Class InventoryParameters Public ReadOnly OUTPUTVIEWID As Guid = Guid.Empty Public ReadOnly IDSETID As Guid = Guid.Empty

Public Sub New(ByVal parameterSetID As Guid, ByRef requestContext As RequestContext) Using con As SqlConnection = New SqlConnection(requestContext.AppDBConnectionString) Using command As SqlCommand = con.CreateCommand() Try command.CommandText = "USR_USP_INVENTORYPROCESS_GETPARAMETERS"

command.CommandType = CommandType.StoredProcedure command.Parameters.AddWithValue("@ID", parameterSetID) con.Open() Using reader As SqlDataReader = command.ExecuteReader() reader.Read() Me.IDSETID = reader.GetGuid(reader.GetOrdinal("IDSETREGISTERID")) Me.OUTPUTVIEWID = reader.GetGuid(reader.GetOrdinal("OUTPUTVIEWID")) reader.Close() End Using con.Close() Catch Throw New Exception("Unable to get parameter set found for the given Id") End Try End Using End Using End Sub End Class

' The core of the buisness process Public Overrides Function StartBusinessProcess() As Blackbaud.AppFx.Server.AppCatalog.AppBusinessProcessResult ' Our return object Dim result As New AppCatalog.AppBusinessProcessResult()

' Declare some constants for the output table Const OUTPUT_TABLE_PREFIX As String = "USR_INVENTORYPROCESS" Const OUTPUT_TABLE_KEY As String = "OUTPUT"

' Declare local variables Dim outputTableName As String = String.Empty Dim exportView As String = String.Empty Dim viewColumns() As AppCatalog.TableColumn = Nothing Dim inventoryIDField As String = String.Empty

' Get the export view's name and the field to join on With Me.OutputView(_parameters.OUTPUTVIEWID) exportView = .ExportViewName inventoryIDField = .JoinField


End With

' This will create the output table called 'USR_INVENTORYPROCESS_<guid> and get the viewColumns outputTableName = Me.CreateOutputTableFromView(exportView, OUTPUT_TABLE_PREFIX, OUTPUT_TABLE_KEY, viewColumns)

' Now we need to populate the output table Dim sql As New StringBuilder()

With sql .AppendFormat("insert into dbo.[{0}]", outputTableName) .AppendFormat("({0})", Me.CreateFieldsList(viewColumns)) ' Now the select part of the query .AppendLine("select ")

' OUTPUTVIEW here is the table name field prefix i.e. TABLE.FIELD .AppendFormat("{0} ", Me.CreateFieldsList(viewColumns, "OUTPUTVIEW")) .AppendLine("from dbo.USR_FOODBANK as FB") .AppendFormat("join dbo.[{0}] as OUTPUTVIEW on FB.[ID] = OUTPUTVIEW.[{1}]", exportView, inventoryIDField) ' Now we add the join clause to filter based on our selection parameter ' Note: I used a standard product UFN to read the GUIDs from a IDSET given an ID .AppendFormat("join dbo.[UFN_IDSETREADER_GETRESULTS]('{0}') IDSET on OUTPUTVIEW.ID = IDSET.ID", _parameters.IDSETID.ToString()) End With ' Execute the command to populate the table Using con As SqlConnection = New SqlConnection(Me.RequestContext.AppDBConnectionString) con.Open() Using command As SqlCommand = con.CreateCommand() With command .CommandText = sql.ToString() .CommandTimeout = Me.ProcessCommandTimeout .ExecuteNonQuery() End With End Using ' Now get the record count for the BP status Using command As SqlCommand = con.CreateCommand() With command .CommandText = String.Format("select count(*) from dbo.[{0}]", outputTableName) .CommandTimeout = Me.ProcessCommandTimeout result.NumberSuccessfullyProcessed = CType(.ExecuteScalar(), Integer) End With End Using con.Close() End Using Return result End FunctionEnd Class

Step 13 – Build and Deploy the Blackbaud.CustomFx.FoodBank.Catalog assembly


With Infinity development, a catalog is an assembly (.dll file) that contains embedded catalog items (specs) as resources. The catalog assembly also holds our vb file that contains our business process class.

Very Important: The vb class file’s Build Action property should be marked as ‘Compile’ while each xml spec file’s Build Action property within each spec XML file should be marked as ‘Embedded Resource’.

Copy the assembly (.dll file) to the Infinity application’s ..\bbappfx\vroot\bin\custom folder.


13 Exercise 4 – Adding Parameters Sets

In the previous 3 exercises, we created a parameter set table, the BusinessProcessSpec, processing logic, two QueryViewSpecs to use as potential parameter values for the Output Format parameter, and three selections to use as potential values for the Selection parameter. In this exercise we will add a couple of parameter set rows to the parameter set table via an Add Data Form.

Step 1 – Load custom add data form Ensure the Blackbaud.CustomFx.FoodBank visual studio solution within Microsoft Visual Studio is open.

Right click the InventoryProcess folder and select New\Existing Item… from the context menu.

Using the table below, add the following xml file from the source code to your food bank catalog assembly project. The file represents an Add Data Form adds a record into the parameter set table.

If you are participating in instructor led training, check with your instructor or facilitator for the appropriate location for the specs.

Feature Name Spec XML File Name Description

Inventory Process Business Process Add Form

InventoryProcess.Add.xml Data form for adding inventory process business parameters. Adds an inventory process parameter set into the custom USR_INVENTORYPROCESS table.

Right click the spec file and view its properties. Change the Build Action property value to ‘Embedded Resource’ to mark the file as an embedded resource.

Save and load the add data form

Step 2 – Review the FormFields for the Add Data FormLet’s open up the InventoryProcess.Add.xml file and view the xml for the spec.

Review the form fields within the FormMetaData xml element

Pay close attention to the form field for the IDSETREGISTERID which allows the end user to search for a selection to restrict the rows processed.

Also notice the QUERYVIEWID form field which utilizes a simple data list with 2 parameters. It will give a list of business process views (output formats) that have a record type of "Food Bank" and have a meta tag of "Inventory".


Step 3 – Configure a New Task to Open the Add Data Form Navigate to the Administration > Application > Shell Design Page

Figure 75 - Navigate to the Shell Design task

Select the Tasks tab and click the Add action button.

Complete the task as shown in the dialog below.

This will create a new task within the food bank functional area that opens our new add data form.


Once the task is created, refresh shell navigation to view the task within the food bank functional area

Click the task to open the add data form and create a parameter set. Repeat to add a second record


Open SQL Server Management Studio and create a SQL query to view the rows within the USR_INVENTORYPROCESS table.


14 Exercise 5 - Building the Status Page

A business process instance status page or also known as the “status page” is primarily used to view the recent and historical statuses for a business process and its associated parameter set. After a business process is started manually, the task or action typically will redirect the user to the status page. A user should also have the ability to start a new instance of the BP with the chosen parameter set on the status page.

Let’s build a status page that fulfills the use case diagram and the requirements described in the Business Process Instance Status Page section. We will start by loading some custom features from the lab answers source code project. These custom features provide the basis for fulfilling all but one of the green use case ovals above. If you are unsure where to locate the lab answers within your training environment, ask your instructor. Otherwise, you can grab the food bank source code from the Blackbaud Developer Network.

Step 1 – Load custom features Ensure the Blackbaud.CustomFx.FoodBank visual studio solution within Microsoft Visual Studio is open.

Right click the InventoryProcess folder and select New\Existing Item… from the context menu.

Using the table below, add the following xml files from the source code to your food bank catalog assembly project. Add the files to the new ‘InventoryProcess’ folder. Each file represents an individual Infinity feature that will be leveraged on our new status page. We will reference these features as we build the status page in the upcoming steps for this exercise.

If you are participating in instructor led training, check with your instructor or facilitator for the appropriate location for the specs.

Feature Name Spec XML File Name Description

Inventory Process Business Process Status View Form

InventoryProcessPageExpression.View.xml Expression Data Form used by the status page. Provides data for use on the inventory process business process status page.

Inventory Business Process View Data Form

InventoryProcess.View.xml Summary View Data Form used by the status page to view BP Parameter Set Information.

Inventory Process Business Process Status List

InventoryProcessStatus.DataList.xml Returns a status list for the inventory process business process. Referenced within the page’s History tab

Inventory Process Business Process Edit Form

InventoryProcess.Edit.xml Data form for editing inventory process business process parameters. Edits the parameter set for the business process.

Inventory Process Business: Delete

InventoryProcessDelete.RecordOperation.xml Deletes the specified inventory process business process.

Table 2 - Custom features referenced within the status page

Mark each file as an embedded resource within the catalog project


http://www.bbdevnetwork.com/content/food-bank-source-code

Use the load spec utility to load each spec into the appropriate Infinity database. If you are participating in instructor led training, check with your instructor or facilitator for the appropriate environment database.

In future steps we will utilize these features along with out of the box features that ship with Blackbaud Enterprise CRM to build a status page.

Step 2 – Configure a new page and set the context, expression view form, caption, and summary sectionLet’s build a new page for our status page. Our page will require context value of “Inventory Process Parameter”. A page that is configured with a context record type requires that an ID value of that same record type is passed to the page when the page is opened. Once passed to the page, this value is stored within a property on the page named PageContext. By configuring the page while in design mode, an administrator can use the value for the PageContext property to pass the context value to other features and actions referenced on the page. For more information on pages see the article titled Pages .

As a reference we will review the metadata for a completed example of the status page that we will ultimately build with this exercise. Below, we see the context record type is equal to “Inventory Process Parameter” which is a reference to the primary key value of the custom USR_INVENTORYPROCESS table used to hold the parameter sets for our custom business process. See the section titled Tables for more information on the entity relationship diagram supporting business processes.

Figure 76 - Metadata displaying the context record type of the completed status page


TripOt, 10/13/11,

ditto

TripOt, 10/13/11,

Hyperlink to correct location in new html help stuff.

http://www.bbdevnetwork.com/content/pages

Within the page the value for PageContext, which is the primary key value of the custom USR_INVENTORYPROCESS table used to hold the parameter sets for our custom business process, is passed to a myriad of features referenced within the page. A few examples are the summary view data form, view data form within the Recent Status tab, and the expression data form on the page.

Let’s begin the process of configuring a new page:

Navigate to the Administration > Application > Shell Design Page


Select the Pages tab

Figure 78 - Adding a new page

Selecting the Add action above the Pages data list opens the property sheet used to create a new page. See above.

Enter the initial properties for the page using the figure below as a guide.

o Note the value for the RecordType property (Context record type). This value equates to the Name attribute within the TableSpec used to create the USR_INVENTORYPROCESS table.

o Note the reference to the expression data form named “Inventory Process Business Process Status View Form” within the ExpressionDataForms property. You must configure the expression data form prior to writing an expression that leverages a form field on the expression data form.

For more information about this expression view data form see Expression Data Form Drives Expressions on the Status Page


o Note the Caption property and how it leverages the Name form field value from the Expression Data Form

o Note the reference to the summary view data form named “Inventory Business Process View Data Form” within the SummarySection property.

See Summary Section for more information

o You should change the name of the author to “Technical Training” after you reverse engineer the page spec back into your visual studio project.

Figure 79 - New status page properties in Shell Design

Save the Page

Using SQL Server Management Studio, write a query to retrieve the rows from the USR_INVENTORYPROCESS table.

This table represents the parameter sets for the business process.

Copy one primary key value from the table to the clipboard.

In the next step, we will need this value when we test the page since our page requires a context value of this record type.

Step 3 - Test the page Ensure you are on the Shell Design page.

Click the Pages tab. Find the page we just created. Note the rows are grouped by Record Type. The record type for our page is Inventory Process Parameter. See below


Select the row and click the Test Page action which is located just above the data list. See below.

Provide the context value for the page

You will be presented with a simple dialog screen which prompts you for the page’s context value. Since our page has been configured to accept a context value of a record type of Inventory Process Parameter, you will need to paste the GUID from the USR_INVENTORYPROCESS table which represents the Parameter Set ID for the business process.

Review the page

The page should open with the appropriate parameter set displayed at the top of the page within the page’s summary section.

Place the page in Design mode

Select Tools\Design Mode from the main menu. With the page in design mode, you can continue the configuration of the page.


Step 4 – Configure 3 tabs on the pageOur new page will contain 3 tabs: Recent Status, History, and Job Schedules.

Recent Status TabThis tab will contain one section to hold the “Business Process Parameter Set Recent Status View Form” that ships with Blackbaud Enterprise CRM. This data form displays the most recent status information for the given business process parameter set. This section will contain no actions.

With the page in design mode, select the Edit tabs button (red rectangle) to open the tabs property sheet.

On the Tabs Property Sheet, select the add button and provide a value of “Recent Status” for the caption property.

Select the Sections property on the tabs property sheet. Select the ellipsis button to open the Sections Property sheet to begin the process of adding the data form.

Figure 80 - Configuring the Recent Status Tab

Using the figure below as a guide, Select the Add button to add a new section and provide the values for the SectionType, DataForm, and ContextType properties.


Figure 81 - Configuring the Recent Status Section within the Recent Status Tab

Select OK on the Sections Property Sheet to accept the settings.

Select Save on the Tabs Property Sheet to save the new tab.

History TabThis tab will contain one section that displays a custom data list named “Inventory Process Business Process Status List” which returns a status list for the process.

With the page in design mode, select the Edit tabs button again to open the tabs property sheet.

On the Tabs Property Sheet, select the Add button and provide a value of “History” for the caption property on the new tab.

On the Tabs Property Sheet, select the Sections property. Select the ellipsis button to open the Sections Property sheet to begin the process of adding a data list to the new section.

On the section dialog, select the Add button to begin the process of adding a new section to the tab. Using the figure below as a guide, provide the values for the Caption, SectionType, DataList, and ContextType, Style, and Groups properties.


Figure 82 – Configuring the History Section within the History Tab

With the Sections Property sheet open, select the ellipsis button next to the Actions property to begin the process of adding a Delete action. See below.

Figure 83 - Configuring a Delete Action for the History Section


On the Actions property sheet (see below), select the Add button and provide the following values for the Caption, Image, ActionType, Post-Action Event, Record Operation, ContextType, and SectionField.

Figure 84 - Adding a Delete Action

Select OK on the Actions Property Sheet to accept the settings for the action.

Select OK on the Sections Property Sheet to accept the settings for the section.


Job Schedules Tab With the page in design mode, select the Edit tabs button one more time to open the tabs property sheet.

On the Tabs Property Sheet, select the Add button and provide a value of “Job Schedules” for the caption property on the new tab.

On the Tabs Property Sheet, select the Sections property. Select the ellipsis button to open the Sections Property sheet to begin the process of adding a data list to the new section.

On the Sections property sheet, select the Add button to add a new section into the tab. Using the figure below as a guide, provide the values for the Caption, SectionType, DataList, and ContextType properties.


Figure 85 – Configuring the Job Schedules Section within the Job Schedules Tab

Configuring the Add, Edit, and Delete Actions for the Job Schedules SectionAdd Action

With the Job schedules section property sheet open, select the ellipsis button next to the Actions property to begin the process of adding an Add action. See below.

Figure 86 - Configuring a Add Action for the Job Schedules Section

Add an Add action to the section. With the Actions property sheet open (see below), provide the following values for the Caption, Image, ActionType, Data Form, ContextType, and Expression properties:


The value for the expression used to derive the context value for the Add action can be found below:IIf(String.IsNullOrEmpty(Page.Fields!PARAMETERSETID.ToString()), "", String.Concat("Exchange Contact Synchronization Process|B531B950-2534-4E95-B104-805DB1328806|", Page.Fields!PARAMETERSETID.ToString())).ToString()

Edit Action With the Actions property sheet open add an Edit action to the section (see below). Provide the following values

for the Caption, Image, ActionType, Data Form, ContextType, SectionField,and Post-ActionEvent properties:


Delete Action With the Actions property sheet open add a Delete action to the section (see below). With the Actions property

sheet open, provide the following values for the Caption, Image, ActionType, Post-Action Event, Record Operation, ContextType, and SectionField properties:

Select OK on the Actions Property Sheet to accept the settings for the 3 actions.

Select OK on the Sections Property Sheet to accept the settings for the section.


Step 4 – Configure the “Tasks” action group with new actions on the page. Configuring the “Edit Process” ActionYou will now add 6 actions to the “Tasks” action group which resides on the far left hand side of your new page.

1. Edit Process

2. Generate WSF

3. Create job schedule

4. Create task

5. Delete process


6. Start Process

Create a new action that opens the “Inventory Process Business Process Edit Form”. This is a custom edit data form that allows an end user to edit the parameter set associated with the business process. The data form was loaded previous step 1. The action should pass the page context to the data form.

Figure 87 - The Inventory Process Business Process Edit Form

With the page in design mode, select the Edit Action Groups button at the top of the page. See below.

Select the Add button to add a new Task action group. Provide the following properties. See below:

Select the ellipsis button for the new Tasks action group. See below:


Figure 88 - Adding an Action to the "Tasks" Action Group

With the Actions dialog open, select the Add button to begin the process of adding the property values for the Edit process action. See below.

Provide the following values for the Caption, Image, ActionType, Post-Action Event, Record Operation, ContextType, and SectionField properties:

Figure 89 - Edit process action

Click OK to save the action. Try out the new action.


Step 5 – Configuring the “Generate WSF” ActionSelecting the “Generate WSF” action, creates a Windows Scripting File which can be run once or scheduled using Windows Task Scheduler. For more information see Generate WSF Action.

With the Actions dialog open, select the Add button to begin the process of adding the property values for the Generate WSF action. See below.

Provide the following values for the Caption, Image, ActionType, CustomComponent (see next bullet), Post-Action Event, Record Operation, ContextType, and SectionField properties:

Here is the value for the CustomComponent property: Blackbaud.AppFx.Platform.BusinessProcessClient,Blackbaud.AppFx.Platform.BusinessProcessClient.BusinessProcessGenerateWsfAction

Figure 90 - Generate WSF Properties

Select the StaticParameters property and select the ellipsis button and add the values for the BusinessProcessID parameter.

The BusinessProcessID references the ID attribute of your BusinessProcessSpec. MAKE SURE THE VALUE YOU PROVIDE MATCHES YOUR ID FROM YOUR BUSINESSPROCESSSPEC.


Select the StaticParameters property and select the ellipsis button and add the following values for the BusinessProcessName parameter:


Step 6 – Configuring the “Create Job Schedule” ActionSelecting the “Create Job Schedule” action opens the Business Process Job Add Form which is a data form that ships with Blackbaud Enterprise CRM.

Figure 91 - Creating a SQL Server Agent Job for the business process with a given parameter set

When the data form is saved it will create a SQL Server Agent job using an ActiveX script to run the business process using a specific parameter set. For more information see Create Job Schedule Action.

With the Actions dialog open, select the Add button to begin the process of adding the property values for the “Create Job Schedule” action. (See below)

Provide the following values for the Caption, Image, ToolTipText, ActionType, DataForm, ContextType, Expression (see next bullet for the complete expression), and Post-Action Event action type:

Here is the complete expression value for the Expression property:= IIf(String.IsNullOrEmpty(Page.Fields!PARAMETERSETID.ToString()), "", String.Concat("Exchange Contact Synchronization Process|B531B950-2534-4E95-B104-805DB1328806|", Page.Fields!PARAMETERSETID.ToString())).ToString()


Figure 92 - Create job schedule's action properties

Step 7 – Configuring the “Create task” ActionSelecting the “Create task” action opens the “Run Business Process Task Add” form which ships with Blackbaud Enterprise CRM. This data form looks strikingly similar to a property sheet for a task. At run time, this data form allows the user to create a task that will allow users to run the business process with the current parameter set. For more information on using this action see Create Task Action.


Figure 93 – Clicking the “Create task” action opens the Run Business Process Task Add form

With the Actions dialog open, select the Add button to begin the process of adding the property values for the Create Task action. (See below)

Provide the following values for the Caption, Image, ActionType, DataForm, and ContextType:

Figure 94 – Create Task’s action properties


Step 8 – Configuring the “Delete process” ActionClicking the “Delete process” action within the Tasks action group on our status page will call upon a custom record operation named “Inventory Process Business: Delete” to delete the parameter set for the business process. The record operation will call upon a stored procedure to delete a row from the custom USR_INVENTORYPROCESS table which is used to store the parameter data for a specific business process. For more information see Business Process Parameter Set Table.

Figure 95 - Delete process action

With the Actions dialog open, select the Add button to begin the process of adding the property values for the Delete Process action. (See below)

Provide the following values for the Caption, Image, ActionType, Post-Action Event ActionType, Post-Action Event Page, RecordOperation, and ContextType properties:


Figure 96 - Delete Process' action properties

Step 9 – Configuring the “Start Process” ActionCreate a new action that starts our business process. By selecting the “Start process” action within the “Tasks” action group, the end user can start the business process with the specified parameter set.


In this step we will actually start the business process and then navigate to back to the same status page to view the results. This step assumes that the business process spec has been completed and loaded into the Infinity catalog/database. This step also assumes the CLR code that forms the logic for the business process has compiled within the catalog assembly and the assembly deployed to the Infinity web server. We will create an action button to start the business process given a selected parameter set. After the business process has been started, we will navigate to the page via the StatusPage property within the action.

In design mode, select the Edit action groups to begin the process of configuring a new action which will start our food bank inventory business process. See below.

Figure 97 - Adding a new action

Select the Tasks action group followed selecting ellipsis button next to the Actions property.

Select the Add button on the Action dialog and complete the property sheet as shown below.

The ActionType property should be set to StartBusinessProcess and the business process name will be the Inventory Process Business Process as defined within our business process spec. Configure the action to navigate to the Inventory Process Business Process Instance Status Page after the business process has started. Provide the id of the currently selected row within the data list as the context to the business process. This will provide the business process with the primary key value of the parameter set to run with the business process. Use the screen shot below as a guide.


Figure 98- Configuring the Start Process action button

Your action buttons should now look like this. See screen shot below.

Finally, start the business process by selecting the Start Process action.

Step 10 – Inspect the Output Format TableOutput tables may be created as a result of a business process. The BusinessProcessOutput table contains data describing the output of a particular business process run. The BusinessProcessOutput.TableName field refers to an output table for a given instance of a business process. The BusinessProcessOutput.TableKey field is the key by which this table will be referenced internally. For more information see BusinessProcessOutput .

Open SQL Server Management Studio and query the BusinessProcessOutput table within the appropriate Infinity database.

Use the T-SQL SELECT statement below to determine the name of the generated business process output table. *** Be sure to use your BusinessProcessSpec’s ID attribute value within the WHERE clause. ***

SELECT TOP 1000 BPO.[ID] ,BPO.[BUSINESSPROCESSSTATUSID] ,BPO.[TABLENAME] ,BPO.[TABLEKEY] ,BPO.[ADDEDBYID] ,BPO.[CHANGEDBYID] ,BPO.[DATEADDED] ,BPO.[DATECHANGED]


,BPO.[TS] ,BPO.[TSLONG] ,BPO.[DOWNLOADPARAMETERS] ,BPO.[COLUMNMETADATA] FROM [dbo].[BUSINESSPROCESSOUTPUT]BPO INNER JOIN BUSINESSPROCESSSTATUS BPS ON BPO.BUSINESSPROCESSSTATUSID = BPS.ID INNER JOIN BUSINESSPROCESSCATALOG BPC ON BPS.BUSINESSPROCESSCATALOGID = BPC.ID WHERE BPC.ID = 'YOUR BUSINESS PROCESS ID GUID GOES HERE'

For example, the query below results in the following results:

In the sample query results above, the TableName column provides the name of the output table generated from our business process. Querying this table provides the results of the business process run given the selected parameter set. See below. Your results will vary depending on the food bank transaction within the database and the parameters chosen for the given parameter set.


15 Parameter Set Page

One of the tasks a business process administrator/end user will need to accomplish is managing parameter sets for a given business process. Once a parameter set has been established, the user should be able to launch a new instance of the business process and direct the user to a separate page to view history of previous business process instances. In addition, the user will need to permission and secure a parameter set for a particular site and/or role.

A page should be constructed that contains a data list to allow the viewing of parameter sets for the business process. The page should allow for the selection of a parameter set for the purpose of starting a business process instance and the securing of a parameter set for a site and or role. The UML use case diagram to the left displays how the user will interact with the page. Each oval represents a use case which is a discrete and repeatable interaction that a user or ‘actor’ experiences when using the page. Actors represent the users of the system. Users can be human, machine or other computer systems.

Figure 99 - BP Parameter Set Page UML Use Case Diagram

15.1 Business Process Parameter Set Data List

Before we can build a page to display and start our food bank inventory business process with a parameter set, we need to provide a feature that will display the associated parameter sets.

The data list must support the following requirements:

1. Ability to uniquely identify the parameter set row within the database. This id will be used to start the business process, edit a parameter set, delete a parameter set, secure a parameter set, and view the status history of the business process. The end user must not be able to see this column within the datalist.

2. Ability to view the name and description of the parameter set.

3. Ability to view the name of the Selection associated with the parameter set

4. Ability to view the name of the Query View associated with the parameter set

5. Ability to uniquely identify the owner (if any) of the parameter set. The end user must not be able to see this column within the datalist.


TripOt, 10/11/11,


TripOt, 10/11/11,


6. Ability to restrict the view of parameter sets to which the current user does not have permission to execute.

To fulfill these requirements the data list will require a SELECT statement to retrieve data from the USR_INVENTORYPROCESS, IDSETREGISTER, BUSINESSPROCESSVIEW, and BUSINESSPROCESSINSTANCE tables.

For more information on these tables, review the section titled Tables . The SELECT statement will also restrict the view of parameter sets to which the current user does not have permission to execute using a user defined function provide by Blackbaud named UFN_SECURITY_APPUSER_GRANTED_BUSINESSPROCESSINSTANCE_IN_SYSTEMROLE.

The data list will return the following columns of data. Note the hidden columns.

FieldID Caption Data Type

IsHidden Description

ID System record Id Guid True USR_INVENTORYPROCESS.ID

NAME Name String False USR_INVENTORYPROCESS.NAME

IDSETREGISTERNAME Selection String False IDSETREGISTER.NAME

QUERYVIEWCAPTION Output Format String False BUSINESSPROCESSVIEW.CAPTION

DESCRIPTION Description String False USR_INVENTORYPROCESS.DESCRIPTION

OWNERID Owner ID Guid True BUSINESSPROCESSINSTANCE.OWNERID

Table 3 - Datalist Output Fields

15.2 Exercise 6 – Review and Load the Business Process Parameter Set Data List

Before we can build a page to display and start our food bank inventory business process with a parameter set, we need to provide a feature that will display the associated parameter sets. For details on this data list see the section Business Process Parameter Set Data List.

Step 1 – Review the Data List’s Stored Procedure Review The CREATE PROCEDURE statement below in Step 2 within the DataListSpec which is used to retrieve the

rows for the datalist.

Review each table referenced in the T-SQL using the Tables section of this document.

Review the UFN_SECURITY_APPUSER_GRANTED_BUSINESSPROCESSINSTANCE_IN_SYSTEMROLE user defined function using the Blackbaud Enterprise CRM Database Reference which is located within your SDK\Documentation folder (BlackbaudEnterpriseCRM.chm). Alternatively, you may review the function within the database. This function returns true if user has been granted and not denied the business process instance for a System Role.

Step 2 – Copy and Load the Spec Create a new DatalistSpec within your catalog project within the new Inventory Folder. Name the xml file:

InventoryProcesses.DataList.xml

Replace the xml for the new DataListSpec using the DataListSpec listed below.

Save and load the spec<DataListSpec

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"ID="53a74b52-b121-4210-bb93-505ddcaa22ec"


TripOt, 10/11/11,


TripOt, 10/11/11,


TripOt, 10/11/11,


Name="Inventory Process Business List"Description="Returns a list of Inventory Process Business process parameter sets."Author="Technical Training"common:SecurityUIFolder="Constituent\Food Bank\Inventory"xmlns:common="bb_appfx_commontypes"xmlns="bb_appfx_datalist">



<SPDataList SPName="USR_USP_DATALIST_USR_INVENTORYPROCESS"><common:CreateProcedureSQL>

<![CDATA[create procedure dbo.USR_USP_DATALIST_USR_INVENTORYPROCESS( @CURRENTAPPUSERID uniqueidentifier = null )as

set nocount on;

SELECTIP.ID,IP.NAME,IDS.NAME as IDSETREGISTERNAME,BPV.CAPTION as QUERYVIEWCAPTION,

IP.DESCRIPTION, BPI.OWNERID

FROMdbo.USR_INVENTORYPROCESS IP

INNER JOINdbo.IDSETREGISTER IDS on IP.IDSETREGISTERID = IDS.ID

INNER JOIN BusinessProcessView BPV on IP.QUERYVIEWID = BPV.QUERYVIEWCATALOGID

LEFT JOINdbo.BUSINESSPROCESSINSTANCE BPI on IP.ID = BPI.BUSINESSPROCESSPARAMETERSETID

where dbo.UFN_SECURITY_APPUSER_GRANTED_BUSINESSPROCESSINSTANCE_IN_SYSTEMROLE(@CURRENTAPPUSERID, IP.ID) = 1

order by IP.NAME

]]></common:CreateProcedureSQL>

</SPDataList>

<Output><OutputFields>

<OutputField FieldID="ID" Caption="System record Id" DataType="Guid" IsHidden="true" /><OutputField FieldID="NAME" Caption="Name" DataType="String" /><OutputField FieldID="IDSETREGISTERNAME" Caption="Selection" DataType="String" />

<OutputField FieldID="QUERYVIEWCAPTION" Caption="Output Format" DataType="String" /> <OutputField FieldID="DESCRIPTION" Caption="Description" DataType="String" /> <OutputField FieldID="OWNERID" Caption="Owner ID" DataType="Guid" IsHidden="true" />

</OutputFields></Output>

</DataListSpec>

15.3 Exercise 7 - Building the Business Process Parameter Set Page

The following describes the process to build a simple business process parameter set page. This page will contain a single tab with a single section containing a data list to hold the parameter sets that the current user has permission to view and manage.

Within the section containing the data list are 6 section actions that enable the following:

In this exercise we will begin to build the page to host the data list and corresponding actions to manage parameter sets for the food bank inventory business process.

Step 1 – Begin the process of creating a new page Navigate to the Administration > Application > Shell Design Page


Select the Pages tab

Figure 101 - Adding a new page

Selecting the Add action above the Pages data list opens the property sheet used to create a new page. See above.

Provide the following properties for the new page:


Note: On the page that we are building, there is no value for the RecordType property. The RecordType property declares the record type of the context for the page, if any. When it comes time to configure a task or an action to navigate to the new page, we will not need to provide any context to the page.

Figure 102 - New page property sheet without a RecordType property value. This page will not require any context prior to its display.

Step 2 – Add a new tab Select the ellipsis button to the right of the Tabs property. This will open a new property sheet that enables you

to add tabs to the page.


Figure 103 – Selecting the ellipsis button to begin adding 1 tab to the page

With the ‘Tabs’ property sheet open, select the Add button within the lower left hand section of the page and provide the following properties for the tab. Note with only one tab, the tab will not be visible within the user interface but its future contents will be visible.


Figure 104 - Adding the properties for the tab

Step 3 – Add a new section with data list within the tabIn this step we will add a data list that displays the different business process instances for our business process. The data list is populated via a stored procedure that pulls the parameter sets from the USR_INVENTORYPROCESS table. The list is filtered based on security permissions for the current application user. In other words, if the current user does not have rights to view a parameter set for the business process, then the corresponding row will not be displayed within the datalist.

A tab can contain many sections and a section contains a reference to a single feature, such as a data list. With the Tabs property sheet open, select the ellipsis button (purple square above) next to the Sections property to begin the process of adding a new section.

With the Sections property sheet open, select the Add button in the lower left hand section of the page. This will begin the process of adding a section within the tab. The section will ultimately contain a reference to the data list we created in the prior exercise. See figure below.

Note: For a refresher on configuring Pages via Design Mode within the Infinity Shell user interface, see the following articles within the Blackbaud Developer Network:

http://bbdevnetwork.com/content/pages

http://bbdevnetwork.com/content/configuring-page-tab-and-data-list The section should display the data list named ‘Inventory Process Business List’ that we created in the previous

exercise.

Use the figure below to add a reference to the data list within the new section:


TripOt, 10/18/11,

Adjust to new content

http://bbdevnetwork.com/content/configuring-page-tab-and-data-list

http://bbdevnetwork.com/content/pages

Figure 105 - Add the Parameter Sets section to the tab

Select OK on the sections property sheet, followed by selecting Ok on the tabs property sheet, followed by selecting the Save button for the page property sheet.

Navigate to the Shell Design page via Administration > Application > Shell Design. Locate your newly created Food Bank Inventory Business Process Parameter Set Page within the Shell Design page


Step 4 – Test the page Once the page has been located, select the Test page action to open the page.

Figure 106 - Testing the page within Shell Design

The number of parameter sets within your data list on the page may vary from the figure below. At this point, you probably do not have any parameter set record within the database for this business process. In the next step we will add an action button above the data list which allows the opening of a data form to add a parameter set to the database.

Place the page into design mode by selecting Tools > Design Mode from the main menu

Step 5 – Adding a Parameter Set


With the shell in design mode, select the Edit actions button within the section that holds the Parameter Sets data list. See below.


With the dialog window open (see below), select the “Add” button to begin the process of adding the new action. Provide the following properties for the new action which will open the “Inventory Process Business Process Add Form” which is used to add a new parameter set for this business process.

Figure 108 - Adding an section action to call the Inventory Process Business Process Add Form

Within the new action created, let’s test the new action. Within the section on the page, select the new Add button and try out the add data form by adding a new parameter set.

Provide a name, description, select the ‘All Food banks’ selection created from one of the previous exercises. Finally, and select one of the output formats create earlier, as well.


Figure 109 - Testing the Add action

Step 6 – Editing and Deleting Parameter Sets Using the previous step as a guide, add two new actions, one for editing the parameter set and the other for

deleting the parameter set. Use the table below for details.

Edit Action ButtonProperty Value

Caption Edit

Image RES:edit

ActionType ShowDataForm

DataForm Inventory Process Business Process Edit Form

ContextType SectionField

SectionField ID

Post-Action Event Action Type RefreshSection

Delete Action ButtonProperty ValueCaption Delete

Image RES:delete

ActionType ExecuteRecordOperation

RecordOperation Inventory Process Business: Delete

ContextType SectionField

SectionField ID

Post-Action Event Action Type RefreshSection

Table 4 - Edit and Delete action properties

When you are done adding the two actions, test each action on the page. Ensure you can an edit and delete existing parameter sets.


Figure 110 - Testing the Edit action

Figure 111 - Testing the Delete Record Operation

Step 7 – Starting the Business Process with a Selected Parameter SetIn this step we will start the business process and then navigate to our status page to view the results. This step assumes that the business process spec has been completed and loaded into the Infinity catalog/database. This step also assumes the CLR code that forms the logic for the business process has compiled within the catalog assembly and the assembly deployed to the Infinity web server. It also assumes the Inventory Process Business Process Instance Status Page has been completed. We will create an action button to start the business process given a selected parameter set within the data list. After the business process has been started, we will navigate to the page via the StatusPage property within the action.

Select the Edit action button to begin the process of configuring a new action which will start our food bank inventory business process. See below.



The ActionType property should be set to StartBusinessProcess and the business process name will be the Inventory Process Business Process as defined within our business process spec. Configure the action to navigate to the Inventory Process Business Process Instance Status Page after the business process has started. Provide the id of the currently selected row within the data list as the context to the business process. This will provide the business process with the primary key value of the parameter set to run with the business process. Use the screen shot below as a guide.

This new action button should appear before the Add, Edit, and Delete actions

Note the value for the AppendSeparator property. See below

Figure 113- Configuring the Start Process action button

Your action buttons should now look like this. See screen shot below.


Figure 114 - Start Process Action Button

Press the new Start process button and try out the business process. You may have to debug the code with the business process and status page after kicking of the process. Good luck! If all goes well , the action button should direct you to the status page

Figure 115 - Status Page

Step 7 – Go to the Business Process Status Page Select the Edit action button once again to begin the process of configuring another new action which

will navigate to our status page

The ActionType property should be set to ShowPage and the page name is Inventory Process Business Process Instance Status Page. Provide the id of the currently selected row within the data list as the context to the page. Use the screen shot below as a guide.

This action button should appear before the Start Process action button.


Figure 116 - Adding the action button that will navigate the user to the BP status page

At this point the page should look like the following below. Note the two new action buttons to start the business process and to navigate the status page.

Figure 117 – Our new Go to process action button

Step 8 – Secure the Parameter Set for the Business ProcessNext, let’s secure certain users from starting a business process using a specific parameter set. In this step we will create an action button to open the ‘Edit Business Process Instance Permissions With Site’ data form which allows the editing of permissions for a parameter set associated with a given business process. This data form is as an “out of the box” feature of Blackbaud Enterprise CRM. This data form has a very interesting behavior. When a parameter set is selected and the data form is loaded, a stored procedure named ‘USP_DATAFORMTEMPLATE_EDITLOAD_BUSINESSPROCESSINSTANCEWITHSITE_PERMISSIONS’ will add a row into the BusinessProcessInstance table. The BusinessProcessInstance table supports the securing of a parameter set for a business process to a particular site and/or selected security roles. By default, the inserted row grants permission to all system roles to execute the business process for the selected parameter


set. This default behavior may be altered using the ‘Edit Business Process Instance Permissions With Site’ data form.

With our parameter set page in design mode, select the Edit actions button one last time to begin the process of configuring another new action which will secure a parameter set for a given site and/or security role. We will be using a data form, named ‘Edit Business Process Instance Permissions With Site’, which allows the editing of permissions associated with a given business process.

This action button should only be enabled if the current user is a system administrator or the current user is the owner of the business process.

This action button should be placed to the right of the existing action buttons

The ActionType property should be set to ShowDataForm and the data form name is ‘Edit Business Process Instance Permissions With Site’. Provide the id of the currently selected row within the data list as the context to the data form. Use the screen shot below as a guide.

Notice the expression used for the Enabled property. The expression will evaluate to either True or False. The expression checks to see if the current application user is a system administrator or if the current application user is the owner of the parameter set. Note the Fields!OwnerID macro field which is looks for the value of an OWNERID field which optionally may be an output field within the datalist. This OWNERID field refers to the field within the BUSINESSPROCESSINSTANCE table. If you desire the BUSINESSPROCESSINSTANCE.OWNERID field populated for your future business processes, then you will need to create the appropriate Infinity feature to manage this data. Otherwise, the application user will need to be a system administrator to select this action.

Expression value:

= Globals.CurrentAppUserIsSysAdmin() OrElse (Globals.CurrentAppUserID = new System.Guid(CStr(Fields!OwnerID)))

Figure 118 - Configuring the action to display the permission data form

Step 9 – Creating a task to open the parameter set page


In this step we will create a task within the food bank functional area which opens the parameter set page.

Navigate to the Administration > Application > Shell Design Page


Select the Tasks tab and click the Add action button.

Complete the task as shown in the dialog below.

This will create a new task within the food bank functional area that opens our new parameter set page.

Once the task is created, refresh shell navigation to view the task within the food bank functional area


Click the new task to open the page


16 Business Process Tasks

16.1 Using a Task’s StartBusinessProcess Action Type

A task spec can be configured to start a business process using an ActionType equal to StartBusinessProcess. When configuring the task you will need to focus on the following properties:

1. BusinessProcess: The business process that the task will start.

2. StatusPage: After the business process is started, the system will redirect the user to the status page.

3. ContextType: The business process may need a GUID that uniquely identifies which parameter set to use when running the business process. You can either hard code a GUID which represents a specific parameter set or allow the end user to select a parameter set via a search list named “Business Process Parameter Set Search”.

In the figure below we see the property sheet for a task spec that starts our Inventory Process Business Process. The identifier for the parameter set is hard coded as a GUID within an expression for the ContextType parameter. This GUID (yellow highlight below) points to the business process parameter set table’s primary key value.

Figure 120 - Using the StartBusinessProcess ActionType within a Task

When the task is executed by the end user, the system will start the business process as determined by the Task’s BusinessProcess attribute using a specific parameter set which is determined by the GUID provided for the expression for the ContextType property.


Figure 121 - The configured task

Figure 122 - The status page displays the configured parameter set and the recent status for the BP.

See below for the TaskSpec which was reverse engineered from the configured task.


Figure 123 - Resulting TaskSpec Created from the Configured Task

16.2 Using a Task’s RunBusinessProcess Action Type

You can configure a task with an ActionType of RunBusinessProcess which will navigate the user to a specific business process “launch page” with a specific parameter set. In the example below the launch page is our Inventory Process Business Process Instance Status Page.


Figure 124 - RunBusinessProcess can be used to load a launch page with a parameter set

When the task is executed by the end user, the system will navigate to the launch page as determined by the Task’s Page attribute. The BusinessProcessParameterSet property determines a specific parameter set for the launch page.

Figure 125 - RunBusinessProcess Task

Below you can see the page opened by the task. By selecting the “Start process” action within the “Tasks” action group, the end user can start the business process with the specified parameter set.


Figure 126 - The launch page is ready to "blast off" with the specified parameter set.


References

1 Introduction to Windows Script Technologies http://technet.microsoft.com/en-us/library/ee176792.aspx

2 Using Windows Script Files (.wsf) http://msdn.microsoft.com/en-us/library/15x4407c(v=vs.85).aspx

3 HTTP Handlers and HTTP Modules Overview http://msdn.microsoft.com/en-us/library/bb398986.aspx

4 Task Scheduler http://msdn.microsoft.com/en-us/library/aa383614(v=vs.85).aspx

5 About the Task Scheduler http://msdn.microsoft.com/en-us/library/aa446802(v=VS.85).aspx

6 Inheritance from a Base Class in Microsoft .NET http://msdn.microsoft.com/en-us/library/ms973803.aspx



http://msdn.microsoft.com/en-us/library/aa446802(v=VS.85).aspx

http://msdn.microsoft.com/en-us/library/aa383614(v=vs.85).aspx

http://msdn.microsoft.com/en-us/library/bb398986.aspx

http://msdn.microsoft.com/en-us/library/15x4407c(v=vs.85).aspx

http://technet.microsoft.com/en-us/library/ee176792.aspx

advanced configuration batch and import - fundraising for web viewoverriding the...

Documents