Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
Share has, since version 3.4, a UI for Advanced Workflow. The Advanced Workflow UI contains of the following pages that lists the users's tasks & workflows:
- My Tasks page (User dashboard)
- Workflow's I've started page (available form the header menu)
- My Tasks dashlet (available form the header menu)
- Document Workflows component (on the document details page).
From these 'list' pages you can navigate to form pages to start, edit, view, complete or cancel individual workflows or tasks. These form pages are built upon the Alfresco Forms runtime which means that you can customise the forms for each individual workflow type or task type. Instructions for how to customise these pages can be found further down. First lets take a look at what we can configure on the list pages.
Table of Contents
My Tasks dashlet
In my-tasks.get.config.xml you can see that it is possible to configure the filter menu in the dashlet. You do this by overriding the config file and modify it according to your needs. You define a filter by giving it an i18n label key in the label attribute (which will be used to get the actual display label from my-tasks.get.properties) and a parameter attribute (which will be added to the end of the /api/task-instances webscript url which is used to get the user's tasks).
<config>
<filter-menu>
<filter label='item.allTasks' parameters=''/>
<filter label='item.highPriorityTasks' parameters='priority=1'/>
<filter label='item.tasksDueToday' parameters='dueAfter={-1d}&dueBefore={0d}'/>
...
</filter-menu>
</config>
Note that its possible to use runtime dates in the url parameters by using the following notations:
- {0dt} (will become the current date time in iso8601 format)
- {1d} (will become the date of tomorrow in iso8601 format)
- {-4d} (will become the date for days ago in iso8601 format).
In other words the number indicates how many days to roll the current date forward or backward, d means date and dt means datetime.
TODO: Write about how to change the maximum search results when that has been moved into the config files instead of being set from the component properties.
My Tasks & Workflows I've Started page
Both these pages are built up uping the same concept of having filters to the left and tasks or workflows in a list to the right. Each filter section (i.e 'Due') has its own filter id (in this case due common for all 'Due'-filters) and a unique filter data value for each individual filter (i.e. 'Today' has the data value today and 'Next 7 Days' has next7days).
Below is the complete config for the 'Due' filters. The label attribute contains the i18n label key that is used to get the display label from the due.get.properties file. When it comes to the id and data attributes they will be sent as values in a 'changeFilter' event which is fired when the filter is clicked.
<config>
<filters>
<filter id='due' data='today' label='link.today'/>
<filter id='due' data='tomorrow' label='link.tomorrow' />
<filter id='due' data='next7Days' label='link.next7Days' />
<filter id='due' data='overdue' label='link.overdue' />
<filter id='due' data='noDate' label='link.noDate' />
</filters>
</config>
The task-list.get & workflow-list.get components both listen for changeFilter events use the filter id and data to create url parameters that will be added to the end of the webscript url that they use to get the tasks and workflows. The task list uses api/task-instances repo webscript and the workflow list uses the api/workflow-instances repo webscript. To create the url parameters added to these webscripts both pages use their own config file. Below is the part of the config file for the task list component (task-list.get.config.xml) that corresponds to the due filters:
<config>
<filters-parameters>
...
<filter id='due' data='today' parameters='dueAfter={-1d}&dueBefore={0d}'/>
<filter id='due' data='tomorrow' parameters='dueAfter={0d}&dueBefore={1d}'/>
<filter id='due' data='next7Days' parameters='dueAfter={0d}&dueBefore={8d}'/>
<filter id='due' data='overdue' parameters='dueBefore={-1d}'/>
<filter id='due' data='noDate' parameters='dueBefore='/>
...
</filters-parameters>
</config>
Note that it is possible to use date runtime values in the parameters just like explained in the my tasks dashlet section above.
As you probably have noticed the header title in the list also correspond to the selected filter. This header label is retrieved from the task or workflow lists' .get.properties files by looking for a i18n key that matches 'filter.<filterId>.<filterData>'. Below is the part of the workflow-list.get.properties file specific for the 'Due' filter:
...
filter.due.today=Tasks Due Today
filter.due.tomorrow=Tasks Due Tomorrow
filter.due.next7Days=Tasks Due in Next 7 Days
filter.due.overdue=Overdue Tasks
filter.due.noDate=Tasks Without a Due Date
...
To create or remove a filter in one of the filter sections simply override the filter's config file AND the task or workflow lists' config files in the web-extension folder and add or remove a filter element. Make sure to match the filter id and data attributes in both files and supply the appropriate url parameters in the parameters attribute and don't forget to also add the filter's i18n key in the .get.properties file.
It could also be worth saying that some of the filters are reused on both pages, such as 'All', 'Due' and 'Priority'. If you want to replace or remove an entire filter section (i.e. switch the 'Due' filter on the 'My Tasks' page with a new custom filter) create a new component binding (template.due-filter.my-tasks.xml) in the web-extension's site-data/components folder and make it look like below to replace it with a new custom one (to remove it simply point it to a webscript component with an empty response template:
<component>
<region-id>due-filter</region-id>
<url>/components/workflow/filter/new-custom-filter</url>
</component>
TODO: Write about how to change the maximum search results when that has been moved into the config files instead of being set from the component properties.
Task & Workflow form pages
As mentioned in the previous sections the Forms Engine is used in most the workflow UI, namely the Start Workflow page, View and Edit Task Details page and within the Workflow Details page.
If custom workflows are deployed the Forms Engine will generate a default form for each type of task in the workflow. The forms will obviously be functional and contain a sensible set of fields but there will be no grouping of fields and no guarantee of their order.
To obtain the best results form configuration should be provided for your custom tasks, the following sections describe how to do this. All the configuration noted below should be placed outside the web application in the share-config-custom.xml file.
Start Workflow Form
The Start Workflow page for the out-of-the-box Adhoc workflow is shown below.
The form configuration for this page is driven from the name of the workflow definition, as the configuration below shows.
<config evaluator='string-compare' condition='jbpm$wf:adhoc'>
<forms>
<form>
<field-visibility>
<show id='bpm:workflowDescription' />
<show id='bpm:workflowDueDate' />
<show id='bpm:workflowPriority' />
<show id='bpm:assignee' />
<show id='packageItems' />
<show id='wf:notifyMe' />
</field-visibility>
<appearance>
<set id='' appearance='title' label-id='workflow.set.general' />
<set id='info' appearance='' template='/org/alfresco/components/form/2-column-set.ftl' />
<set id='assignee' appearance='title' label-id='workflow.set.assignee' />
<set id='items' appearance='title' label-id='workflow.set.items' />
<set id='other' appearance='title' label-id='workflow.set.other' />
<field id='bpm:workflowDescription' label-id='workflow.field.message'>
<control template='/org/alfresco/components/form/controls/textarea.ftl'>
<control-param name='style'>width: 95%</control-param>
</control>
</field>
<field id='bpm:workflowDueDate' label-id='workflow.field.due' set='info' />
<field id='bpm:workflowPriority' label-id='workflow.field.priority' set='info'>
<control template='/org/alfresco/components/form/controls/workflow/priority.ftl' />
</field>
<field id='bpm:assignee' label-id='workflow.field.assign_to' set='assignee' />
<field id='packageItems' set='items' />
<field id='wf:notifyMe' set='other' />
</appearance>
</form>
</forms>
</config>
The form is actually generated for the start task for the workflow definition, this is the task that defines the metadata you wish to be entered when the workflow is started. The form configuration therefore typically contains the workflow level metadata i.e. the overall priority and due date of the workflow and in the case of the Adhoc workflow, a flag to indicate whether an email should be sent when the assignee completes the task.
You may also notice the use of the priority control, this is one of the workflow specific controls added in the 3.4 release.
The other thing to note here is the 'packageItems' field. This field represents the items of the workflow package, this field has a default control associated with it so the correct one will be rendered automatically.
View and Edit Task Form
The edit form for an Adhoc task is shown below.
The configuration for tasks is similar to repository nodes and types where a specialised 'evaluator' is used, in this case a 'task-type' evaluator as shown below.
<config evaluator='task-type' condition='wf:adhocTask'>
<forms>
<form>
<field-visibility>
<show id='message' />
<show id='taskOwner' />
<show id='bpm:priority' />
<show id='bpm:dueDate' />
<show id='bpm:taskId' />
<show id='bpm:status' />
<show id='packageItems' />
<show id='bpm:comment' />
<show id='transitions' />
</field-visibility>
<appearance>
<set id='' appearance='title' label-id='workflow.set.task.info' />
<set id='info' appearance='' template='/org/alfresco/components/form/3-column-set.ftl' />
<set id='progress' appearance='title' label-id='workflow.set.task.progress' />
<set id='items' appearance='title' label-id='workflow.set.items' />
<set id='response' appearance='title' label-id='workflow.set.response' />
<field id='message'>
<control template='/org/alfresco/components/form/controls/info.ftl' />
</field>
<field id='taskOwner' set='info' />
<field id='bpm:taskId' set='info'>
<control template='/org/alfresco/components/form/controls/info.ftl' />
</field>
<field id='bpm:priority' set='info' read-only='true'>
<control template='/org/alfresco/components/form/controls/workflow/priority.ftl' />
</field>
<field id='bpm:dueDate' set='info' label-id='workflow.field.due'>
<control template='/org/alfresco/components/form/controls/info.ftl' />
</field>
<field id='bpm:status' set='progress' />
<field id='packageItems' set='items' />
<field id='bpm:comment' label-id='workflow.field.comment' set='response'>
<control template='/org/alfresco/components/form/controls/textarea.ftl' />
</field>
<field id='transitions' set='response' />
</appearance>
</form>
</forms>
</config>
All tasks, including start tasks should have form configuration defined in this way, they will be shown in both view (task details page) and edit (edit task page) modes so that should be considered when defining forms. As shown above the new info.ftl form control can be used to display metadata on an edit form but in an 'informational' way i.e. not in a disabled form control!
There are a few fields to call out here, the first is 'message'. The 'message' field is essentially the 'bpm:description' property, if the user enters a Message when they start a workflow the data will be exactly the same. If no message is entered however, bpm:description will default to the title of the type of the task i.e. 'Adhoc Task', the 'message' field displays the more appropriate (No Message) in this scenario.
The 'taskOwner' field shows the full name of the owner of the task including a link to their profile page. The 'cm
wner' property can be used instead but it will only display the task owners username.
The last field to mention is the 'transitions' field, this is a field that displays all the transitions for the task as a set of buttons. The field, like the 'packageItems' field, has a default control so the buttons will be rendered automatically.
Workflow Details Form
The Workflow Details page for the out-of-the-box Adhoc workflow is shown below. The highlighted section of the screenshot indicates the part of the page that is driven by the Forms Engine.
Workflow_Details_Start_Task_Form.png
The form being displayed in the Workflow Details page is assigned a specific form id of 'workflow-details'. The form displayed is always for the start task of the workflow. As mentioned previously the start task is used to collect the overall workflow metadata and therefore contains all the values the user entered when the workflow was initiated. The form area can therefore be configured to show any custom metadata available to the start task.
The configuration for the 'wf:submitAdhocTask' task (the start task of the Adhoc workflow) for the Workflow Details page is shown below.
<config evaluator='task-type' condition='wf:submitAdhocTask'>
<forms>
<form id='workflow-details'>
<field-visibility>
<show id='wf:notifyMe' />
<show id='packageItems' />
</field-visibility>
<appearance>
<set id='' appearance='title' label-id='workflow.set.workflow.more_info' />
<set id='items' appearance='title' label-id='workflow.set.items' />
<field id='wf:notifyMe' />
<field id='packageItems' set='items' />
</appearance>
</form>
</forms>
</config>
Workflow Controls
Several new form controls were added in the 3.4 release to support workflow, they are described in the following sections.
Priority
The 'priority.ftl' control is a fairly simple control, it just renders a drop down list using a textual representation of the priority i.e. High, Medium or Low.
Task Owner
The 'taskowner.ftl' control is the default control rendered when the 'taskOwner' field is configured for a form. The control simply renders the task owner's full name as a link to their profile page.
Package Items
The 'packageitems.ftl' control is the default control rendered when the 'packageItems' field is configured for a form. The control extends the generic association control.
This control puts the underlying association control in 'list' mode and provides actions for the items in the workflow package. These are however, driven by the values of the 'bpm
ackageActionGroup' and 'bpmackageItemActionGroup' properties, these were historically for the Explorer client to allow the actions to be customised. Until similar capabilities are exposed in the Share client the following rules apply:
- If the value of the 'bpmackageActionGroup' property is set (and not empty) the Add button under the list of items will be present.
- If the value of the 'bpmackageItemActionGroup' property is set (and not empty) a 'View More Actions' link will be available for each item in the list.
- If the value of the 'bpmackageItemActionGroup' property is set to 'remove_package_item_actions', 'start_package_item_actions' or 'edit_and_remove_package_item_actions' a 'Remove' link will be available for each item in the list and the Remove All button under the list of items will be present.
Transitions
The 'transitions.ftl' control is the default control rendered when the 'transitions' field is configured for a form. The control renders an button for each transition the task has, the default transition is rendered as a button with the label 'Task Done'.
The 'activiti-transitions.ftl' control was added in the 4.0 release and can be used for Activiti tasks where the transitions are defined by a LIST constraint. This control renders a button for each allowable value.
References
