Configuration of Robotic Desktop Automation (RDA) with your application
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 Robotic Automation Studio 8.0
This article assumes that you have successfully installed and configured Pega Robotic Automation Studio and Pega Robotic Automation Runtime. For more information, see Configuration of robotic desktop automation for Pega 7 applications. This article discusses the following topics:
- Desktop automation architecture overview
- Design principles
- Invoking automations from your Pega application
- Automating activities in Pega Robotics Studio
Desktop automations are designed and built in Pega Robotic Automation Studio. The compiled automations then run in Pega Robotic Automation 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 Robotic Automation 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 Robotic Automation 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, Robotic Automation 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 Robotic Automation Studio development environments:
- The automation identifier that is created in Robotic Automation 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 Robotic Automation 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.
- 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 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.
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.
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
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 Robotic Automation Studio 8.0 and later has a Robot Activity component. This component is based on the activity component that is a part of the Robotic Automation 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 Robotic Automation 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.