Although Appian RPA is currently available only for Appian Cloud sites, we understand that customers may be interested in using its capabilities in their self-managed environments. This page describes how a hybrid configuration for Appian RPA works, how to set it up, and how to use robotic tasks in your applications. We've also included tips for maintenance.

What is a hybrid configuration?

In the context of Appian RPA, a hybrid configuration refers to the connection between a customer's self-managed Appian site and a separate Appian Cloud site, where Appian RPA is available.

Customers continue to build and deploy apps in the environments they're used to, while the robotic tasks are created and executed in the Appian Cloud. The two environments are integrated using an HTTP connected system. With the connected system, business applications can communicate with robotic tasks in the customer's new Appian Cloud environment. The connected system enables you to execute robotic tasks and retrieve results.

To get started, you'll need to do some setup steps for the two environments to communicate. Developers will also need to use different design patterns to integrate Appian RPA into their applications.

Setting up Robotic Workforce Manager

Appian's Robotic Workforce Manager (RWM) solution provides you with visibility into automations across your business, including requests for new automations, automations in production, and execution results. RWM leverages Appian RPA's APIs to initiate these actions and retrieve data automatically, so you don't need to set up additional objects or processes to accomplish those routine tasks. Instead, the solution streamlines management for you.

To set up RWM, you'll need to complete tasks on your Appian Cloud site and your self-managed site.

Cloud site tasks

Create a service account for RWM

You'll need to create a service account in your Cloud environment to authenticate with RWM.

1. In the Appian Cloud environment, open the Admin Console.
2. Click API Keys under the Authentication menu.
3. Click Create.
4. In the Create New API Key dialog, add a Description for the key.
5. Click Create Service Account to create a new service account to associate with this API key.
6. In the Create Service Account dialog, type a name for the service account and click Create.
7. Once the account is created, you'll return to the Create New API Key dialog. Click Create to complete the process.
8. The API key is shown. Copy this value now—you won't have another chance to view it.

You'll use this API key when you set up the connected system in RWM.

Self-managed site tasks

Install RWM

In your self-managed environment, install RWM to manage your robotic tasks.

As part of the RWM package, you'll find an RWM connected system you can use to authenticate with Appian RPA in the Cloud environment. You can also use this connected system object to create integrations to use in your applications.

Learn more about Robotic Workforce Manager (RWM).

Set up RWM connected system

The RWM application contains a connected system object you can use to establish a connection with Appian RPA based in the Cloud site.

1. In the RWM application, open the RWM_AppianRPA connected system object.
2. In the Authentication menu, select API Key and add the following values:
   • Send As: Choose Header.
   • Header Name: Type Authorization.
   • Value: Paste the API key associated with the service account you set up in the Cloud site.
3. Click Save.

These are the only RWM setup steps you need to complete as part of the hybrid configuration, but there are additional steps to finish setting up the RWM solution. Learn how to populate RPA vendor details and finish other RWM setup steps in the RWM documentation.

Using RPA in your applications

To use RPA in your applications, you'll need to create a few more design objects. Once you create the objects listed in this section, refer to the Execute robotic tasks synchronously from process models design pattern below for guidance on how to integrate robotic tasks into your applications.

You'll need to create these objects on your Appian Cloud site and your self-managed site.

Appian Cloud site tasks

Create a service account

First, create another service account in your Cloud environment to authenticate with the Appian RPA connected system you'll create in the next step. You'll likely want this user to be different from your RWM service account to help you manage security of what this user can accomplish. Consider having one service account per application.

1. In the Appian Cloud environment, open the Admin Console.
2. Click API Keys under the Authentication menu.
3. Click Create.
4. In the Create New API Key dialog, add a Description for the key.
5. Click Create Service Account to create a new service account to associate with this API key.
6. In the Create Service Account dialog, type a name for the service account and click Create.
7. Once the account is created, you'll return to the Create New API Key dialog. Click Create to complete the process.
8. The API key is shown. Copy this value now—you won't have another chance to view it.

Create an Appian RPA connected system and integration rules

To execute a robotic task or retrieve its results on the self-managed site, you'll need to create corresponding integrations in the Cloud site. To get started, first you need to create an Appian RPA connected system.

1. In your Appian Cloud site, open the Appian Designer.
2. Open the application where you want to use Appian RPA.
3. Click NEW > Connected System.
4. Select Appian RPA as your template.
5. Enter a Name and Description for the connected system.
6. In the API Key field, paste the API key associated with the service account you set up in the previous section.
7. Click Create.

You'll use this connected system to create integrations for the robotic tasks you want to integrate in your applications.

Create web APIs

The self-managed site will call the Appian RPA integrations using web APIs, so you'll need to set those up on the Appian Cloud site.

1. In your Appian Cloud site, go to the Appian Designer.
2. Click New, and then click Web API.
3. Select Create from scratch.
4. Enter a name for the web API. This name is displayed only to Appian developers.
5. Select an HTTP method that corresponds to the type of integration rule you're using. For example, use POST to execute a robotic task or GET to retrieve the results of an execution.
6. Enter an endpoint for the web API. You'll use these endpoints in the integrations you create from the HTTP connected system you set up in the self-managed site.
   • Note: This is used as part of the web API's URL to identify it and will be seen by end users and in log files for network devices and servers. The combination of the HTTP method and endpoint must be unique across all web APIs in the system.
7. Click Create.

You should have a web API for each Appian RPA integration you created. The integrations on the self-managed site will correspond to these web APIs, so you should set them up to call the appropriate integration rules on the Cloud site. Learn more about web APIs.

Self-managed site tasks

Create HTTP connected system and integrations

To communicate with the integrations on the Appian Cloud site, you'll need to configure an HTTP connected system on the self-managed Appian site.

1. In your self-managed environment, open the Appian Designer.
2. Open the application where you want to use a robotic task.
3. Click NEW > Connected System.
4. Select HTTP as your template.
5. In the Base URL field, put the URL for your Appian Cloud site followed by /suite/webapi. For example: https://www.example.com/suite/webapi/.
6. In the Authentication menu, select API Key and add the following values:
   • Send As: Choose Header.
   • Header Name: Type Authorization.
   • Value: Paste the API key associated with the service account you set up in the Cloud site.
7. Click Create.

If you want to create multiple service accounts or API keys, you can use these instructions to create a connected system to integrate the two environments.

Use this connected system to create HTTP integrations that point to the web API endpoints you set up in the Cloud site.

Deploy CDTs

Next, you need to export the relevant CDTs from your self-managed site and import those to the Cloud environment.

In a hybrid configuration, the self-managed Appian site communicates with the Appian Cloud site to execute a robotic task and retrieve the results. Robotic tasks usually interact with Appian data in some way. Therefore, the Appian Cloud site and the self-managed site must have the same CDTs if they're being used in a robotic task. The robotic task uses the Appian Cloud site CDT in the robotic task, but once complete, returns the updated data to the self-managed site. It's important that any data used by the robotic task uses the appropriate structure so it can be sent back to the self-managed site.

You can import CDTs to the Appian Cloud environment as part of a deployment package. Learn more about deployment considerations regarding CDTs.

Execute robotic tasks synchronously from process models

This section describes how to build process models in your self-managed site that communicate with Appian RPA in the Appian Cloud site.

When you develop process models that execute robotic tasks, you may want your process model to wait for the results of the robotic task before continuing. The robotic task executes asynchronously when you use two integration objects, so you have to configure the process model to wait for the robotic task to complete and retrieve the results separately before proceeding.

Goal

This pattern aims to help you develop a network of Appian objects to determine when a robotic task is complete. Most of these objects are reusable (as noted in the sections below), so you'll create them once and apply them to future robotic task and process model configurations.

Data passes between objects in the following ways:

• The main process model will start the robotic task using an integration and wait for a message stating that the robotic task has completed, which is determined with a sub-process.
• On completion, the robotic task will call a web API to look up the process instance where it started from, which is listed in a process report.
• The web API then starts a new process that will send a message to the main process.
• Once the main process receives a message that the robotic task is complete, it will retrieve the results using an integration.

Design structure

To get started, you'll need to create a few objects. In the sections below, we include names for the objects. You can name the new objects you create anything you'd like, but keep in mind that the code referencing the example object names will need to be updated as well if you change the names.

Some objects should be created at the same time, while others can be created in sequence. The steps below start with supporting objects that are needed to create the main process model, which executes the robotic task and fetches results.

At the end of this pattern, you'll have the following objects in your application:

• Process models (2), one representing the process model in your specific application that will incorporate the robotic task and one that will send the message that indicates the robotic task is complete.
• Integrations (2) to execute and retrieve the results of the robotic task.
• Connected system to authenticate the integrations.
• Web API that the robotic task calls when it completes.
• Process report to map the robotic task back to the original process that called it.
• Constants (2) to reference the process model and process report used by the web API.
• Group to set the security on all the other objects.

Step 1: Create group

Create a group to secure the application objects you'll create in the following steps. Add the service account for your Appian RPA connected system to this group.

Step 2: Create process report

Create a process report that will look up the ID of the process instance that executed the given robotic task. To do this:

1. In the Appian Designer, click New > Process Report to create a new Process Report object.
2. Click the Duplicate existing process report option. Select the Active Processes report that comes out-of-the-box.
3. Click Create to create the new report.
4. Open the new report to edit it.
5. Click Edit. In the Data tab, select all existing column names and click Delete.

6. Click New Data and add two new columns: one for the process instance ID (pp!id) and one for the execution ID (pv!executionId). The second column will be blank for any robotic tasks from process models without this variable.

   It's important that this report only contain two columns. If additional columns exist, the query breaks in the web API (detailed below).

7. Save your changes.
8. Set the security on the process folder and/or knowledge center so that the group you created in step 1 has Viewer access.
9. Create a constant that points to this process report so it can be referenced by the web API later on. In this pattern, we named this constant INSTANCE_EXECUTION_MAPPING_REPORT. Select Document for the constant type.

Step 3: Design the first process model

Next, create the process model to send a message to the main process model when the robotic task execution finishes.

Send Completion Message

This process is started by the notifyProcessOfCompletion web API (described below) and takes in a specific process instance ID to send a message to. The process ID is crucial here to ensure that the process-to-process message is targeted rather than just sending a massive message to any listening process model.

This process model contains three nodes: Start, Send Message, and End.

1. In the new process model, create a process variable called processInstance of type Number (Integer). Parameter should be set to Yes.
2. Create a Send Message Event node. On the Data tab, in the DestinationProcessID row, map the Value to the processInstance process variable (=pv!processInstance).
3. Set the security of the process model so that the group you created has Initiator access.

After you save the process model, create a constant called SEND_COMPLETION_MSG_PM pointing to it. You'll use this constant in the web API.

Step 4: Create a web API

Next, create the web API object. This web API is called during the cleanUp() method of the robotic task to notify the originating process that it has completed. It is designed to be generic, so that all the developer has to pass in is the execution ID and it will determine the correct process instance to send the message to.

1. Create a web API object called notifyProcessOfCompletion.
2. Click Start process to build the API from a template. Alternatively, you can choose Create from scratch instead, just choose POST in the HTTP Method field.
3. In the Endpoint field, type send-completion-msg.
4. Click Create.

The code below uses two constants:

• INSTANCE_EXECUTION_MAPPING_REPORT points to the process report you created in step 2. The report maps process instances with execution IDs.
• SEND_COMPLETION_MSG_PM points to the Send Completion Message process model. The API initiates this process model when it receives a process ID as input.

After you've created the object, use the following expression to configure the web API:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
a!localVariables(
  local!processId: index(
    a!queryProcessAnalytics(
      report: cons!INSTANCE_EXECUTION_MAPPING_REPORT,
      query: a!query(
        /* Filter the query results by the execution ID */
        filter: a!queryFilter(field: "c1", operator: "=", value: http!request.body),
        pagingInfo: a!pagingInfo(1, 1)
      )
    ).data,
    /* Index to receive only the process instance ID */
    "c0",
    {}
  ),
  if(
    length(local!processId)=0,
    /* If the query returned no results, there are no active processes waiting on that robotic task */
    a!httpResponse(
      statusCode: 200,
      headers: {
        a!httpHeader(name: "Content-Type", value: "application/json")
      },
      body: "There are no active processes to notify of the completion"
    ),
    /* Otherwise, start the process to send a message to the process instance */
    a!startProcess(
      processModel: cons!SEND_COMPLETION_MSG_PM,
      processParameters: {
        processInstance: local!processId
      },
      onSuccess: a!httpResponse(
        statusCode: 200,
        headers: {
          a!httpHeader(name: "Content-Type", value: "application/json")
        },
        body: a!toJson(
          fv!processInfo
        )
      ),
      onError: a!httpResponse(
        statusCode: 500,
        headers: {
          a!httpHeader(name: "Content-Type", value: "application/json")
        },
        body: a!toJson(
          {
            error: "There was an error starting the process"
          }
        )
      )
    )
  )
)

Finally, set the security of the web API so that the group you created has Viewer access.

Step 5: Create or edit the robotic task

This step takes place in your Appian Cloud environment with Appian RPA enabled.

Next, you'll need to update and deploy the robotic task code so it automatically sends a message to Appian when it's complete. This is done using the cleanUp() method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public String[] cleanUp() throws Exception {

  /** The cleanUp() method ensures the robot is cleaned up at the end of the execution
   * regardless of whether it completes successfully or not. Therefore, the web API call
   * should be added to the cleanUp() method to guarantee that it will always be called
   * at the end of the robotic task.
   */

  // Constructs the execution ID to pass to the web API
  String executionId = server.getExecution(0).getRobotName() + "#" +
      server.getExecution(0).getCurrentExecution().getExecutionNumber();

  // Calls the notifyProcessOfCompletion web API and passes the execution ID
  IAppian appian = IAppian.getInstance(this);
  IWebApiRequest request = IWebApiRequestBuilderFactory.getFreshInstance()
      .post("send-completion-msg")
      .body(executionId)
      .build();
  IWebApiResponse response = appian.callWebApi(request);

  // Displays the result of the web API in the execution log for easy debugging
  server.info("Response body: " + new String(response.getBodyBytes()));
  
  return new String[0];
}

This method is designed to be reusable, so you could consider saving this modified version as a class to use across multiple robotic tasks.

Step 6: Create a connected system and integrations

Set up a connected system as described above. Remember that the service account must have the appropriate tags in Appian RPA to run robotic tasks on robots and must be in the application group you created for this to work correctly.

You'll create and use two integrations based on this connected system:

1. getExecutionResults: Retrieves the execution results for the given execution ID. You can decide whether you want this to be a reusable rule or not, since it can't really vary much between applications. In the integration, create a rule input called executionId (text) and add ri!executionId in the Execution Id field of the integration.
2. executeRoboticTask: Executes a robotic task. This isn't a generic object, but rather will be application specific based on the robotic task they're calling. In the integration, two rule inputs called onSuccess and onError (any type) appear automatically. In the Robotic Task field, select the task you want to execute.

You'll use both of these integrations in the Execute Robotic Task process model, described next.

Step 7: Create the main process model

Finally, create the process model that starts the robotic task and waits for the results.

Execute Robotic Task

This process model kicks off the robotic task execution, then listens for a message indicating the execution has been completed. After it receives that message, it retrieves the results. It doesn't map to a reusable object, but represents a process model within a specific application that wants to integrate with a robotic task. You can think of this as the "main" process model.

This process model contains five nodes: Start, Execute Robotic Task, Receive Message, Get Results, and End.

1. In the new process model, create two process variables called executionId and status, both of type Text. Neither has a set value or other settings configured.
2. Add a Call Integration Smart Service node and use the executeRoboticTask integration. On the Data tab, configure a custom output called ac!Result.executionId. Save this output into the executionId process variable.
3. Add a Receive Message Event node to wait for the robotic task to complete.
4. Add a second Call Integration node and use the getExecutionResults integration. On the Data tab, add a new input called executionId. In the Value field, add the executionId process variable (=pv!executionId). Add a custom output called ac!Result.status. Save this output into the status process variable.
5. Set the security on the process model so that the group you created has Viewer access.

Test it out

Once you have all objects configured and connected, you're ready to test. Use the Start Process for Debugging option in the Execute Robotic Task process model to get started.

If the process model doesn't proceed past the Receive Message Event, check these common issues:

• Does your service account have the right permissions assigned? Remember that Appian RPA users, robots, and robotic tasks need to share at least one permission in common to execute properly.
• Is your integration fully set up? Open the executeRoboticTask integration object to confirm the desired robotic task is selected.
• Is your robot online? Make sure the desired robot is online and communicating with the Appian RPA console and orchestration server.
• Did the robotic task complete successfully, but didn't send a message back to the Send Completion Message process model? It could be that the process report isn't set up properly. In Appian RPA, go to the robotic task's execution log. If you see a line that says "Response body: There are no active processes to notify of the completion," check the process report to confirm that the robotic task execution ID is properly matched with the process model instance.

Maintaining robotic tasks in a hybrid configuration

Now that your hybrid configuration is set up, you and your team can focus on developing robotic tasks. To do that, you'll need to grant developers access to your Cloud site. User accounts aren't automatically synched between your self-managed site and your Cloud site, so you may also want to evaluate the available user authentication mechanisms. Synching certain user accounts automatically can help save you time by managing user accounts in just one environment.

Routinely evaluate data integrity and security in your Appian RPA implementation. Securing data in a robotic task is an important consideration in all environments.

Consider your deployment strategy when you're integrating robotic tasks with your applications. You'll likely have development, test, and production environments for both of your self-managed and Appian Cloud sites, so it's important to have a thorough understanding of how your deployment process works with hybrid configuration in place. Learn more about deploying robotic tasks and applications.