You can use Pega Robotic Desktop Automation to add automation capabilities to your Pega 7 application. With Robotic Desktop Automation (RDA), you can create a unified desktop experience by automating routine tasks on the user’s desktop. Examples of common desktop automations include:
- Synchronizing all your desktop applications with a customer’s account information.
- Automatically launching or closing applications.
- Propagating updated account data from your Pega 7 application into one or more web or desktop applications.
The minimum requirements for building a robotic automation are:
- Pega 7.2.1 and Pega Support HFIX-28846
- Pega Robotics Studio 8.0
This article assumes that you have successfully installed and configured Pega Robotics Studio and Pega Robotics Runtime. For more information, see Configuration of robotic desktop automation for Pega 7 applications. This article discusses the following topics:
Desktop automations are designed and built in Pega Robotics Studio. The compiled automations then run in Pega Robotics Runtime on the local desktop. Automations are invoked directly from the Pega client through a REST service running in Pega Robotics Runtime. After receiving an invocation request, Pega Robotics Runtime is responsible for starting the automation, performing the automation logic, and returning an appropriate response to your Pega 7 \application.
The REST service inside Pega Robotics Runtime honors the cross-origin resource sharing (CORS) security model to determine whether to accept or reject incoming automation requests. Only requests from approved domains are accepted; non-approved domains are rejected. You can configure the list of approved domains in the RuntimeConfig.XML file. Invocation requests from other computers are also rejected.
For more information about the RuntimeConfig.xml file, see Runtime Configuration Settings XML File.
Because Pega 7 applications are hosted over SSL (HTTPS), and browsers do not allow an SSL application to make a call to a non-SSL service, the Robotics Runtime REST service must be SSL-enabled. To create an SSL REST service, Robotics Runtime uses (and includes) a CA-issued SSL certificate. The certificate points to localruntime.pega.com. A global DNS entry has been configured that resolves localruntime.pega.com to 127.0.0.1 or to localhost. This setting allows your SSL-enabled Pega 7 application to make secure invocations to the SSL-enabled local REST service.
All automations invoked through Pega 7 applications are executed synchronously. This means that your Pega 7 application waits for an automation to be completed before proceeding to the next step in the flow. For this reason, you should design automations that are relatively short and fast, and have a single focus or purpose. As a best practice, break down larger blocks of functionality into smaller automations to avoid the appearance of an unresponsive or slow application.
Automations can take input such as a customer name and account number, and return output, such as the amount of a transaction. Configuring data input and output is discussed in detail below. At this time, only scalar Pega 7 Platform properties can be passed between your Pega 7 application and an automation. Hierarchical structures and lists of data are not yet supported.
When designing an automation, you must coordinate the following items between Pega 7 Platform Designer Studio and Pega Robotics Studio development environments:
- The automation identifier that is created in Robotics Studio and uniquely identifies your automation
- The fully qualified class name of the case that will be invoking the automation (for example, MyOrg-MyApp-Work-OpenTicket)
- The format of the data as it is received by the automation
- The required format of any data that is returned from an automation to your Pega 7 application
You can invoke automations from any flow action that runs as part of a standard flow, modal dialog box, or overlay. The automation identifier assigned to your automation in Robotics Studio must be referenced on the flow action. Automations can be invoked from either a pre-action or post-action. The decision of where to invoke your automation depends on your business requirements.
Invoke a preprocessing automation when you want to fetch data from an automated process that will ultimately be rendered on the next immediate (or future) UI screen. The preprocessing actions are performed in the order shown on the Flow Action rule form.
Preprocessing section of the Flow Action rule form
Preprocessing actions are performed in the following sequence:
- A data transform is applied.
- An activity is run.
- Robotic automation is invoked.
- The UI is rendered.
Invoke a postprocessing automation when you want to collect information from your user that will ultimately be used as input into your automation process.
Postprocessing section of the Flow Action rule form
Postprocessing actions are performed in the following sequence:
- The user submits the form.
- Input data is validated on the server.
- Robotic automation is invoked.
- The automation returns, and the clipboard is updated with return values.
- Clipboard data is revalidated on the server.
- A data transform is applied.
- An activity is run.
- The flow action is submitted and completed.
Passing input data to automations
A subset of properties defined on your case is automatically bundled with each automation invocation request. The exact set of properties to include is governed by the set of relevant property records defined for your case type. You can change the set properties that are bundled in each automation request by modifying the relevant records defined for your case type.
All fields created in the Case Designer or Data Designer are automatically marked as relevant. However, relevant records can be curated and modified for your specified case from the Relevant Records landing page (Designer Studio > Application > Inventory > Relevant Records).
Each relevant record property is accompanied by its current clipboard value. Only scalar properties are included in your invocation request. Page properties, page groups, and page lists are not supported at this time.
Retrieving output data from automations
After an automation is invoked, the automation uses the case data included in the request. For example, an automation could use an account number to update a customer account in a mainframe system. The invoked automation keeps track of the incoming values of all properties. If any of these values change during execution, the modified values are automatically included in the response back to your Pega 7 application. Updated property values are automatically posted back to the clipboard page that your flow action is running against. If an automation is invoked as a pre-action, the values are posted to the clipboard before the associated section is rendered. If the automation is invoked as a post-action, the clipboard is updated as part of the flow action submission process.
Depending on the validation criteria defined on your flow actions, your case processing can halt if an automation returns invalid data. Check your automation logic and ensure that your automations are returning valid data to your Pega 7 application.
Automation invocation responses include a return code as well as a status message that reflects the success or failure of the automation. The return statuses are used for informational purposes and do not affect the processing flow of your Pega 7 application. An automation developer can return one of the following messages:
The automation ran to completion and did not encounter any errors.
Completed with errors
The automation ran to completion but encountered an error that might have prevented the successful processing of the intended automation task.
For example, this error can occur if the automation is unable to look up a specific customer account because of an incorrect account ID.
Actual use of this message is dependent on the automation and implementation. Communication of these errors to the end user is handled before the automation is completed by using, for example, a Windows dialog box or an overlay.
Did not complete
This is the default return status. The automation developer is required to overwrite this return code on exiting the automation. If this code is displayed, most likely an error occurred in the automation that prevented a clean run.
However, some error conditions affect your case processing flow. Your Pega 7 application automatically handles environmental errors, including:
The Pega Robotics Runtime is unavailable.
The Pega Robotics Runtime is available, but no package is loaded.
The Pega Robotics Runtime is available, but the specified automation cannot be found.
The automation was invoked but timed out (the time-out is currently set to 60 seconds).
The automation was invoked but was canceled.
If any of these scenarios is detected, a page message that describes the problem is displayed automatically. The user can do either of these actions:
- Quit (cancel)
- Ignore the message and continue the workflow
An environmental error that is displayed as a page message
When one of these environmental errors is detected on a postprocessing automation invocation, the on your flow action. button labels
button label changes to . The user must decide whether to quit or continue their workflow. Button labels do not change if an environmental error is detected on a preprocessing automation invocation. In addition, button labels do not change if the default case action buttons are overridden by selecting
You can also add custom error-handling logic by specializing the
pyProcessAutomationFailure extension point activity. For example, you might want to send an email to your case administrator or technical support team whenever an automation request fails.
Pega Robotics Studio 8 has a Robot Activity component. This component is based on the activity component that is a part of the Robotic Studio Interaction Framework. This component is used most similarly to an activity that does not require an active interaction.
Configuring the component
To configure the Robot Activity component, place the component in a Global Container. An Interaction Manager component is not required. The property grid contains these items:
- ActivityName – The activity name is a string used to identify the automation. This is the automation identifier that is referenced in the Pega flow action as the robotic automation name.
- ClassName – The Pega case type that supplies data to the automation. The class name is verbally communicated between the Pega developer and the automation developer, for example: MyOrg-MyApp-Work-OpenTicket or MyOrg-MyApp-Work-OpenTicket-OpenSubTicket.
- Fields – After a class name is provided, Pega Robotics Studio can programmatically retrieve a list of all available relevant record fields that can be used by automations. An automation developer can choose a subset of these fields to appear as properties on the Robot Activity component.
The following example shows a fully configured Robot Activity component.
A Robot Activity component
The numerals in the image above highlight the following items:
- The Property Grid shows the Pega properties as described above
- The Property Grid has the Fields (Collection) opened. This is the Selected Fields dialog box. Open the Selected Fields dialog box by selecting the property and clicking the ellipsis button, as shown in the following figure:
Ellipsis button in the Properties dialog box
- The Object Inspector shows the properties that have been selected on the Selected Fields dialog box. Changes to the Selected Fields dialog box are reflected after that dialog box is modified and submitted. You can place these properties on an automation surface.
Using the component
A Robot Activity component contains an ActivityStarted event. This event starts when a Pega 7 application flow is configured to invoke an automation with the corresponding name. You can only access an activity’s properties when the activity is active—from the start of the ActivityStarted event until its completion.
An example of an ActivityStarted event
As discussed in the error handling section, call the SetCompletionStatus method at the end of the processing of the activity to return the appropriate result. The return status is used for informational purposes and does not affect the processing flow of your Pega 7 application. You can also assign a return code and message when calling the SetCompletionStatus method to communicate status with the application. The return code can identify the error type for quick reference and is arbitrary. You can customize the return message as needed. Use the Message Manifest to hold the strings.