Skip to main content
Version: 20.05

Deploy and configure Workspaces

​ This topic explains how to setup Workspaces (Workspaces REST API) in Journey Manager (JM). ​

note

To perform the instructions below, you need to login to your JM environment with an account that has sufficient administrative privileges; for example, the System Manager role.

The steps required to setup Workspaces include: ​

  • Deploy the Workspaces REST API in Journey Manager.
  • Prepare Workspaces for first use.
  • Configure a collaboration job. ​

Deploy the Workspaces REST API

The Workspaces REST API is distributed in the Workspaces WAR file.

info

Prior to the 20.05 release, the Workspaces WAR file contained both the Workspaces REST API and the Workspaces client application. In the 20.05 release, the Workspaces WAR file contains the Workspaces REST API only.

There are two ways to deploy the Workspaces WAR file.

  • Journey Manager installer option: Starting from Journey Manager 20.05, the Workspaces WAR file comes bundled with the Journey Manager installer as an optional package. This means you can deploy the Workspaces WAR file as part of a Journey Manager installation or upgrade. Note that the JM installer doesn't support a standalone installation of the Workspaces WAR file.
  • Manual import: Sometimes you may need to deploy a Workspaces WAR file manually. You can this by downloading the relevant Workspaces WAR file and importing it into your Journey Manager instance.

Upon successful deployment by either method, a new form space called Work Spaces appears on the Form Spaces page in Journey Manager.

note

If you don’t see the Work Spaces form space on the Form Spaces page after a few minutes, the deployment may have failed. Go to the deployment folder in your JM instance, and locate the file called {warfilename}.war.FAILED. Raise a support request (login required), attaching this file.

Manual import

info

You can use this deployment method if you want to use the Workspaces 19.11 application with a TJM 20.05 instance, although we don't recommend this mixed-release deployment. For more information, see Can I deploy the Workspaces 19.11 portal in a TJM 20.05, 20.11, 21.05 or 21.11 environment?.

To import a Workspaces WAR file into Journey Manager:

  1. In Journey Manager, select Forms > Form Spaces.
  2. Click Import WAR.
  3. Click Choose File, locate the Workspaces WAR file, then select it and close the file browser dialog.
  4. Click Import to complete the WAR file deployment.

Prepare Workspaces for first use

​ Once Workspaces has been successfully deployed, a number of configuration steps are required to prepare Workspaces for use by end users. ​

Configure the Workspaces space

​ You can edit the Work Spaces form space to configure attributes such as the context path and other access related settings. For more information about configuring a Journey Manager form space, see Edit a Form Space. ​

  • In Journey Manager, select Forms > Form Spaces.
  • In the list of form spaces, locate Work Spaces and click the Edit icon for that space. Alternatively, you can click the Name of the Workspaces space.
  • Select the Space tab.
  • Update the domain part of the Context Path URL to be the same as your JM domain.
  • Select a Security Manager to be used for Workspaces.
  • Select the Authentication Mode matching the level of authentication required to access Workspaces.
  • If you need to be able to modify the Work Spaces space at runtime, select the Content Editable checkbox.
  • Select Default Forms Space to route all job step actions to the new Work Spaces space by default. ​

Note

If you want to use a Context Path domain different to the JM domain then you may need to configure a reverse proxy for redirection. ​

​ Workspaces needs to be linked to a JM organization so that forms and Txns generated from the collaboration job can be accessed by Workspaces. Follow these steps to ensure Workspaces is linked to your organization. ​

  • In Journey Manager, select Forms > Organization.
  • Select the Spaces tab.
  • If Work Spaces is in the Available Spaces list, select it and click > to move it to the Assigned Spaces list.
  • Click Save. ​

Grant user access

​ Workspaces users must be assigned to the Work Spaces space before they can login and access Workspaces features. Follow these steps to grant users access to the Work Spaces space. ​

  • In Journey Manager, select Security > User Accounts.
  • In the list of user accounts, locate the user to be configured and click the Edit icon for that user. Alternatively, you can click the user's Login Name.
  • Select the Spaces tab.
  • If Work Spaces is in the Available list, select it and click > to move it to the Assigned list.
  • Click Save.
  • Select the Roles tab.
  • Ensure the roles required to use Workspaces (Work Spaces Staff) are assigned to the user account.
  • Click Save. ​

Note

With Workspaces 19.05 release, JM roles can be assigned to a Space attribute in Global property. If you create a new role in JM, make sure you assign the following permissions to the role - Collaboration Job Completed View, Collaboration Job View and Help Desk View.

Accessing the Workspaces portal

​ Refer to the Form Deployment and Security section on how to build the Workspaces client application and deploy it in Journey Manager ​ ​

Configure the collaboration job

​ This section explains how to configure a collaboration job to route the review tasks to Workspaces, and the steps required to copy the data extracts and submission properties from an applicant’s original submission Txn to the review task.

​ Workspaces offers great flexibility in filtering and sorting Txns, which helps the back-office staff to find the tasks they need. In order to support these features, the application must include all the necessary data from the applicant’s original submission Txn that is captured as the form data extracts or submission properties. ​

Setting up each collaboration job to capture this data is a complex task. Template Groovy scripts that can assist with the collaboration job setup are provided with Workspaces. ​

Copy the form data extracts and submission properties

​ Workspaces includes a Replicate properties service (Groovy script) that copies the contents of form data extracts and submission properties from the original submission to the submission properties of the review task that will be accessed from Workspaces. ​

To add the Replicate properties service to Journey Manager: ​

  • In Journey Manager, select Services > All Services.
  • Click Import.
  • Click Browse then locate the "Replicate properties" file, select the file, and close the file browser dialog.
  • Click Upload to upload the selected file to Journey Manager. ​

Once the Replicate properties service has been added to Journey Manager, modify the collaboration job to use this service. Then, in Journey Manager:

  • Select Services > Job Services.
  • In the list of services, locate the collaboration job that manages the workflow of the application that will be reviewed in Workspaces, and click the Edit icon for that service. Alternatively, you can click the service's name in the Service column.
  • In the Job Definition, add a "Replicate properties" action after each review task. This will cause the contents of the original submission to be copied automatically to the review task. ​
{
"name": "Manual Review",
...
"actions": [
{
"name": "Create Task",
"type": "Job Task Assign",
"properties": [
...
]
},
{
"name": "Replicate properties",
"type": "Job Action"
},
...
]

​ Finally, to route the review tasks to Workspaces, check the collaboration job definition and ensure the review task steps are assigned to Work Spaces as shown below. ​

{
"name": "Manual Review",
...
"actions": [
{
"name": "Create Task",
"type": "Job Task Assign",
"properties": [
...
{ "name": "Task Assign Portal", "value": "Work Spaces" },
...
]
},

Setup the template review form in Journey Manager

​ Making a decision about the success (or otherwise) of an application is an important aspect of application processing. While Workspaces doesn’t have native support for decision-making in the portal, this functionality can be achieved using the template decision form that is supplied with Workspaces. The template decision form is a Maestro form that can be extended to include any additional business logic you need, and includes the following sections: ​

  • A section for uploading documents from the review process.
  • A section for making the decision and adding justifications about the decision made.

​ The template form also has a callback mechanism on submit which passes the supporting information captured in the form to Workspaces, where it is displayed in the application timeline. ​

The instructions below explain how to add the template review form to Journey Manager, and configure it to be associated with the review task. ​

Add the review form to Journey Manager

​ To add the template review form to Journey Manager: ​

  • In Journey Manager, select Forms > Forms.
  • Click Import Form.
  • Click Browse then locate the template review form supplied with Workspaces, select the form file, and close the file browser dialog.
  • Click Upload.
  • Once the review form is imported, add Work Spaces as the associated form space.
    • Navigate to the form's dashboard.
    • Select the Spaces tab and click New.
    • Select Work Spaces from the dropdown.
    • Click Save. ​ If you need to rename the review form or change its form code: ​
  1. In Journey Manager, navigate to the form's dashboard.
  2. In the Form Details section, click the Form Display Name.
  3. Select the Details tab then update the Form Display Name and Form Code as required.
  4. Click Save. ​
Configure the collaboration job

​ To associate review tasks from the collaboration job with the template review form (added in the previous step): ​

  • In Journey Manager, select Services > Job Services.
  • Locate the collaboration job service that manages the workflow of the application that will be reviewed in Workspaces, and click the Edit icon for that service. Alternatively, you can click the service's name in the Service column.
  • Select the Job Definition tab.
  • Update the job definition, as required, to ensure review tasks are associated with the template review form as shown below. ​
{
"name": "Manual Review",
...
"actions": [
{
"name": "Create Task",
"type": "Job Task Assign",
"properties": [
{ "name": "Task Form Code", "value": "reviewtemplate" },
...
]
},

Note

Starting with Workspaces v19.05, all tasks are accessible in Workspaces. Accordingly, associating a task with a Workspaces portal is optional in Workspaces v19.05. ​

Server Errors

​ For information about server errors, see Workspaces API documentation. ​