Workflow and History Data In Assisted Service, Self Service and User Requests

This article examines the three primary templates that are used to interact with workflow and history records - Assisted Service, Self Service and User Requests. It describes how each template displays data from the platform and how you can customise that data.

It's quite common to create multiple articles using these templates. You can tailor each article to the the type of process it displays or to how you need to use the templates.

User Request Cards

User Requests is designed to be used by individual users to track and update requests they have made via your website. User Request cards take their data from the platform's History service.

Title

The card title uses the description set in the history's subject data. Every history has a single subject, and once it's been written it can't be updated.

History subjects are written when a workflow process starts. They match the description of the process model, so make sure your process has a meaningful description as it will be visible to your users. Process model descriptions can include process variable tokens, see the final section of this article.

If there isn't a workflow description, or there's a problem with it (eg failed token expansion), the process name is written to the history subject instead.

Summary Text

The text below the title is taken from the historyDescription in most the recent SUMMARY event in the history.

Because more summary events can be added to a history throughout the lifetime of a request, you can add new events with a new historyDescription to update what a user can see, letting them know the current state of their request.

When a user completes a task during a workflow process, the form designer's Workflow - Complete Task Action field lets you choose if a summary event is written. If one is, the workflow worker will automatically take the process description (set in the process modeller) and write it to the historyDescription. Because a process description can include tokens (see below) it can be updated as the process progresses.

Task Link

User Requests queries the Workflow worker and displays any tasks in the process that the user can perform. The text on the task button ("Track and update" in the screenshot above) uses the task description set in the workflow process model and will fall back to the task name.

User Requests Summary View

The card title links to the summary view. The top section of the view displays the same information as the card.

Form Data

The Summary Details section (the title is set in the User Request article extras) is taken from the most recent public SUMMARY event in the workflow's history. The event that generated the summary in the screenshot above looks like this:

{
    "private": false,
    "historyDescription": "A description of the request",
    "description": "Summary",
    "proxyUserId": null,
    "formData": {
        "data": {
            "NAME": "Tim",
            "TYPE": "Music",
            "LOCATION": "The park over the road"
        },
        "formName": "TIMSFORM",
        "typeName": "FORM_TIMSFORM",
        "formDefinitionType": "FORMDEFINITIONEX"
    },
    "event": "SUMMARY",
    "userRole": "workflowengine",
    "userId": null
}

The formData object provides the data that the summary should display (field names and values) and the name of the form that should be used to display it. By default a read-only version of the form that wrote the summary event is used. It is possible to set a different formName via the workflow action form fields that wrote the event.

Data in the summary event will be mapped to fields on the form that have the same name. Alternatively you can write a "custom read only" handlebars template in your form which will be used to display the data. The screenshot above shows a custom read-only template that lays the form data out in a table.

Event Details

A list of all of the events in the history can be displayed beneath the summary. The User Requests article extras let you turn this section on and off and choose whether private and summary events are displayed (we don't recommend displaying either).

The name of the event (the text in bold above) is the description of the history event. The Workflow - Start Action form field has a "History event settings" property that lets you control how the event is written. The default event description is "Process started", but you can change that to something more meaningful.

Here's the event that created the entry in the list above.

{
    "private": false,
    "proxyUserId": null,
    "description": "Request submitted",
    "formData": {
        "data": {
            "NUMBER": "35",
            "COLOUR": "Blue"
        },
        "formName": "TIMSFORM",
        "typeName": "FORM_TIMSFORM",
        "formDefinitionType": "FORMDEFINITIONEX"
    },
    "event": "STARTWORKFLOW",
    "userRole": "user",
    "userId": "TIMG"
}

The workflow start action looked like this:

The list includes a link to "View details". This displays the formData in the event in the same way as the Summary Details section. Unlike summary events, the form data will always be displayed using the form that was used to submit the data. If an event doesn't have form data, the link won't appear.

Self Service Columns

Self Service lets your staff members handle requests from users. Most of the panels are powered by workflow process data that has been indexed by the platform's search engine, apart from the history panel, which comes from history. 

Active Panels

The assigned, claimable and active process panels all work in a similar way.

Description

The description column uses the process description of the workflow model.

Tasks

The task link works in the same way as User Requests - the task description that will fall back to the task name.

History Panel

This panel displays information from the platform's history service.

Description

The description is taken from the historyDescription in most the recent SUMMARY event in the history. It works in the same way as the Summary Text in User Requests.

Self Service Summary View

Clicking the process description displays the summary view. It is constructed in exactly the same way as the User Requests summary view described above, and uses the form and form data from the latest public SUMMARY event, and includes a list of events from the history.

Assisted Service Transactions

Recent requests are displayed in Assisted Service when viewing the details of users.

Each item in the list is taken from the History service. It includes the value of the history labela and the most recent SUMMARY event's historyDescription.

Tokens in Task and Process Descriptions

Your workflow process and task descriptions can include process variable tokens. That means you can dynamically update them during the process, which will save the new variable values to the historyDescription in summary events. The User Request card, Self Service description and Assisted Service entry will display the updated descriptions as tasks are carried out.

There's more information about tokens and how they are used in the modeller in the Process Variable Tokens and Expressions article.

Case Management Conventions

The Case Management workflow model has a variable named form_SERVICEREQUESTTEXT which can be set in the forms used to raise cases. This will set the title for the card that appears on the User Requests template.

Task names and descriptions are made up of a combination of the name of the user who raised the case, the case type name in the case configuration, and may include other details like the current status.