Deploy and configure Journey Brokers

Overview

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

To setup Workspaces for Journey Brokers, follow these steps.

• Deploy the Workspaces module in Journey Manager.
• Prepare Workspaces for first use.

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.

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.

Optional: Create the Brokers Read Only View permission

When you deploy the Workspaces module, a default Journey Brokers permission called Brokers Read Only View is created. However, sometimes this permission may be missing; for example, if you upgrade your TJM environment from an older release without also upgrading the Workspaces module. Regardless of why this permission is missing, you can add it as follows.

Start by downloading the installed Workspaces WAR file.

1. Login to Journey Manager, and navigate to Forms > Form Spaces.
2. Locate the Work Spaces form space, and click the Module WAR File link. The Workspaces WAR file, called tm-workspaces.war, is downloaded.

Next, update the Workspaces WAR file to include the Brokers Read Only View permission. To complete this process, you need an archive tool that supports the WAR file format (such as 7-Zip).

info

The following instructions assume your archive tool supports in-place file modification; that is, you can modify a file in the archive without having to extract it. If your archive tool doesn't support in-place file modification, you need to extract the XML file from the WAR file before modifying it, and update the WAR file with the modified XML file afer modifying it.

To update the Workspaces WAR file, follow these steps:

1. In the tm-workspaces.war file, locate the WEB-INF/classes/db-config1.xml file and open it for editing.
2. In the db-config1.xml file, search for the <permissions> element in the <portal name="Work Spaces"> element, and add the permission <permission>brokers-read-only-view</permission> as shown in the following code sample:

   <portal name="Work Spaces">
       ...
       <permissions>
           ...
           <permission>brokers-read-only-view</permission>
       </permissions>
   </portal>

   note

   There's also a <permissions> element in the <roles> element. Don't modify that one.

3. Save the db-config1.xml file.

   tip

   If your archive tool allows in-place file modification, it may prompt you to update the tm-workspaces.war file when saving the db-config1.xml file. Accept this if offered.

4. Close the tm-workspaces.war file.

Finally, re-deploy the updated Workspaces WAR file; see Import a War file above.

Prepare for first use

Once the Workspaces module has been successfully deployed, a number of configuration steps are required to prepare Journey Brokers for use.

• Configure the Workspaces form space
• Create a role for Journey Brokers users
• Grant users access

Configure the Workspaces form 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.

Create a Brokers role

Journey Brokers users need a role with limited permissions to create and manage their own applications.

Follow these steps to create a new role for Journey Brokers users.

1. In Journey Manager, select Security > Roles.
2. Click New.
3. Enter a name and description for the new role. For example, you could use the name Brokers and description Journey Brokers users.
4. Ensure the Active checkbox is selected.
5. Click Save.
6. Switch to the Permissions tab, and select Work Spaces from the Spaces & Module dropdown list.
7. Select a permission in the Available list box and move it to the Assigned list box. The following Journey Brokers permissions are supported.
   • Invoke Fluent Functions: Select this permission if your Journey Brokers portal is configured to invoke Fluent Functions.
   • Brokers Read Only View: Select this permission if no other permission is applicable.

     note

     If the Brokers Read Only View permission is not available, you can add it; see Create the Brokers Read Only View permission above.

8. Click Save.

Grant user access

Journey Brokers 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, then click Save.
5. Select the Roles tab.
6. Ensure the role required to use Journey Brokers is assigned to the user account. You may have created this role in the previous section.
7. Click Save.

Develop and deploy your app

Once you have built the Journey Brokers client application (with the Applicant space), you need to deploy it in Journey Manager.

• For information about developing your client application, see Form Development.
• For information about deploying your client application in JM, see Form Deployment and Security.

Server Errors

For information about server errors, see Workspaces API.

Accessing Journey Brokers

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

https://YOUR_DOMAIN/workspaces/secure/app/brokers/

info

JM allows only one active Journey Brokers session per user. You can login to Journey Brokers 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.