Workflow Integration

This topic describes how to design and launch FileNet P8 workflows that integrate collaborative work environments and tasks.

The FileNet Team Collaboration Manager product installs an inheritable workflow definition file (CollaborationIntegration.pep) that provides the base elements required to integrate core collaboration functionality into workflows, making component integrator steps available for collaboration. A collaboration queue (Collaboration_Wait) is configured on the Process Engine, permitting the workflow engine to await completion of TCM tasks that are designated "workflow-aware." For important information on installation and configuration of these and other elements that comprise workflow support in TCM, see the task, "Configure Workflow for TCM use" in the TCM Installation Guide.

Developers must use the provided base workflow definition file (CollaborationIntegration.pep) from within the FileNet P8 Process Designer to create teamspaces (new or from templates) or create tasks within existing workflows. The base workflow definition's submaps combine component integrator steps and other workflow logic necessary to integrate the specified collaboration functionality. Any workflows designed to include collaboration functionality must inherit the Collaboration Integration workflow as the base workflow, or include its submap and required workflow data.

Two sample workflows—CreateTeamspace WithTaskSample.pep and CreateCollaborationTeamspaces-TSMembers-Tasks_Sample.pep—are provided to demonstrate how to design workflows using the Collaboration Operations. CreateTeamspaceWithTaskSample.pep, which shows how to create collaboration objects using the base workflow (CollaborationIntegration.pep), is described in more detail in the section Sample Workflow Definition at the end of this topic. The second sample, CreateCollaborationTeamspaces-TSMembers-Tasks_Sample.pep, shows how to create collaboration objects using a Component Integrator Step from the Collaboration Operations queue. Note that the createTask Collaboration Operation cannot be used by itself—it must always be used with the additional functionality defined in the CreateTask step of the CollaborationIntegration.pep (base workflow). See About the Component Integrator for instructions on how to design workflows using Component Integrator Steps.

Note: In the procedure described below in "Using the Process Designer to Create Teamspaces and Tasks," main workflow data (fields, attachments, and workflow groups specified in the Workflow Properties dialog box) interact with the Submap Steps in the current workflow by pushing and pulling data to and from those steps. This allows the workflow designer to specify different workflow data entries specific to collaboration functionality, preventing conflicts with data that may be provided in later submap calls. For instance, an array of attachments used by one workflow-aware task may be different from that used by another workflow-aware task, and applied differently in other steps specified later in the workflow that may relate to a different business process.

Creating Teamspaces and Tasks

Note: The provided workflow definition file described in this procedure is, in a default installation, checked into a Content Engine server and then transferred from Workplace as described in the TCM Installation Guide section, "Configure Workflow for TCM use".

To use the Process Designer to create teamspaces and tasks:

  1. Sign in to the FileNet P8 Workplace. (Note: Appropriate permissions are required to access Workplace's Advanced Tools page and Process Designer.)
  2. Expand the Author list, then choose Advanced Tools.
  3. Open the Process Designer.
  4. Choose Workflow Properties from the View menu to open the Workflow Properties dialog box.
  5. Click the Modify button to open the Select Base Workflow dialog box.
  6. Choose Collaboration Integration as the base workflow from which to inherit your new workflow, then click OK to close the Select Base Workflow dialog box.
  7. In the Workflow Properties dialog box, type a new Workflow Name, as well as a Subject and Description for your workflow.
  8. Select the Data Fields tab and specify your data fields. Sample data entries are shown here:



  9. Select the Attachments tab and specify any attachments you wish to add to the workflow. As with data fields, attachment fields are used by the Submap Steps described later in this procedure. Sample entries: teamspaceParentFolder, teamspaceRef, taskRef, taskAttachments. Note that taskAttachments should be specified as an array.
  10. Select the Workflow Groups tab and specify your user groups. Again, these fields are used by the Submap Steps described later in this procedure. Sample entries: teamspaceOwner, taskAssigner, taskAssignee.
  11. Click Close to dismiss the Workflow Properties dialog.
  12. Add (create) a Submap Step to the workflow.
  13. Select the new Submap Step. From the Submap dropdown list on the Properties page, select a collaboration submap from the base workflow. You can select from Create Collaboration Task, Create Teamspace, or Create Teamspace From Template. For the purposes of this example, choose Create Teamspace. In the Name field of the Properties page, rename the step (for example, "WF_Teamspace").
  14. Add a second Submap Step. This time, add a task by choosing Create Collaboration Task from the Submap dropdown list. Rename the step (for example, "WF_Task").
  15. Add a System Step. This step is used to assign data to the teamspace prior to its creation.
  16. Select the new System Step and rename it to clarify its purpose (for example, "Teamspace data assignment").
  17. From the Functions list on the Properties page, select the Assign function. Double-click Assign on the Selected Functions list to open the Assign dialog box. Use this dialog to map your fields to the base properties supplied in the CollaborationIntegration definition file. Base properties are available from a dropdown list in the Name column. The Expression Builder (available by clicking the "..." button in the Expression column after choosing a base property) helps you locate your fields by type (Data, Attachment, Workflow Groups, etc.).


  18. Add a second System Step. This step is used to acquire data after the teamspace is created. Select the step, and rename it to clarify its purpose (for example, "Teamspace data acquisition "). As in the previous step, use the Assign function and dialog box to perform the mapping. In this sample, only one assignment is required for this step. Name: teamspaceRef, Expression: TCMTeamspaceRef (from Attachment Fields).
  19. Repeat the previous four steps to add System Steps for task data assignment and acquisition. For tasks, the data assignment parameters contain a collection of task-specific properties and mappings, as shown here:



    On the task data acquisition step, for the purpose of this sample, only two assignments are needed: taskRef=TCMTaskRef, and taskAttachments=TCMTaskAttachments.
  20. Add a verification step to the map. Though this is an optional step, it provides an easy way to confirm that the workflow proceeds as expected. To create a verification step, add a General Step, rename it accordingly (for example, "Data Verification"), click the Modify button next to the Participants radio button on the Properties/General page to open the Participant Selection dialog box, choose F_Originator, and close the dialog box. If applied, the verification step should also be used to expose any parameters that should be made visible to the user step. To do that, use the Parameters tab on the Properties page and select from the Available Parameters.
  21. Create an exit step for the workflow by adding a System Step, assigning it the Terminate function, and renaming it accordingly (for example, "End Workflow").
  22. Add routes between the teamspace, task, and assignment/acquisition steps, as shown here:


  23. Choose Validate from the File menu to test the workflow and correct any validation errors. Note: Verification is an optional debugging task and should only be used during workflow design.
  24. Select the Launch Step, then select the Parameters tab on the Properties page. Select all parameters on the Available Parameters list and click the green select ( > ) button to select all.
  25. Select File | Transfer to transfer the workflow. When prompted to save the workflow, browse to and select a folder in your Object Store. Give the Workflow definition a Document Title, and click Finish (or click Next to set security on the Workflow definition). Note: Transferring the workflow allows it to acquire a workflow ID, which provides the Process Engine with the data it needs to launch the workflow and track the workflow definition with the running workflow objects.
  26. Choose Launch from the File menu. The Launch Processor window appears, with all fields available for specification or modification:

Base Workflow Property Reference

The following tables describe properties available from the base workflow (CollaborationIntegration.pep) for each step type.

Create Teamspace

Property Description
TCMTeamspaceParentFolder Attachment. Can be specified either by the workflow designer or by the user. If creating a workflow from the procedure described earlier in this topic, use the attachment button in the Launch Processor LaunchStep view to browse for a teamspace location after launching the workflow.
TCMTeamspaceFolderClass String. Required. Default value: "CollaborationTeamspace". Custom applications may designate a new class.
TCMTeamspaceName String. Required. Identifies the new teamspace.
TCMTeamspaceOwner Required identification of the teamspace member creating the teamspace. If specified in a Submap Step, use a workflow group containing one participant. If specified in a Component Step, use a VWParticipant (a single element of a workflow group, such as wfgroup[1], keeping in mind that workflow group arrays begin with element 1, not 0).
TCMOwnerRole String. Required. Value: A role (for example, "admin-security-role") with teamspace administrative privileges. Since the member specified in TCMOwnerRole is the only member of the teamspace when it is created, the role specified here should have sufficient capability to control the teamspace.
TCMOwnerEmailAddress String. Optional. Email address of the teamspace creator. Must be available to P8 applications.
TCMTeamspacePropertyNames An array of property names. Optional. Normally used for properties defined in a custom teamspace class.
TCMTeamspacePropertyTypes An array of types matching the property names array. Optional. Values are defined in the Content Engine Property interface. Note: Use only integer values (0-8) here.
TCMTeamspacePropertyValues An array of values to match the property names array. Optional. Normally used for properties defined in a custom teamspace class.
TCMAppId String. Required. Specified by the workflow designer, based on the collaboration application that will be used to handle the collaboration objects created by this workflow. Default installation value is "TCM". May differ in a custom collaboration application, but must correspond to a value in the Collaboration Store's application configuration file.
TCMTeamspaceRef Not specified by task creator. Automatically generated when the workflow is launched and the teamspace is created.

Create Collaboration Task

Property Description
TCMTeamspaceRef Attachment. Required. If creating a workflow from the procedure described earlier in this topic and you are not creating a teamspace in the same workflow, use the attachment button in the Launch Processor LaunchStep view to browse for a teamspace location after launching the workflow. If you are creating a teamspace in the same workflow, the reference value is automatically generated when the workflow is successfully launched.
TCMTaskName String. Required. Provides a label for the task.
TCMTaskAssigner Required identification of the teamspace member assigning the task. If specified in a Submap Step, use a workflow group containing one participant. If specified in a Component Step, use a VWParticipant (a single element of a workflow group, such as wfgroup[1], keeping in mind that workflow group arrays begin with element 1, not 0).
TCMTaskAssignee Optional identification of the the teamspace member to whom the task is assigned. If specified in a Submap Step, use a workflow group containing one participant. If specified in a Component Step, use a VWParticipant (a single element of a workflow group, such as wfgroup[1], keeping in mind that workflow group arrays begin with element 1, not 0).
TCMWorkflowAwareFlag Boolean. Optional. If true (the default), the workflow will not complete until the task has been marked as completed by the assigner or assignee.
TCMTaskDueDate * Optional. The date and time on which the task is to be completed. Recommendation for main workflow fields: Set to the default null(date).
TCMTaskReminderDate * Optional. The date and time on which members assigned the task are to receive reminder emails. Recommendation for main workflow fields: Set to the default null(date).
TCMTaskPriority Integer. 1 = High priority, 2 (default) = Normal priority, 3 = Low priority.
TCMTaskDescription String. Optional. Describes the task.
TCMWaitQueueName Not specified by task creator. Automatically-generated property specifies the Collaboration Queue (Collaboration_Wait) installed on the Process Engine.
TCMTaskStepWobNum Not specified by task creator. Automatically generated when the workflow is successfully launched (obtained by the submap to handle possible workflow branching).
TCMTaskAttachments Array of attachment(s). May include documents, folders, UNC\URLs, etc.
TCMTaskAttachmentsFieldName Not specified by task creator. Automatically generated from the base workflow.
TCMAppId String. Required. Specified by the workflow designer, based on the collaboration application that will be used to handle the collaboration objects created by this workflow. Default installation value is "TCM". May differ in a custom collaboration application, but must correspond to a value in the Collaboration Store's application configuration file.
TCMTaskRef Not specified by task creator. Automatically generated when the workflow is successfully launched.

* Note: The createTask step of the CollaboratonIntegration.pep (base workflow) cannot accept a due or reminder date/time value that has already passed. If a past date is provided to the step, createTask will ignore it and create the task with an empty date for the specified event.

Create Teamspace From Template

Property Description
TCMTeamspaceTemplate Attachment. Required. After launching a workflow, use the attachment button in the Launch Processor LaunchStep view to browse for a teamspace template.
TCMTeamspaceParentFolder Attachment. Can be specified either by the workflow designer or by the user. If creating a workflow from the procedure described earlier in this topic, use the attachment button in the Launch Processor LaunchStep view to browse for a teamspace location after launching the workflow.
TCMTeamspaceName String. Required. Identifies the new teamspace.
TCMTeamspaceOwner Required identification of the teamspace member creating the teamspace. If specified in a Submap Step, use a workflow group containing one participant. If specified in a Component Step, use a VWParticipant (a single element of a workflow group, such as wfgroup[1], keeping in mind that workflow group arrays begin with element 1, not 0).
TCMOwnerRole String. Required. Value: A role (for example, "admin-security-role") with teamspace administrative privileges. Since the member specified in TCMOwnerRole is the only member of the teamspace when it is created, the role specified here should have sufficient capability to control the teamspace.
TCMOwnerEmailAddress String. Email address of the teamspace creator.
TCMAppId String. Required. Specified by the workflow designer, based on the collaboration application that will be used to handle the collaboration objects created by this workflow. Default installation value is "TCM". May differ in a custom collaboration application, but must correspond to a value in the Collaboration Store's application configuration file.
TCMTeamspaceRef Not specified by task creator. Automatically generated when the workflow is launched and the teamspace is created.
TCMTeamspaceFolderClass String. Required. Default value: "CollaborationTeamspace". Custom applications may designate a new class.
TCMTeamspaceName String. Required. Identifies the new teamspace.
TCMTeamspaceOwner Required identification of the teamspace member creating the teamspace. If specified in a Submap Step, use a workflow group containing one participant. If specified in a Component Step, use a VWParticipant (a single element of a workflow group, such as wfgroup[1], keeping in mind that workflow group arrays begin with element 1, not 0).

Sample Workflow Definition

The FileNet Team Collaboration Manager CD includes a sample workflow definition file, CreateTeamspaceWithTaskSample.pep, that offers a prepared and extended version of the workflow design described above in the procedure, "Using the Process Designer to Create Teamspaces and Tasks." To examine the sample, copy CreateTeamspaceWithTaskSample.pep from <CD>\CollaborationToolkit\Workflow to the \Workflow folder on the Application Engine server on which the base workflow definition file (CollaborationIntegration.pep) was installed, then open CreateTeamspaceWithTaskSample.pep from the Process Designer.

Note: The sample workflow definition file does not gather values from workflow data entries for presentation to the end user. The workflow designer may, however, extend the sample to test this capability in accordance with specific customer needs.

To create your own workflow, use the base workflow definition file (CollaborationIntegration.pep) and follow the guidelines above in "Using the Process Designer to Create Teamspaces and Tasks."

Additional Information

API reference: CollaborationOperations.

For information on how workflows are used within the FileNet P8 TCM application, see the TCM Help topic, Workflows.