Studio Web - Managing API workflows

Creating API workflows

To create an API workflow solution:

In your Automation Cloud™ organization, open Studio Web.
Select Create New > API workflow.

Defining Input schemas

API workflows function as APIs themselves and may require an input schema to define the expected input parameters. The input schema specifies the data structure an external service must provide when triggering the workflow.

You can configure the input schema by uploading a JSON or by manually defining input parameters.

In your API workflow project, open the Data manager panel.
Select the Input tab.

To upload a JSON schema, follow Step 3.

To manually define input parameters, follow Step 4.
To upload a JSON schema with the input parameters already defined, select Generate From Payload.
1. Provide the JSON with the expected input.
2. Select Generate Schema.
3. Review the generated schema and add descriptions to properties if necessary.
To manually define input parameters, select Add property.
1. Configure the property details:
  - Name—Define the property key
  - Type—Select from String, Number, Integer, Boolean, Object, Array, Date-time, Date, Time.
    Important: If you are using an Object or an Array, define the properties for the nested items.
  - Required—Select this box to mark the property as required.
2. Repeat the step until you define all input parameters.

Defining Output schemas

The output schema defines the structure of the data returned by the API workflow, ensuring that any service calling the workflow understands the output format in advance. The output schema may include data explicitly defined within the schema itself, such as IDs or user-provided values, as well as outputs generated dynamically from workflow steps, such as API responses or calculated values.

You can configure the output schema by uploading a JSON or by manually defining output parameters.

In your API workflow project, open the Data manager panel.
Select the Output tab.

To upload a JSON schema, follow Step 3.

To manually define output parameters, follow Step 4.
To upload a JSON schema with the output parameters already defined, select Generate From Payload.
1. Provide the JSON with the expected output.
2. Select Generate Schema.
3. Review the generated schema and add descriptions to properties if necessary.
To manually define output parameters, select Add property.
1. Configure the property details:
  - Name—Define the property key
  - Type—Select from String, Number, Integer, Boolean, Object, Array, Date-time, Date, Time.
    Important: If you are using an Object or an Array, define the properties for the nested items.
  - Required—Select this box to mark the property as required.
2. Repeat the step until you define all output parameters.

Using the Expression editor

The Expression editor helps you access, evaluate, and manipulate data within API workflows. Use it to create conditional logic, configure activity fields, or write JavaScript activities.

Expression editor layout

The layout of the Expression editor contains the following panels:

Panel	Description
Input	The main panel is the input panel, where you write your JavaScript or JQ expressions. This panel includes a built-in syntax-checker that identifies and highlights errors in your expression syntax.
Autopilot expression generator	Located at the bottom of the input panel, the Autopilot expression generator helps you create workflow expressions using natural language, instead of writing JavaScript. Autopilot understands the context of your workflow, and enables you to reference objects and workflow steps simply by describing your desired outcome.
Activity test input	To the right-hand side of the code panel, the Activity test input panel allows you to review test data generated from previous workflow runs. It provides sample data you can use to build and validate expressions, and it interacts directly with the Expression output panel to ensure your expressions produce the desired results.
Expression output	The Expression output panel displays the result of your expression based on the data from the Activity test input data. This allows you to validate that your expression generates the expected outcome. If your expression has errors, the Expression output section highlights the problematic expression and provides a corresponding error message. The result updates automatically whenever you modify the expression in the input panel.

Accessing data using JavaScript

There are two access points for workflow data:

$workflow—Refers to the workflow-level configuration.
$context—Refers to activity-level configuration.
$input—Refers to the previously executed activity configuration.

Important: Use the Test input screen within the Expression editor to reference step properties when building your expressions.

Access points	Description	How to use
`$workflow.input`	Stores the request schema and any values defined in the test configuration.	To access test configuration data within the Expression editor, enter the following syntax, and replace `{property_name}` with the specific property you want to reference: `$workflow.input.{property_name}`$workflow.input.{property_name}
`$context`	Stores the input and output data for each workflow step. To reference these properties in your expressions, first run and test the workflow. This generates step-level inputs and outputs visible in the Test Input screen.	To access the output response data of a specific step, use the following syntax pattern in the Expression editor, and replace `{step_name}` and `{property_name}` with your step and property names, respectively: `$context.outputs.{step_name}.content.{property_name}`$context.outputs.{step_name}.content.{property_name}
`$input`	Stores data passed directly from the previous step into the current step. Use `$input` to reference properties from the preceding step without navigating through the entire `$context`.	To access properties from the previous step, use the following syntax, and replace `{property_name}`with the property you wish to reference: `$input.{property_name}`$input.{property_name}

Testing API workflows

For a successful API workflow integration, test your workflow early and frequently. Regular testing helps you quickly identify and resolve errors. Features such as IntelliSense, auto-completion, Autopilot, and the Activity test input screen depend on test data. Execute the workflow regularly using the Test button to generate this data.

Testing ensures:

Your data mappings between workflow steps are correct, preventing unexpected behavior.
API requests are properly configured, ensuring reliable responses.
Your workflow performs as intended, reducing the risk of unexpected errors in production.

Understanding the Run Output information

The Run Output panel provides detailed information about workflow execution.

Activity input and output data

This data is available per selected activity and provides:

Input data—Information a step receives from the previous activity.
Output data—Information produced by the current step, passed to the next activity.

Review input/output data to confirm accurate mappings and data transformations.

API request information

When workflows interact with APIs, verify the following request details:

Request URL—Confirm dynamic URL parameters resolve correctly.
Headers—Ensure authentication and content-type headers are set appropriately.
Query Parameters—Check that filters and parameters are correctly formatted.
Body Content—Validate JSON structure matches the API requirements.

Successful API requests

For successful API requests, expand each step to review:

Request details—URL, headers, query parameters, and body content.
Response details—Status code, headers, and response content.
Output data—Information generated by the API call for use in subsequent workflow steps.

Debug

To efficiently identify and debug workflow errors, follow these guidelines:

Error Indicators
- Steps encountering errors display an error icon.
- Select the step to view detailed error messages and outputs.
Common Debugging Steps
- Validate API requests—Ensure request details such as URLs, headers, parameters, and body content match API documentation.
- Review error messages—Examine error messages for clues about authentication errors, incorrect payloads, or scripting mistakes.

Adding a Test configuration

You can build and test your API workflow iteratively, validating each step as you add new activities. To run these tests effectively, you can define specific input data using the Test configuration feature. This allows you to set a JSON input once and reuse it across all subsequent test runs. You can access the emulated data through the $workflow.input object during workflow execution.

To add a Test configuration:

On the top of your API workflow designer canvas, open the Test dropdown, then select Test configuration.
In the window that opens, provide the test input data in JSON format.
Save your test configuration.
Once saved, you can access the test configuration in the Expression editor using the reference $workflow.input.{propertyname}. Additionally, the test configuration is also displayed in the Activity test input panel of the Expression editor.

Testing your API workflow

To test your API workflow:

Open your API workflow. Make sure your workflow is fully configured and ready to run.
If your workflow depends on input data, for example, from an external system, define the Test configuration before testing. This ensures every step receives the necessary data.
Test your workflow. The Test button is located at the top of the page. Select it to execute the workflow and see real-time results.
Once testing starts, the Run Output panel appears on the right side of the screen. Here, you can see each step execution status clearly marked as success, failure, or pending.

Publishing API workflows

Important: Before publishing, test your API workflow using both success and failure scenarios to confirm that each scenario executes correctly.

To publish your API workflow solution:

On your API workflow designer canvas, select Publish.
Select the location where your API workflow should be published:
- Your Orchestrator personal workspace feed
- Your Orchestrator tenant feed
Provide other details important for your API workflow, such as Change log and Version.
Select Publish. A notification informs you about the successful publishing of your API workflow.

If you published to your personal workspace feed, the workflow is visible in Orchestrator under My Workspace > Automations > Processes. API workflows are identifiable by the type API.

If you published to your tenant feed, the workflow is visible in Orchestrator under Tenant > Solutions. API workflows are identifiable by the type API.

Deploying API workflows

Once you published your API Workflow to the feed of your preference, you need to deploy the solution.

Deploying API workflows from your personal workspace feed

Publishing to your personal workspace prepares the API workflow as a process in Orchestrator > My Workspace > Your API workflow name subfolder > Automations > Processes.

Important: A dedicated subfolder is automatically created inside your personal workspace folder.

Deploying API workflows from your tenant feed

Publishing to your Orchestrator tenant uploads the API workflow package to Orchestrator > Tenant > Solutions.

To deploy it as a process:

Go to Orchestrator > Tenant > Solutions.
For the API workflow package you previously published to your tenant feed, select the three dots menu, then select Deploy package.
On the Deploy solution version wizard, configure the following details:
1. Deployment name—add the name to be displayed on all pages which mention, list, or monitor processes. If left empty, the name of the package is used.
2. Destination folder—indicate the folder to be used as a parent folder for the solution root. The solution is not deployed in the selected folder, but a new child folder is created.
3. Install as a new root folder under tenant—select this checkbox to install the solution as a new root folder under the current tenant.
4. Solution root folder name—change the root folder name.
Select Review. You can now save your solution as a draft, or validate it and continue.
Select Deploy. Now you can find your workflow as a process in the folder indicated at step 3 > Automations > Processes. You can identify an API Workflow by the type API.
Select Activate deployment to finish deploying your API workflow.

Best practices

Define clear Input and Output schemas so other UiPath products can understand and interact with your workflow.
Leverage the quick execution speed of API workflows to test input and output payloads during design time.
Use Autopilot to generate context-aware expressions and JavaScript code.
Validate expressions in the Expression Editor output panel to catch syntax or logic issues before runtime.
Interact with input and output data in the Run Output panel by expanding, collapsing, or copying values to the clipboard.
Exit the workflow early by configuring a Response activity, either Success or Failure.
In Loop activities, namely For Each and Do While, use $input instead of $context to access the previous object output.
Use the HTTP activity to call APIs directly when a connector does not provide the required functionality. Choose between the native HTTP activity or the connector-specific HTTP Request activity.

Provide authentication tokens in the HTTP activity Headers property:

{ 
    Authorization: "<my_token>",
    "Content-Type": "application/json"
}{ 
    Authorization: "<my_token>",
    "Content-Type": "application/json"
}

For basic authentication, use:

{ Authorization: "Basic " + btoa("<username>:<pass>")}{ Authorization: "Basic " + btoa("<username>:<pass>")}

Studio Web User Guide

Managing API workflows