Setting Preferred Device

Early Access

By default, push notifications will be sent to all devices registered devices associated with the user. TrustX provides functionality for the user to set the preferred device to receive the push notification so that only one device will receive a push notification based on user preferences.

This guide will cover the following use cases:

1. Show current preferred device info to the user.
2. Set current preferred device info.
3. Clear current preferred device info.

Custom Forms will be used to manage showing and setting preferred device information to the user. See Custom Data Forms for more information on configuring forms in the TrustX Backoffice.

Show Current Preferred Device

The 'IDS Get Preferred Device Info' activity will get current preferred device information for a given user. After retrieving the data, a Custom Data Form can be used to show this information to the user whether a preferred device is set or not.

Create Custom Data Forms

Show Preferred Device

The first Custom Form incorporates values that will be retrieved from the 'ID Get Preferred Device Info' activity in the Process Definition and display the preferred device information to the user.

1. Login to the Backoffice application and access the Integration Hub > Custom Forms.
2. On the Custom Forms landing page, click the 'New Custom Form' to open the Custom Form builder.

3. A sample JSON Custom Form can be found below:

{

    "title": {...},

    "components": [...],

    "continueButton": {...},

    "version": "1"

}

4. The Custom Form will be populated using variable substitution from data retrieved by the 'IDS Get Preferred Device Info' activity. For example, the device ID can be retrieved as follows:
   1. processVar - Accesses the process variables table.
   2. ._preferredDeviceInfo - Access the table of preferred device information.
   3. .id - Retrieves device ID from the _preferredDeviceInfo table.

No Preferred Device

If no preferred device information is set, the 'ID Get Preferred Device Info' activity will not return any information in the _preferredDeviceInfo table. As a result, it may be preferred to show a simple page or form to communicate this information to the user.

JSON Example:

{

    "title": {

        "values": {

            "en": "Preferred Device Info"

        },

        "isValid": true,

        "type": "title"

    },

    "components": [

        {

            "isValid": true,

            "type": "paragraph",

            "id": "paragraph",

            "label": {

                "values": {

                    "en": ""

                }

            },

            "values": {

                "en": "No preferred device set for user."

            },

            "index": 0

        }

    ]

}

Configure the Process Definition

1. After the Start event, add a 'Get User' activity to retrieve the Identity Store user.

2. The 'Get User' activity supports the following input parameters:

3. Connect an 'IDS Get Preferred Device Info' activity to the 'Get User' activity using the global connect tool.

4. The 'IDS Get Preferred Device Info' activity will return preferred device information based on the Identity Store user. It is also possible that no preferred device is set and will return no information.
5. The activity supports the following input parameters:

6. The activity also supports the following error boundary events.

7. Create a gateway that will manage the conditional logic between the two potential paths in the Process Definition.
8. After the gateway, add a new 'Custom Page' activity. This activity will be used to display the preferred device to the user.
9. Select the activity to expand the list of input parameter available. Set the Custom Form name and version.

The Show Preferred device activity represents the Custom Form.

10. Click the connecting arrow from the gateway to the Custom Form activity. Click the 'Spanner' icon representing the list of options and set the flow to 'Default'.

11. In the event that a preferred device is not set and no data is returned, the flow can be configured to return a message to the user using the Custom Form defined in the Create Custom Data Forms section above.
12. From the 'check device info' gateway, add a new 'Custom Form' activity to the Process Definition and connect them using the global connect tool.

The 'No preferred device set' activity represents the Custom Form.

13. This step will involve configuring a conditional expression that determines when the preferredDeviceInfo is empty.
    1. Select the sequence flow arrow connecting the gateway to the 'No preferred device set' Custom Form activity to open the right-side contextual menu.
    2. Expand the Condition option and create a new expression with the following condition expression: ${_preferredDeviceInfo == null}

14. Connect both Custom Form activities and each of the error and timeout boundary events to a Simple Decider activity.

Set Preferred Device

The 'IDS Set Preferred Device' activity can be used to set the current device used to complete the Process Instance as the preferred device for the given Identity Store User.

1. Add a 'Get User' activity to the beginning of the Process Definition, after the 'start' event.

2. The 'Get User' activity supports the following input parameters:

3. Select the activity to open the righthand contextual menu to identify the User using one of the available User ID fields.
4. After the 'Get User' activity, add the 'IDS Set Preferred Device' activity. This will set the current device used to complete the Process Instance as the current preferred device for that Identity Store User.

5. The 'IDS Set Preferred Device' activity supports the following input parameters:

6. The activity also includes the following error boundary events:

7. The Process Definition can be concluded with a 'Simple Decider' or by integrating a show preferred device flow following the process outlined in Show Current Preferred Device.
8. Example: A full set preferred device flow that includes showing the current preferred device to the user.

Clear Preferred Device

The 'IDS Clear Preferred Device' activity will clear the current preferred device of a given Identity Store User.

1. Similar to the Process Definitions outlined in Show Current Preferred Device and Set Preferred Device above, the first step involves getting the Identity Store User by adding a 'Get User' activity to the Process Definition.
2. After the 'Get User' activity, add an 'IDS Clear Preferred Device' activity.

3. When this Process Definition executes, the