Skip to main content

Version: 23.10

Deploy and configure Journey Workspaces

caution

23.10.4 introduced important security changes to the 23.10 release. If you are upgrading to 23.10 from any 23.4.x version, you must upgrade your application to 23.10.4. To learn more, see Upgrade from 23.10.x to 23.10.4.

Overview​

Journey Workspaces requires the Workspaces module to be setup in your Journey Manager (JM) environment. This topic explains how to setup the Workspaces module for Journey Workspaces.

To setup Workspaces, follow these steps:

  • Deploy the Workspaces module in Journey Manager.
  • Prepare Workspaces for first use.
  • Configure a collaboration job.
note

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

Deploy the Workspaces module​

The Workspaces module, which includes 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 and later releases, the Workspaces WAR file no longer contains the Workspaces client application.

There are two ways to deploy the Workspaces module.

  • Journey Manager installer option: Recommended. The Workspaces module is included in the Journey Manager installer as an optional package (Modules and Spaces > Form Spaces > JM Work Space). This means you can deploy the Workspaces module during a Journey Manager installation or upgrade.

    info

    The JM installer doesn't support a standalone installation of the Workspaces module.

  • Manual import: If you need to deploy the Workspaces module manually, download the relevant Workspaces WAR file and import 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, locate the file called {warfilename}.war.FAILED, and raise a support request (login required) attaching this file.

Import a WAR file​

If you need to import a Workspaces WAR file into Journey Manager, follow these steps:

  1. In Journey Manager, select Forms > Form Spaces.
  2. Click Import WAR.
  3. Click Choose File, then use the file dialog to locate and select the Workspaces WAR file to be imported.
  4. To complete the WAR file deployment, click Import. A message is displayed on the Form Spaces page indicating whether the WAR file deployment was successful.

Prepare 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
  • Link an organization to the Workspaces space
  • Grant users access to the Workspaces space

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.

  1. In Journey Manager, select Forms > Form Spaces.
  2. 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.
  3. Select the Space tab.
  4. Update the domain part of the Context Path URL to be the same as your JM domain.
  5. Select a Security Manager to be used for Workspaces.
  6. Select the Authentication Mode matching the level of authentication required to access Workspaces.
  7. If you need to be able to modify the Work Spaces space at runtime, select the Content Editable checkbox.
  8. Select Default Forms Space to route all job step actions to the new Work Spaces space by default.
info

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.

note

If you're presented with an HTTP 403 Forbidden status code when you attempt to access Workspaces, you may need to add the CSRF token to the Workspaces portal pages. For details, see HTTP 403 Forbidden status code when attempting to access Workspaces after upgrading from 21.05 or earlier.

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.

  1. In Journey Manager, select Forms > Organization.
  2. Locate your organization, then click the Organization Name or Edit icon for your organization.
  3. Select the Spaces tab.
  4. If Work Spaces is in the Available Spaces list, select it and click > to move it to the Assigned Spaces list.
  5. Click Save.

Grant user access​

Workspaces users must be assigned to the Work Spaces space before they can login and access its features.

Follow these steps to grant users access to the Work Spaces space.

  1. In Journey Manager, select Security > User Accounts.
  2. 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.
  3. Select the Spaces tab.
  4. If Work Spaces is in the Available list, select it and click > to move it to the Assigned list.
  5. Click Save.
  6. Select the Roles tab.
  7. Ensure the role required to use Workspaces (Work Spaces Staff) is assigned to the user account.
  8. Click Save.
info

Starting with Workspaces 19.05, JM roles can be assigned to a Space attribute in the 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.

Develop and deploy Workspaces​

caution

Temenos Journey Manager (TJM) 21.11 introduced changes to the Workspaces REST API that are incompatible with earlier releases. Consequently, the Workspaces 19.11 application can no longer be used with a TJM 21.11 or later instance, and you must upgrade your Workspaces application to an Open UX form. To learn more, see Workspaces release compatibility > Breaking changes in TJM 21.11.

Once you have built the Workspaces client application, you need to deploy it in Journey Manager.

Configure a 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 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 which 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.

Replicate properties service​

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:

  1. In Journey Manager, select Services > All Services.
  2. Click Import.
  3. Click Browse then locate the "Replicate properties" file, select the file, and close the file browser dialog.
  4. 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.

  1. In Journey Manager, select Services > Job Services.
  2. 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.
  3. In the Job Definition, add a "Replicate properties" action after each review task. This causes 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" },
            ...
        ]
    },

Template review form​

Making a decision about the outcome (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 following instructions explain how to add the template review form to Journey Manager, and configure it to be associated with the review task.

To add the template review form to Journey Manager:

  1. In Journey Manager, select Forms > Forms.
  2. Click Import Form.
  3. Click Browse then locate the template review form supplied with Workspaces, select the form file, and close the file browser dialog.
  4. Click Upload.

Once the review form is imported, add Work Spaces as the associated form space:

  1. In Journey Manager, navigate to the form's dashboard.
  2. Select the Spaces tab and click New.
  3. Select Work Spaces from the dropdown.
  4. 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 job definition​

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

  1. In Journey Manager, select Services > Job Services.
  2. 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.
  3. Select the Job Definition tab.
  4. 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" },
                ...
                ]
        },
info

Starting with Workspaces 19.05, all tasks are accessible in Workspaces. Therefore, associating a task with a Workspaces portal is optional in Workspaces 19.05 and later releases.

Server Errors​

For information about server errors, see Workspaces API.

Accessing Workspaces​

To access Journey Workspaces, open your preferred supported browser and enter the Context Path URL for your Journey Workspaces portal. For example:

https://YOUR_DOMAIN/workspaces/secure/app/workspaces/
info

JM allows only one active Journey Workspaces session per user. You can login to Journey Workspaces on multiple browsers, but only the first browser in which you perform an action will be successful. The second and subsequent browsers in which you attempt an action will report an HTTP 403 Forbidden status code.