Workspace Common Variables
Would you like your Workspace users to be able to see all process instances or tasks related to a particular customer name that they participated in? Would you like to refine the number of items displayed in your To Do or Tracking lists based on a particular value?
ADEP Process Management 10.0 has introduced a new feature called Common Variables which will allow you to do this. The overall purpose of this feature is to enhance the Workspace UI experience by allowing users to see and filter on information that is common across all processes.
In three easy steps, you can be using this new feature.
- Create the variables in a system application in Workbench.
- Set them in your process using a Set Value service.
- View them in Workspace, as values in a Search Template or as column headings.
Note: This feature is intended to be used with simple variable types only such as string, boolean, date, date-time, int, long and short. Only simple types will display in Workspace.
1) Create your Variables in Workbench
You will define your common variables in a new system application called Process Manager (common-variables).
- Do a File->Get Application in Workbench to download the process.
- Check out the CommonVariables process.
- Add a variable in the usual way.
- Save the process and Deploy the application.
In the screenshot below, I have added a string variable called custName with a Title of “Customer Name.” The title is what users will see in Workspace.
Note that by default, the variable is marked “Searchable” and “Visible in UI”. Searchable allows you to add the variable to a search template and Visible in UI allows the variable to be exposed as a column heading. Also, since this is a common variable, the ability to mark it as Input/Output/Required has been removed.
2) Set Common Variables in your Process in Workbench
Now that you have created your variable, it will be available to all processes. You just need to set it in whichever process you want to use it in. The contents of these variables at runtime will be unique per process instance, just like any other process variable.
To set your common variable, you will use the XPath builder in the Set Value service. In the screenshot below, you will note that in addition to the Process Data node there is now a Common Data node to display common variables.
In my example, I have a field in my form named OrderedByCompany. The Workspace user will fill in this field before submitting the form. I will then take this value out of my form data (I picked this “Expression” from the Process Data node in the XPath builder) and map it into my common variable called custName (I picked this “Location” from the Common Data node).
When the process is run, these values will be set in the same way as normal process variables.
3) Viewing your Common Variables in Workspace
Now that your process has been run and the common variable has been set, there are multiple ways that you can see the common variable values in Workspace. They will appear as column headings in To Do and Tracking and as values returned in a Search.
Column Headings – To Do
Another new feature that was added in ADEP Process Management 10.0 is the ability to set your column preferences directly on the page you are working on. This applies to To Do and Tracking. You will use this feature to see the value of your common variables in Workspace.
Navigate to To Do. Select your queue, and make sure that you are in List View. Select the Manage Column Headings button in the top-right. Select your common variable from the list (mine was Customer Name) and select OK.
Your common variable will now appear as a column….with the values that were set when the process was run. Note that my queue in the screenshot below is set to “Show All” processes…I don’t have to select a specific process to see common variables. Since they appear across all processes, this may help to refine your To Do list.
Below, you will see that Maple Trust appears three times, once for the PurchaseOrder process and twice for the MortgageApplicationStart process.
If I filter on “Maple”, my list below will show three tasks from different processes that have the Maple Trust customer name in common. This has filtered the other 6 tasks from my list. (Note that clearing the filter brings back the other 6 tasks.)
Column Headings – Tracking
The ability to see common variables also applies to Tracking. This may provide more context when looking for a particular process instance. You can filter on the variables in the same way that I detailed above in the To Do page.
Values From a Search
Common variables may also be used in a Search Template. Using my example, this will allow a user to search for a particular customer name across different processes and will show them the tasks that they have participated in.
The ADEP administrator will create a Search Template that contains the common variable. When they create the template, the common variables will appear automatically under the Process Variables section. (For regular process variables you first have to select the process where they are defined. Common variables do not require this extra step.)
In my example, my Search Template asks the user to provide a Customer Name.
I entered Maple Trust and all tasks with Customer name Maple Trust are returned. In my case there were two processes that used this common variable and search results were returned for both processes.
Common Variables Best Practices
- When you are ready to move your Process Manager (common-variables) application from development to production via an lca, make sure you don’t change the application name and process name. The common variables feature depends on this application name/process name being Process Manager (common-variables)/CommonVariables.
- Do not create complex variable types (lists, maps etc) for use as common variables. Although Workbench allows you to do this, the feature was intended to be used with simple types only. Only simple types will display in Workspace.
- Limit the number of common variables in your system to reduce possible performance implications.
- It is not recommended to version the Process Manager (common-variables) process.
- Only delete a common variable from the CommonVariables process if you are sure it is not referenced in any process. As with regular process variables, referencing a deleted variable will cause your process instance to stall. If you are unsure whether it is referenced, a better practice would be to uncheck the “Visible in UI” and “Searchable” properties on the variable. This means the variable will no longer display in Workspace or be available for Searching.
- Default values can be used in common variables. Unless you override it in a SetValue service, the default value will be used.
- The CommonVariables process is a system process. Use it only to define your variables. Do not add any steps to it, invoke it or reference it as a sub-process.
- Record & Playback is currently not supported for common variables.
Original article at http://blogs.adobe.com/ADEP/2011/08/workspace-common-variables.html.