Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Configuration of attended automations with your Pega application

Updated on March 30, 2023

You can use Pega Robotic Automation to add automation capabilities to your Pega 8 application. Pega Robotic Automation consists of Pega Robot Studio and Pega Robot Runtime. With Pega Robot Studio, you can create a unified desktop experience by automating routine tasks on the user’s desktop. Pega Robot Runtime provides an environment for executing the automations that you create with Pega Robot Studio. 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 8 application into one or more web or desktop applications.

The minimum requirements for building a robotic automation are:

  • Pega 8.x
  • Pega Robot Studio 19.1

This article assumes that you have successfully installed and configured Pega Robot Studio and Pega Robot Runtime. For more information, see Configuring Pega Robot Manager 6 for Pega Platform 7.4. This article discusses the following topics:

Desktop automation architecture overview

Desktop automations are designed and built in Robot Studio. The compiled automations then run in Robot Runtime on the local desktop. Automations are invoked directly from the Pega client through a REST service running in Robot Runtime. After receiving an invocation request, Robot Runtime is responsible for starting the automation, performing the automation logic, and returning an appropriate response to your Pega 8 application.

Automation security

The REST service inside Robot 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.

Because Pega 8 applications are hosted over SSL (HTTPS), and browsers do not allow an SSL application to make a call to a non-SSL service, the Robot Runtime REST service must be SSL-enabled. To create an SSL REST service, Robot Runtime uses (and includes) a CA-issued SSL certificate. The certificate points to A global DNS entry has been configured that resolves to or to localhost. This setting allows your SSL-enabled Pega 8 application to make secure invocations to the SSL-enabled local REST service.

Design principles

All automations invoked through Pega 8 applications are executed synchronously. This means that your Pega 8 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 8 Platform properties can be passed between your Pega 8 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 8 Platform Designer Studio and Pega Robot Studio development environments:

  • The automation identifier that is created in Robot 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 8 application

Invoking automations from your Pega 8 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 Robot 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.

Preprocessing automations

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.

Pre-processing section in the Flow Action rule form
Pre-processing section in the Flow Action rule form
Pre-processing actions are performed in the following sequence:
  1. A data transform is applied.
  2. An activity is run.
  3. Robotic automation is invoked.
  4. The UI is rendered.

Post-processing automations

Invoke a post-processing automation when you want to collect information from your user that will ultimately be used as input into your automation process.

Post-processing section of the Flow Action rule form
Post-processing section of the Flow Action rule form

Post-processing actions are performed in the following sequence:

  1. The user submits the form.
  2. Input data is validated on the server.
  3. Robotic automation is invoked.
  4. The automation returns, and the clipboard is updated with return values.
  5. Clipboard data is revalidated on the server.
  6. A data transform is applied.
  7. An activity is run.
  8. 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 8 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 8 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 8 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 8 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
An environmental error that is displayed as a page message
An environmental error that is displayed as a page message
When one of these environmental errors is detected on a postprocessing automation invocation, the Submit button label changes to Ignore and continue. 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 Customize the action section button labels on your flow action.

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.


Automating activities in Robot Studio

Robot Studio 19.1 and later has a Robot Activity component. This component is based on the activity component that is a part of the Robot 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, Robot 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
A Robot Activity component

The numerals in the image above highlight the following items:

  1. The Property Grid shows the Pega properties as described above
  2. The Property Grid has the Fields (Collection) opened. This is the Selected Fields dialog box. Open the Selected Fields dialog box by selecting the Fields property and clicking the ellipsis button, as shown in the following figure:


Ellipsis button in the Properties dialog box
Ellipsis button in the Properties dialog box


  1. 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 8 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.


ActivityStarted event

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 8 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.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us