Web service actions

There are six actions within the Interact Web API Service, which are called directly fromusing the Blue Prism Object. Going through each of the actions in turn, the sections below explain how to use them in your automations.

All of the web API service actions should be called from the Utility - Interact API VBO in Blue Prism, and not directly from the web service.

Get Submission

The Get Submission action does a very similar action to the Get Next Item action when it retrieves the information from a queue.

To utilize the action, an action is added to your process and the Business Object selected, with the action set to Get Submission. There is only one input parameter which is the Submission ID as illustrated below.

The output parameters retrieves the contents of the Interact Form, using the submission ID into a collection.

One difference when the submission is retrieved using this methodology rather than the standard Get Next Item action is the formatting of Date elements. Using the Get Next Item technique the Date is returned in a Text format, whereas the Get Submission returns it as a DateTime format as below.

For a complete list of restrictions, see Interact Web API Service object restrictions.

You cannot use the Get Submission action unless you know the submission ID, as this is unique per submission it cannot be hardcoded into your automation. This must be retrieved using the Get Next Item action.

Get Form Schema

The Get Form Schema action gets a structure of an Interact Form in a collection allowing you to manipulate and then using the Create Submission action create an Interact Form either empty or partially created for a user to complete and submit.

There is only one input parameter which is the name of the Form within Interact that you are retrieving the structure for, as illustrated below.

The outputs parameters are similar to the ‘Get Submission’ action where the request status is returned along with a collection containing the fields.

The retrieved collection is a blank collection containing the structure of the Form.

The structure of the fields presented is in the same format as the Get Next Item format and therefore the Date element is requesting a Text data type to be submitted. The reason that Text type is used, is to support the multiple format Date element types within Interact, where the Date can be supplied in UK, US or International format.

Create Submission

There are four parameters that need to be defined within the Create Submission action.

These four parameters are as follows:

  • Username – This is the username of the Interact user that the submission will be created for.
  • Password – The password for this Interact user.
  • Form Name – The Form that will be created within Interact.
  • Fields – The values that will be set within the created submission.

To assist in creating a new submission, Get Form Schema can be used to retrieve the basic structure of the Form. This could then be populated with new data items and then created as a new submission for a user.

To create a submission, the fields and form schema must match that of the Form within Interact. Missing fields or an incorrect structure will end up creating a corrupt submission.

Once initiated the created submission will appear in the specified users Submission History as a submitted Form and will be added to the specified Blue Prism queue detailed in the Form construct.

The user whose credentials are used to create the new submission must be allowed to access the Form. So, the Interact Role which contains the Form must have the user specified in the user list.

There are no outputs parameters for the Create Submission action.

Edit Submission Field Value

The Edit Submission Field Value action, like all the other actions, is called from the object. There are several actions within the object which allow you to update specific field elements, these actions link directly to the element type that is used in the Interact Form.

The Field Name in the sections below is the Automation ID that was created within the Form designer.

Details for the different element types are described in the following sections.

Checkbox element (Single)

The Checkbox Edit Value is two different actions supporting use of both Single and Multiple Checkboxes. To update the values for a Single Checkbox, it is a simple text string that is submitted.

Checkbox element (Multiple)

For the Checkbox Edit Value (Multiple) again it is a simple text string that is submitted but using a comma separated string for the different values.

Date element

The Date element uses Text format to edit values in an Interact Form, this is to support the three different formats within the Interact Form. The Form will allow you to use these formats for dates:

  • DD/MM/YYYY – UK format;
  • MM/DD/YYYY – US format;
  • YYYY/MM/DD – International format.

If you have set the Interact Form to accept the International format for dates and you send the date back in either the UK or US format, the Interact Form will display an invalid data message.

Dropdown element (Single)

The Dropdown element, like the Checkbox element, supports two actions for the single and multiple entries. To update the values for a Single Dropdown, it is a simple text string that is submitted.

Dropdown element (Multiple)

For the Dropdown Edit Value (Multiple) again it is a simple text string that is submitted but using a comma separated string for the different values.

Number element

The Number element will accept either a number or a text being passed to it. Though the field type is a Text type you must supply a number using only the acceptable delimiters such as commas and decimal points. If text is sent back, the Interact Form will display a message regarding invalid data.

Radio group element

The Radio group element is like a single Checkbox or Dropdown element. The edited value is a single text field which includes the required updated value.

Table element

The Table element uses a collection to enable you to update the values. The collection must contain the same number of columns as the form field within the targeted form. Automation IDs must be used for the field names of the collection. The number of rows can be increased or decreased to accommodate the data being updated.

The Edit Table action overwrites the whole table as opposed to appending rows to an existing table.

Text element

The Text element requires a simple Text field being passed to it.

Time element

The Time element uses Text format to edit values in an Interact Form. You can supply the Time in one of two formats these being:

  • 03:00:00 PM; or
  • 15:00:00.

Both will return 3 o’clock in the afternoon in Interact.

Update Config

The Update Config action allows you to change the state of a field or a page within a submission. The inputs for the action are illustrated below. This example shows a field with the name of ‘security being set to a ‘mandatory’ state. The inputs are the Submission ID, the Automation ID of the field or the page name if you are changing the state of a page, a Type and the State inputs.

There are no outputs from the Update Config action.

The Type and the State inputs work together. For the Type there are two values that can be used:

  • 0 – to modify the state of a field
  • 2 – to modify the state of a page

If modifying the state of a field (Type set to ‘0’), then the State options are as follows:

  • 0 – changes the field to an optional state.
  • 1 – changes the field to a mandatory state.
  • 2 – changes the field to a read-only state.
  • 3 – changes the field to a hidden state.

If modifying the state of a page (Type set to ‘2’), then the State options are as follows:

  • 0 – changes the page to a shown state.
  • 1 – changes the page to a shown state.
  • 2 – changes the page to a shown state.
  • 3 – changes the page to a hidden state.

The Update Config is typically used in a human/Digital Worker collaboration scenario where the Form is dynamically updated as the human interacts with the automation. This is detailed separately showing how these Actions can be used to update a Form with input from a user.

The Paragraph elements are blocks of text that cannot be changed in a Form once the Form has been deployed. However, it is possible using ‘Get Form Schema’ to obtain the element ID of the Paragraph field, then using Update Config, hide or unhide them as the update progresses.

Update Status

The Update Status action, like the Update Config action, is typically used in a Human-in-the Loop scenario. The action allows you to move the submission between different Interact tabs.

The inputs for the action are illustrated below and are the Submission ID and the Status.

There are six statuses that can be applied to a submission, these are defined as follows:

  • 0 – Sets the status to Submitted and moves the submission to the History tab, if not already there.
  • 1 – Sets the status to Approved and moves the submission to the History tab, if not already there.
  • 2 – Moves the submission to the Awaiting approval tab.
  • 3 – Sets the status to Declined and moves the submission to the History tab, if not already there.
  • 4 – Moves the submission to the Draft tab.
  • 5 – Moves the submission to the Inbox tab.
  • 6 – Moves the submission to the Archived tab.

To see how to use this action in a typical scenario, see the section on human/Digital Worker collaboration.