Interact Controller EER4 - February 2021

Interact Controller	EER4	The release requires Interact Controller to be this version.
Blue Prism	6.4.3a	The release is compatible with the specified version of Blue Prism version and above.

This release note is for the Evolution Edition Release 4.1, 4.2 and 4.3 releases of Blue Prism Cloud Interact (Interact) Controller.

For further information regarding Interact and the Interact Controller please see the Interact User Guide.

Important notices

Ensure you have reviewed the upgrade notices for this release.

Release notes

Enhancements

This is the second formal release of the Interact Controller Object.

Blue Prism Cloud Interact provides new and existing Blue Prism users with a collaboration interface for an end users interaction with their digital workforce within a business process. Initiate, verify, receive and authorize varied work related to your business processes. In addition, Blue Prism Cloud Interact reduces the skill criteria required by allowing users to create dynamic web interfaces by using the no-code form designer.

To support the human/digital worker collaboration capabilities of Blue Prism Cloud Interact, an Object has been developed which automation developers can call from their processes. This Object enables developers to update fields in an Interact Form by allowing the changes made by the digital worker to be fed back via the Interact API.

Fixes and minor improvements

This release of the Interact Controller Object resolves the following issues:.

• Individual actions to handle different field elements.
• Inclusion for support of Multiline, Radio Groups, Checkboxes and Select elements.
• Added new Raise Submission functionality.

Upgrade notices

Install the required Blue Prism artifacts for Interact Controller

To install the Object import the Utility - BPC - Interact Controller v2.9 release file into your version of Blue Prism. The release contains the following artefacts:

• Utility – BPC – Interact Controller
• Utility – HTTP
• Utility – JSON
• Utility – Strings
• Four environmental variables

The release is available to download from the Blue Prism Product Portal – login required. Unzip the file before importing.

Installation

Within the installation package there are two artefacts:

• This document
• A Blue Prism Release for BP version 6.4.3a.

To install the Object import the ‘bprelease’ file into your version of Blue Prism. The release contains the following artefacts:

• Utility – BPC – Interact Controller;
• Utility – HTTP;
• Utility – JSON;
• Utility – Strings; and
• Four Environmental Variables.

After the release has been installed see the configuration Section on how to configure and utilize the Object.

Configuration

The Interact Controller is a Business Object that has been produced by Blue Prism Cloud to simplify the interaction between Interact and Blue Prism Design Studio.

The Business Object utilizes Environmental Variables to control its operation. It makes available a number of actions which can be provided with a data item as an input along with the submission ID (Request ID) to identify the Interact submission and field that it will be updating. There are no outputs from the Interact Controller though there is exception handling should an error occur during processing.

There are four Environmental Variables that need to be established to operate the Interact Controller, these are:

• EV-Interact-API-Key;
• EV-Interact-API-Username;
• EV-Interact-API-Password; and
• EV-Interact-API-URL.

The first three of these Environmental Variables are obtained when the API is set up within Interact.

The image below shows the API that has been established for our example process.

The same API can be used by multiple processes.

The last Environmental Variable the ‘EV-Interact-API-URL’ is the URL used to access the Interact Web Server.

The Environmental Variables are set in the System area of Blue Prism as illustrated below.

Data Items are then set changing the exposure to the ‘Environment’ setting and selecting the appropriate Environment Variable from the dropdown.

Operation

The Interact Controller butoperates in on a per element basis so that the developer can update specific fields whilst ignoring others that do not need updating. It operates for each element in a similar way which is:

• Obtaining a Bearer Token Header to enable authentication with the Interact API service.
• Obtain the process submission details using the Request ID.

• Then updating the process submission using the Request ID and the data item fed into the Interact Controller.

Bearer Token

The API connection is used to get bearer authentication from Interact. Bearer authentication is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “bearer authentication” can be understood as “give access to the bearer of this token.” The Bearer Token is a cryptic string, usually generated by the server in response to a login request

This Bearer Token is then used as authorization to retrieve and update information in Interact.

The Bearer Token has a limited time span, which is 15 minutes. If the retrieval and update doesn’t complete within this period, a new Bearer Token will be required.

Get Process Submission by Request ID

This part of the business object uses the Bearer Token as authentication and the Request ID to retrieve from Interact the submission data and form structure. This is returned in a raw JSON format.

Update Process Submission by Request ID

The final part of the business object takes the raw JSON that has been retrieved, reformats it into an acceptable JSON, updates the value that is being requested to be changed using the Data item that has been submitted and then posts the updated information back into Interact.

Configuring the Interact Controller

To utilize the Interact Controller in your automations. Add a new Action to your process and select from the drop down the ‘Action’ from the ‘Utility – BPC – Interact Controller’ that you wish to use.

There are 12 actions that can be called from the Object. These are:

• Raise Submission to Inbox
• Update Checkbox Single and Multiple
• Update Date
• Update Email Address
• Update Multiline
• Update Number Field
• Update Password
• Update Radio Group
• Update Select
• Update Text Area
• Update Text Field
• Update Time

The parameters that need to be configured are illustrated in the following sections for each of these actions.

The ‘_requestId’ is the key parameter to link the update to the Interact submission ID.

Object Actions

The following sections detail the Object actions and their associated parameters:

• Raise Submission to Inbox
• Update Checkbox Single and Multiple
• Update Date
• Update Email Address
• Update Multiline
• Update Number Field
• Update Password
• Update Radio Group
• Update Select
• Update Text Area
• Update Text Field
• Update Time

A few considerations should be adhered to when using the actions.

• When submitting a form with hidden fields, a value must be sent back to the hidden fields. Since there is not a way to find out whether the field is hidden or not in the JSON, default values are given to blank fields that are not checkboxes, radio buttons and select boxes. The following values are sent by defaults from the object:
  • Text Field – “Default”
  • Text Area – “Default”
  • Password – “Default”
  • Date – “0001/01/01”
  • Time – 00:00:00
  • Number – 0
• If you submit a form with hidden file upload and image upload that have empty values, this will throw also an error and will not allow any other fields to be updated. These fields must be populated even when hidden.

Raise Submission to Inbox

This action creates a new submission in an individual’s inbox within Interact, this could be the existing user or an alternative user. Raising a submission puts the submission in the inbox but does not submit the submission to Blue Prism for processing.

To raise a submission, a submission ID is required as an input to this action. Therefore, you can’t raise a new submission, it is moving an existing submission either back to the original submitter or a new submitter for the next part of the process.

The action itself does not require field values as an input. It just takes the existing submission and places in the user’s inbox, for them to update and resubmit as required.

You can update values to a submission first, using update actions, and then use raise submission to send it to another user.

• Inputs
  • User ID – this is the User ID of the person who’s inbox the submission is going to. This information is available is the Users settings when logged into Interact as an administrator. It has to be retrieved manually, there is no API call to retrieve this information.
  • Request ID – current submission ID. Retrieved manually or from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
• Outputs
  • o New Request ID – the new ID of the submission after being moved to user’s inbox.

The image below displays the properties of the Raise Submission to Inbox action.

Update Checkbox Single and Multiple

The update Checkbox Single and Multiple action allows the digital worker to update checkbox elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – this matches to the ‘Name’ value within the Interact form designer that is used to recognize the element. This is not the ‘Label’ field which is a title.
  • Field Value – the new value for the element being updated within the Interact submission. When updating multiples, the values should be separated by a comma. This is not free text but must match the values you set in the Interact form designer.

The image below displays the properties of the Checkbox Single and Multiple action.

Update Date

The update Date action allows the digital worker to update date elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.
  • Field Value – the new value, which is a text value, for the element being updated within the Interact submission and must be in the format ‘YYYY/MM/DD’.

The image below displays the properties of the Date action.

Update Email Address

The update Email Address action allows the digital worker to update Email elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.
  • Field Value – the new value for the element being updated within the Interact submission.

The image below displays the properties of the Email action.

Update Multiline

The update Multiline action allows the digital worker to update Multiline, or table elements within a specified submission.

When updating a Multiline element, a collection is required. This collection is called from the Table Replacements collection. The Multiline collection must match the Multiline element that is configured in the Interact Form.

The following applies:

• Multiline elements can be updated if an input is sent to the Multiline replacements collection.
• When defining the Multiline in the form designer within Interact, you need to ensure that the Multiline columns have different names.
• The collection you are sending in must match the columns of the Multiline Table Replacements collection.
• Name (text) is the “name” of the field, not the label. This is unique for each field. A label is not necessarily unique.
• The values (Table Replacement collection):
  • Each field in this collection must have the same name as the columns on the Multiline.
  • Each row represents a row of the Multiline to update. The values are free text.
• Empty Multiline elements cannot be updated. Only Multiline elements that have values in them already can be updated.
• Any values sent override the whole Multiline. So, if the current Multiline has 3 rows, and the values input collection has 2 rows, the previous Multiline will be overridden with these 2 rows.
• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Table Replacements – this is the collection with the new data that will be entered into the Multiline element within the designated Interact submission.

The image below displays the properties of the Multiline action.

The image below illustrates the Replacements Collection with a Multiline element defined.

The Multiline or value collection is illustrated below.

These image directly above correlate to the following image, which is the Interact form from where the Multiline element has been called from. The Name of the element, red box, matches the name within the Replacements Collection, which calls the Value collection. The columns names, green boxes, are defined within this Value collection, that match the column names in this collection.

Update Number Field

The update Number action allows the digital worker to update Number elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.
  • Field Value – the new value for the element being updated within the Interact submission.

The image below displays the properties of the Number action.

Update Password

The update Password action allows the digital worker to update Password elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.

  • Field Value – the new value for the element being updated within the Interact submission.

The image below displays the properties of the Password action.

Update Radio Group

The update Radio Group action allows the digital worker to update Radio Group elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.
  • Field Value – the new value for the element being updated within the Interact submission. This is not free text but must match the values you set in the Interact form designer.

The image below displays the properties of the Radio Group action.

Update Select

The update Select action allows the digital worker to update Select elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.
  • Field Value – the new value for the element being updated within the Interact submission. This is not free text but must match the values you set in the Interact form designer.

The image below displays the properties of the Select action.

Update Text Area

The update Text Area action allows the digital worker to update Text Area elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.
  • Field Value – the new value for the element being updated within the Interact submission.

The image below displays the properties of the Text Area action.

Update Text Field

The update Text action allows the digital worker to update Text elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.
  • Field Value – the new value for the element being updated within the Interact submission.

The image below displays the properties of the Text action.

Update Time

The update Time action allows the digital worker to update Time elements within a specified submission.

• Inputs
  • Request ID – the submission ID. Retrieved from the queue item.
  • Key – the API key generated during setup of the API, configured as an environment variable.
  • Username – for the API configured, configured as an environment variable.
  • Password – for the API configured, configured as an environment variable.
  • URL – the URL to the web server where Interact is installed, configured as an environment variable.
  • Field Name – the name given within the Interact form that is used to recognize the element.
  • Field Value – the new value for the element being updated within the Interact submission This must be a text value and in the format ‘hh:mm:ss’.

The image below displays the properties of the Time action.