Version: 20.05

Deploy and configure Workspaces

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

Note

It is assumed you are logged in to your JM environment using an account with sufficient administrative privileges to perform these instructions; for example, the System Manager role. ​

The steps required to setup your Workspaces portal include: ​

The following instructions explain how to complete these steps. ​

Deploy Workspaces in Journey Manager

​ Workspaces module (API) is distributed as a WAR file that is deployed on Journey Manager as follows:

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

Note

Starting from Journey Manager v20.05, Workspaces war file comes bundled with Journey Manager installation file as an optional package. To install the Workspaces module (API), install it directly from the Journey Manager installation file. Upon successful deployment, a new form space called Work Spaces appears on the Form Spaces page. ​

Note

If you don’t see the new 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 environment, locate the file called {warfilename}.war.FAILED_ and send it to workspace@avoka.com for assistance. ​

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. ​

Link an organization

​ 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. ​