Mike Talley
The K2 blackpearl platform provides tools and wizards that make building process-driven applications very simple. The previous chapters in this book covered the basics that are provided to developers and business analysts for building processes on the K2 blackpearl platform. However, there are additional pieces of functionality in K2 blackpearl that provide an additional level of flexibility in building and maintaining complex applications without having to write an extensive amount of code.
This chapter will cover the following topics:
Advanced Destination Rules
Advanced actions and outcomes
Advanced InfoPath capabilities
Troubleshooting
All of the examples in this chapter will be based on an Application Access Request process (see Figure 22-1).
The Application Access Request process is an InfoPath-based process that allows a user to request access to one or more applications for another employee. When the request is submitted, an e-mail confirmation is sent to the Requestor and the process is then routed to the employee's manager. After approval from the manager, the request is routed to the appropriate Application Owners, based on the information selected in the InfoPath form. The InfoPath form is deployed to a form library on a SharePoint site. Once approved, an e-mail is sent to the originator letting them know that their request has been approved. During the process, both the Manager and any of the Application Owners have the ability to decline the request, which sends an e-mail to the originator. In addition, a Cancel Request option is available during the Manager Approval step. The process also makes use of several SmartObjects to provide information to the process:
Employee: Accesses employee information from Active Directory using the out-of-the-box Active Directory Service Object.
Applications: A SmartBox-based SmartObject that holds application information, such as Name and Application Owner.
ApplicationRequest: A SmartBox-based SmartObject that holds information about the request instance, including the employee ID and the IDs of the applications that are being requested.
ApplicationAccess: A SmartBox-based SmartObject that holds information about the access levels available for a particular application.
As described in Chapters 8 and 9, K2 blackpearl provides several options for configuring destinations for human-based tasks. Destinations can be set to individual users, groups, or roles, depending on the needs of the organization. In addition, destinations can be configured to run in parallel or serially and can be configured to accommodate situations where a certain number of members of a group need to respond before moving on to the next task.
All of these options allow for a wide range of scenarios to be solved with the K2 blackpearl platform. However, to provide the most amount of flexibility possible, K2 blackpearl provides several additional options for making destinations dynamic based on information received when the process instance is started. Number of destinations, particular usernames, and so forth, may not all be known at design time but can be planned for using the following options.
K2 blackpearl provides the ability to access information stored in SmartObjects to provide destination user information for process tasks. This information may or may not be filtered based on other information within the process. In the following scenario, an Employee SmartObject is accessed to provide the manager information based on an employee that is selected in the InfoPath form that is used to kick-off the process.
On the Manager Approval step in the Application Access Request process, click the Destination Users icon in the activity strip (see Figure 22-2).
On the Destination Users screen, click the ellipsis button next to the User field.
Expand the SmartObject Server node to access the Employee SmartObject. Select the
GetEmployeeDetailslist method.This particular SmartObject method required an input parameter to be set for the Employee's information that should be returned. On the window that opens, click the ellipsis button next to the input_username field. Select the Employee Name field (
empName) from the Application Request InfoPath form.In the returns section of the screen, select Manager and click OK.
Click Finish to complete the wizard.
Deploy the process and begin a new instance of the process by accessing the Forms Library on the SharePoint site and filling out the required information.
To verify that the correct manager information is retrieved from the SmartObject, open the K2 Workspace and open the Process Overview report. Drill into the appropriate process instance and verify that the destination user for the Manager Approval task is set to the correct manager (see Figure 22-3). In this case, the employee that is requesting access is Codi and her manager is Anthony.
Another destination configuration option available in K2 blackpearl is the ability to provide destination user information via XML nodes. This allows processes to retrieve destination information from a repeating table within an InfoPath form or other XML-based document. In the following example, the destination users for the Application Owner task are retrieved from a repeating table that has been configured in the InfoPath form.
On the Application Owner Approval step in the Application Access Request process, click the Destination Users icon in the activity strip.
On the Destination Users screen, click the ellipsis button next to the User field.
Drill into the XML field that corresponds to the InfoPath form being used by the process. Select the
appOwnerfield under the Applications node, which is a repeating node.Click Finish to complete the wizard.
Deploy the process and begin a new instance of the process by accessing the Forms Library on the SharePoint site and filling out the required information.
To verify that the correct application owner information is retrieved from the InfoPath form, open the K2 Workspace and open the Process Overview report. Drill into the appropriate process instance, and verify that the destination users for the Application Owner Approval task are set to the correct owners. In this case, the application owners should be Anthony and Holly. Figures 22-4 and 22-5 show the information as selected in the InfoPath form and the destination users for the Application Owner approval step, respectively.
You may have some confusion about the options for planning an activity, how to configure Destination Rules, and the effects these different options will have on the events in the activity. K2 blackpearl allows for some extremely powerful ways to plan activities, and the way you set up these rules is determined by your process scenario. For more information about the options, see the whitepaper "K2 blackpearl Roles and Advanced Destination Rules" (www.k2underground.com/files/folders/technical_product_documents/entry20948.aspx) on K2underground.com.
Take the following example of an activity that contains three events:
Mail Event #1
Client Event
Mail Event #2
The default activity plan for all K2 blackpearl activities is Plan Just Once. This type of activity plan allows a single activity instance regardless of the number of users or slots specified. Mail Event #1 and Mail Event #2 will only ever be sent once. The same is true if you do a Plan Per Destination — All at Once, otherwise known as a parallel plan, using the default values, because the worklist item will appear on all user's worklists as soon as the activity is planned.
If you choose the Resolve all roles to users option instead of the Create a slot for each role default option, you will get as many activity instances as you have users in your role. If your role has five users, Mail Event #1 will fire five times. Mail Event #2, however, will fire only the number of times that corresponds to the number of slots you have specified. This is important to understand. The number of slots dictates how many responses are needed during the client event, so if you have five users in your role and only two slots, once two users action their worklist item, the worklist item will disappear from the three other users' worklists, and Mail Event #2 will fire twice because it comes after the client event. If you had something other than a mail event in place of Mail Event #2, such as a SharePoint document copy event, that server event would also fire only twice.
Because of the complexity of options available when configuring advanced Destination Rules, we recommend that you test your process in an environment that closely resembles your business process environment and particularly your users and roles. You can configure the mail events (or server activities) to send mail to a single address so it is easier to test the final outcome of your Destination Rule configuration, but it is important to test what is actually going to happen before deploying a process with advanced activity plans and Destination Rules.
Also keep in mind that the way in which you configure your Destination Rule impacts the way in which data is reported. For example, if you do not specify to resolve roles to users, you will see that your worklist items are assigned to the role instead of individual users, and this may not be desirable. However, resolving roles to users also prevents K2 from dynamically managing the worklists of users in the role. If you create a slot for each role, the report will still list who actually took action on the worklist items, but from an "outstanding task" point of view. You will not see who actually has worklist items assigned to them, and you will either have to know who is a member of the role or look in the Management Console to see the role membership.
In previous chapters, actions and outcomes were introduced as the way in which task actions are configured within K2 blackpearl processes. In most cases, the standard action and outcome functionality provided in the K2 blackpearl task wizards provides enough functionality to ensure that a process advances as it should. However, there are some situations that require more advanced functionality regarding how tasks are actioned by the user. The following sections describe a few advanced scenarios that can be handled by the K2 blackpearl platform.
In most cases, the auto-generated outcomes that are created based on the actions configured will handle all task-actioning needs. However, in some cases, scenarios may come up where actions and outcomes don't match on a one-to-one basis. For example, on an Expense Claim process, perhaps there is a business rule that states that after the manager approval, if the total expenses being claimed are greater than $5000, the process needs to be routed to the VP of finance for an additional approval step. In this case, there are two actions, Approve and Decline, but instead of a one-to-one match for outcomes, there are three possible outcomes, one for Manager Approved — under $5000, one for Manager Approved — above $5000, and one for declined. The K2 blackpearl task wizards make it very easy to configure these types of scenarios without having to resort to writing code. In the scenario below, if the Application Access Request includes a request to access Personnel information within SAP, the request needs to be routed to an HR representative for an additional approval step before moving on to the Application Owner step.
On the Manager Approval step in the Application Access Request process, rerun the task wizard by clicking the Run the default wizard icon on the event (See Figure 22-6).
Click through to the Outcomes page. Keep the existing outcomes but add a new one called Approved — Personnel access. Click Add to add a rule to this outcome. In the rule window that opens, set the First Variable field to be the
appAccessfield from the InfoPath form and set that to be equal to Personnel Information. The screen should look like what's shown in Figure 22-7.Next, modify the existing Approved outcome so that the name is Approved – No personnel access and has a rule that is configured like what's shown in Figure 22-8.
When done configuring the outcomes, click the Generate corresponding line(s) for listed outcome(s) and finish the wizard. You should now have an additional line coming out of the Manager Approval task that can be configured to go to a second level of approval. Your process should look like what's shown in Figure 22-9.
To complete the process, drag an InfoPath client event on to the design canvas and configure the properties so that the event uses the existing InfoPath form and a destination user in the HR group. When complete, the process should look similar to what's shown in Figure 22-10.
Security options have been greatly enhanced in K2 blackpearl, and one of the options now available is to set security on actions for a specific event. This functionality is provided by the K2 Context Grid, which is a matrix of available actions, events, users, and permissions. The management capabilities for the Context Grid are provided in the K2 Management Console and allow an administrator to select specific actions configured on a process to give to users of the process. This functionality allows for administration of users to be added or removed from process tasks without having to modify the process definition if security requirements change in the future.
In the example that follows, the Cancel action on the Manager Approval task will be restricted so that it's only available to the originator of the process.
In the K2 Management Console, expand the [ServerName]
Click Add to open the Select Users/Groups dialog box.
For demonstration purposes, select the user who will originate the process and click OK.
Verify that the Allow checkbox is selected, and click Save. The screen should look like that shown in Figure 22-11.
Kick-off an instance of the project from the SharePoint Forms Library.
Log on as the employee's manager to view the available actions for the Manager Approval task. In this example, the employee's manager is Anthony. Notice that in the K2 Tasklist, the only available options for the manager are Approve and Decline (see Figure 22-12).
Now, open the K2 Tasklist for the originator and view the available actions. Notice that the task shows on the task list with the Cancel action available.
K2 blackpearl provides extensive integration with Microsoft InfoPath to provide data capture capabilities for the processes. For more information about the standard InfoPath integration functionality provided with K2 blackpearl, see Chapter 11. Beyond the standard InfoPath functionality, K2 blackpearl can make use of InfoPath forms to provide advanced functionality for complex processes built on the K2 blackpearl platform.
In previous versions of the K2 software, processes were restricted to using one InfoPath form for all of the client tasks in the process. Different information could be displayed for different tasks in the process by using the InfoPath View functionality. However, for scenarios that had strict security requirements around data that should be seen by different users of the process, this option was not a viable one. With K2 blackpearl, the InfoPath functionality has been enhanced to allow for multiple forms to be configured on a single process. With this capability, each client task in the process can use a different form if necessary to only show the information appropriate to the user for that task.
In the following example, two InfoPath forms will be configured on the process so that the Manager Approval task uses one form and the Application Owner Approval task uses the second form.
Rerun the InfoPath Integration Wizard by clicking the InfoPath Integration icon in the upper-right corner of the process designer (see Figure 22-13).
On the Workflow Form Templates screen that appears, configure an additional InfoPath form by clicking Add and following the wizard's steps to add a second form. When complete, the screen should look similar to what's shown in Figure 22-14.
Rerun the wizard for the Application Owner Approval task. On the General Event Settings screen, select the new InfoPath form template from the drop-down and select the View and Task Action field to use. Once complete, the screen will look similar to what's shown in Figure 22-15.
Click Finish to complete the wizard and then deploy the process.
Start a new instance of the process from the SharePoint Forms Library.
On the Manager Approval task, verify that the Manager Approval view of the first form is displayed (see Figure 22-16).
Now log in as the Application Owner to verify that the second configured form is displayed (see Figure 22-17).
One of the process scenarios that K2 enables is the ability to send client tasks to multiple users for approval, all at the same time. However, the scenario gets complicated if each of those users needs to see slightly different information about the process. For example, in the Application Access Request process, the Application Owner task is routed to each application owner that has been selected in the form. To provide the best possible experience for each of those users, it would be nice to filter the information shown to them so that they only see the application information that they are responsible for. In previous versions of K2, this functionality was possible, but required an extensive amount of coding. The InfoPath form had to be set up with filters to display the information correctly based on the user that was logged in. On top of that, code needed to be written to merge each approver's approval information into the main form so that on the next task, a full picture of the approval process could be seen. This scenario was known as the "split and merge" scenario because the data had to be split across all the users and then merged back into a single view of the form.
With K2 blackpearl, and, in particular, K2 SmartObjects, the "split and merge" scenario has become more simplified. Now, instead of storing all of the relevant process information in the XML document created via the InfoPath form, this information can be stored in a K2 SmartObject. The InfoPath form can then query the K2 SmartObject to retrieve and display the correct information for the user viewing the form. No additional code is required because all relevant information is stored as a SmartObject property and can be displayed in the appropriate way for the task.
In the following example, the Application Access Request process will be modified to use K2 SmartObjects to access the relevant information to display on the InfoPath form for each client task.
On the Submit Request view of the form, modify the InfoPath form so that it includes a connection to the
Createmethod on theApplicationRequestSmartObject when the form is submitted. This will add the information about the request as an instance of theApplicationRequestSmartObject. Set the ID of the instance created to theRequestIDfield in the InfoPath form.On the Manager Approval view of the form, modify the Start Rules so that the
ApplicationRequestSmartObject is queried to return the information for the appropriate RequestID. Set the return values to display as the appropriate fields on the form. On the Submit button of this view, call the Update method on theApplicationRequestSmartObject to update theManagerApprovalfield with the value selected in the form.On the form used for the Application Owner Approval task, modify the form so that on load it queries the
ApplicationRequestSmartObject to retrieve the information about the request. Include a filter on the SmartObject so that it only returns the application information relevant to the user who is logged in to the InfoPath form, using the InfoPathUserNamefunction. On the Submit button, call theUpdatemethod on theRequestApplicationSmartObject to update theApplicationOwnerfield with the value selected on the form.On the Read Only view of the first form, update the Load Rule for that view to run a query against the
ApplicationRequestand associatedRequestApplicationSmartObject instances to retrieve all the relevant data for the process. Set the return properties from the SmartObjects to display as fields in the form.
K2 blackpearl provides several different mechanisms for troubleshooting issues with processes and SmartObjects. Troubleshooting tools range from the simple, such as the K2 View Flow or K2 Reporting environment mentioned in earlier chapters, to the more advanced, such as logging and the process management capabilities included in Visual Studio.
More information about the advanced troubleshooting options is available later in the chapter. For information on the K2 View Flow or K2 reporting environments, see Chapter 20.
The K2 blackpearl Logging Framework allows K2 server administrators to configure the amount of logging done on each K2 server for K2 processes and K2 SmartObjects and Service Objects. The Logging Framework provides a mechanism for configuring multiple log output locations, and provides support for five output targets by default. The provided extensions are described in the following table:
Logging Extension | Description |
|---|---|
| When enabled, messages will be logged to the K2 blackpearl server console when the server is being run in console mode. |
| When enabled, messages will be logged to a log file. The log file is specified in the properties of the configuration declaration. |
| When enabled, messages will be logged to the machine's Event Log. |
| When enabled, messages will be logged to a SQL Server database. By default, messages are logged to the HostServerDB connection, but can be changed in the configuration properties. Logging to a database provides the ability to run queries against logged messages. |
| When enabled, messages will be logged to a Microsoft Messaging Queue. This scenario is useful when automatic monitoring tools are used within the environment. |
In addition, custom output locations, such as e-mail, can be added to the system as necessary. For more information about creating a custom logging extension, see the Logging Framework project located on K2 blackmarket: http://k2underground.com/k2/ProjectHome.aspx?ProjectID=2.
Logging settings can be modified to display different levels of log messages. The following table describes the log levels that are available:
Log Level | Description |
|---|---|
Error | Displays messages about errors occurring within the server or in components that the server is using. Only error messages are displayed at this log level. |
Warning | Displays general warnings from the server. Both error and warning messages are displayed at this log level. |
Info | Displays informational messages, such as sessions starting and users being authenticated on the server. Error, warning, and info messages are displayed at this level. |
Debug | Displays general debugging information and is useful when trying to trace what is happening on the server. Displays error, warning, info, and debug messages at this level. |
All | Displays all levels of logging information. |
Each level of logging may be useful for different environments in your organization. For example, the development server may be configured to show Debug or All messages to provide developers information about problems that are occurring as they are developing applications. It is important to keep in mind that the level of logging that is selected may affect server performance. The All level of logging is not recommended for a production environment unless it is being used to debug a particular problem during a set period of time.
By default, K2 logging is asynchronous to minimize performance impacts on the server. However, certain scenarios may benefit from synchronous logging, so this setting can be changed as necessary. In addition, all logs can be filtered by namespace to reduce the impact on the server.
The following example walks through the steps required to modify logging output targets and levels for the K2 server. This scenario will set the logging target to be both console mode and database mode and will set different log levels for each extension.
Open C:Program FilesK2 blackpearlHost Serverin, using Windows Explorer.
This path may differ in your environment if K2 blackpearl was not installed in the default location.
Open HostServerLogging.config using Notepad or another text editor program.
Find the
<ApplicationLevelLogSettings>section.In the
ConsoleExtensionsetting, verify that the Active property is set toTrueand change the LogLevel toDebug. The line should look like this:<LogLocation Name="ConsoleExtension" Active="True" LogLevel="Debug" />
In the ArchiveExtension setting, set the Active property to
Trueand change the LogLevel toAll. The line should look like this:<LogLocation Name="ArchiveExtension" Active="True" LogLevel="All" />
Save the changes to the file.
Restart the K2 server to put the changes into effect.
Open SQL Server Management Studio.
Browse to the HostServer database.
Expand Tables and find the LogArchive database.
Right-click the database name and select Open Table.
Verify that the correct log information is being displayed in the database. The database will look similar to what's shown in Figure 22-18.
Because K2 blackpearl makes use of the Microsoft Visual Studio environment, debugging of K2 processes and K2 SmartObjects or Service Objects is available just as it would be with any other .NET application. The Visual Studio debugger allows a developer to step through the process, SmartObject or Service Object at the code level to troubleshoot errors or to verify that functionality is working properly.
The following scenario will walk through the steps necessary to debug a K2 process. This example will make use of the Application Access Request process previously described.
This example assumes that the process source files reside on the K2 server so that debugging can occur on the same environment. If Visual Studio and the source files are running on a separate client machine, it may be necessary to configure the K2 server to allow for Remote Debugging. The following link provides more information:
http://support.microsoft.com/kb/910448.
Open the Application Access Request project.
On the Email Confirmation activity, right-click the Email Confirmation event and select View Code
In the XOML designer, right-click the SetProperties activity, and select View Code.
Expand the Code Activities section, and add the following code in the
SetProperties_ExecuteCodemethod://adding code for demo string strFolio = K2.ProcessInstance.Folio; string requestor = K2.ProcessInstance.Originator.Name;
Save the changes and deploy the process by right-clicking the project name and selecting Deploy.
On the Debug menu in Visual Studio, select Attach to Process.
Select the K2HostServer.exe process, and click Attach (see Figure 22-19).
Back in Visual Studio, set a breakpoint on the first line of code that was added in Step 4 (see Figure 22-20).
Once the debugger has attached to the K2 process, start a new instance of the process by navigating to the Application Access Request Library on the SharePoint site.
Step through the code to see the values that are being set and that all functionality is working (see Figure 22-21).
K2 blackpearl provides several ways to repair errors that have occurred in a running instance of a process. These tools allow administrators or developers the ability to easily resolve issues that may be caused by environmental issues or process errors that occur because of functionality included in the process.
The first error repair option is the Retry option that is provided in the Error Profile section of the K2 Management Console. The Retry option allows a K2 administrator to retry the part of the process that errored without changing any of the process functionality. This tool should be used on the occasion that the error is not part of process functionality directly but is caused by an external environmental issue. For example, if a process is creating a new item on a SharePoint site but the site is temporarily unavailable, the process may throw an error on that step. Once the SharePoint site is available again, the process can be retried using the K2 Management Console, and the process will continue on to the next step. Figure 22-22 shows the Retry functionality in the K2 Management Console.
The second option is the process management functionality within Visual Studio. This option allows a developer to open the code in the process at the point where the error has occurred. The developer is able to make changes to the functionality and redeploy the process. When the updated process is redeployed, a new version of the process is created on the server and any existing instances that are in error will be retried. In addition, any new instances of the process that are started will use the updated version of the process. Figure 22-23 shows some of the process management functionality.
In the following example, code is added to the Application Access Request process to force an error when the process is run. Both the retry and process management functionality is used to try to resolve the error.
In Visual Studio, right-click the Email Confirmation event and select View Code
In the XOML designer that opens, right-click the Set Properties activity and select View Code.
Expand the Code Activities section, and add the following code in the
SetProperties_ExecuteCodemethod://adding code for demo int a = 100; int b = 0; int c = a/b;
Save the changes and deploy the process by right-clicking the project name and selecting Deploy.
Start a new instance of the process by navigating to the Application Access Request Library on the SharePoint site.
In the K2 Management Console, expand [SERVERNAME]
Expand the Error Profiles node, and click All to see the current errors.
For the most recent instance, note that the error is Attempted to divide by zero. Select the checkbox next to the instance information and then click Retry. The screen will look similar to the one shown in Figure 22-24.
Note that after the page refreshes, the process instance is still in error.
Open Visual Studio and select K2 Process Management in the View menu.
Expand Workflow Management Server
Highlight the instance of the process that is in error, and click Open.
Once the project has opened to the location where the error occurred, change the code so that the "b" variable does not equal 0 (see Figure 22-25).
Save the changes, and switch back over to the process management window. Click Redeploy. Give the version a descriptive name, and select Retry all instances.
Now go back into the K2 Management Console, and verify that there are no errors and that the instance is now active.
In this chapter, you have been introduced to several advanced topics on the K2 blackpearl platform. We discussed the advanced options that can be used for configuring destination users, including the use of SmartObject data and data in XML nodes, such as a repeating table node in InfoPath.
In addition, we discussed a few of the advanced options available around the actions and outcomes functionality, including configuring additional outcomes and setting specific security on an action.
InfoPath advanced topics, such as using multiple forms and providing "split and merge" functionality were discussed. And finally, we walked through several troubleshooting options that will help you debug problems that may occur when developing processes on the K2 platform.
These scenarios are certainly not the only advanced functionality that can be provided with K2 blackpearl, but they illustrate some of the most common issues that K2 blackpearl developers face. The K2 blackpearl platform provides numerous tools and functionality that make configuring advanced scenarios very easy, and typically require little to no code be added to the process.
In the next chapter, you'll be introduced to K2 connect for SAP, an add-on for K2 blackpearl. K2 connect for SAP provides a user-friendly interface for developers to model business entities against an SAP environment without having to write code. You will learn about the architecture of K2 connect and will walk through an example of how to build a business entity using the K2 connect for SAP toolset.