How to Start a Job

A job is the execution of a process using one or more robots. Implementing the Start Job process enables the creation of a new job in response to events that occur within your platform (outside the UiPath platform).

Endpoints and Inputs

Starting a job requires the use of both GET and POST requests to multiple Orchestrator API endpoints. The GET requests are used to retrieve the input parameter values required for the POST request to the StartJobs endpoint.

What Are the StartJob Input Parameters?

To successfully send POST requests to the StartJob endpoint, you must provide at a minimum, a ReleaseKey (process identifier) and Strategy (how to run the process) as input parameters. Depending on the Strategy, there may be additional input parameters including JobsCount or RobotIds.

How Do I Get the StartJob Input Parameter Values?

To retrieve the required input parameters noted above (i.e., ReleaseKey and Strategy), you collect the following information:

Process Name

The name of the process that will run upon a successful StartJob request (for more information, about processes see About Processes in the Orchestrator Guide).

The process name is used to retrieve the ReleaseKey value.

There may be multiple instances of the same process that are differentiated by the environment they're published in. Because of this, a single Process Name can result in multiple ReleaseKeys. In the event that there are multiple ReleaseKeys associated with a process, the EnvironmentName can be used to identify the ReleaseKey of the process the user wants to run (the EnvironmentName is also used to identify the available robots, more on that in the next bullet).

To retrieve both the ReleaseKey and EnvironmentName for a given process, send a GET request to the Releases endpoint using the Process Name as your input parameter (e.g., {{base url}}/odata/Releases?$filter=ProcessKey eq {{ProcessName}}).

• API
• Swagger

• Postman

Note: The response from the Releases GET request also includes the input argument requirements for the specific process. For more information, see the Input Arguments bullet below.

Strategy

Specifies how the job runs the process; there are three options:

1. Specific

The process runs on a specific robot(s).

When Specific is selected, the StartJob endpoint requires the RobotId of the robot that you want to use to run the process.

To retrieve the RobotId, send a GET request to the GetEnvironments endpoint using the EnvironmentName as your input parameter (e.g., {{base url}}/odata/Environments?$expand=Robots&$filter=Name eq {{_EnvironmentName_}}).

• API
• Swagger
• Postman

Multiple RobotIds may be included in the GetEnvironments response. To identify the correct RobotId, you can use the Robot Name. Because of this, it's recommended that you collect this information when Specific is selected.

2. JobsCount

The process runs a specified number of times using the next available robot.

When JobsCount is selected, the StartJob endpoint requires the JobsCount input parameter to include a value. Because of this, it's recommended that you provide means for a user to enter a number.

3. All

The process will run once on all robots.

Input Arguments (optional)

The process, specified by the Process Name, may require input arguments. These input arguments typically map to data fields associated with an application object.

For example, an issue management system may have an Incident object. This Incident object includes several data fields that contain information relevant to the process (e.g., IncidentId, DateCreated, Owner, etc.).

As noted above, you can determine if a process requires input arguments by parsing the Arguments block in the GET Releases response (see example response below).

To include these data field values in the StartJob POST request, it's recommended that you provide the means to select the application object and its relevant data fields required for the process. When the job is invoked, the connector retrieves the data field values and adds them in the POST request as the InputArgument parameter value.

Note:

You can also send a GET request to the Processes_GetArgumentsByKey endpoint to identify whether a process has required arguments. The benefit to this endpoint is the response only includes the argument details (i.e, Input and Output).

The downside to this endpoint, and why it's not used in our examples, is that it would require the connector to make additional GET requests to retrieve information that was already provided in the previous GET Releases response (which is required to get the ReleaseKey value).

{
  "@odata.context": "https://platform.uipath.com/twTenantTest/twTenantTest/odata/$metadata#Releases",
  "@odata.count": 1,
  "value": [
    {
      "Key": "99587436-4ce5-480d-988c-6d7f43787a2c",
      "ProcessKey": "SupportTriage",
      "ProcessVersion": "1.0.1",
      "IsLatestVersion": false,
      "IsProcessDeleted": false,
      "Description": "",
      "Name": "SupportTriage_QuickstartDemo",
      "EnvironmentId": 128912,
      "EnvironmentName": "QuickstartDemo",
      "InputArguments": null,
      "ProcessType": "Process",
      "SupportsMultipleEntryPoints": false,
      "RequiresUserInteraction": true,
      "AutoUpdate": false,
      "JobPriority": "Normal",
      "Id": 312722,
      "Arguments": {
        "Input": "[{\)\)"name\)\)":\)\)"IncidentId\)\)",\)\)"type\)\)":\)\)"System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\)\)",\)\)"required\)\)":true,\)\)"hasDefault\)\)":false}]",
        "Output": null
      },
      "ProcessSettings": null
    }

Examples

This section provides links to example connector user interfaces and the corresponding Orchestrator API requests for each input field.

In these examples, we introduce the concept of a Template. A template represents an association of an application object and/or event with a UiPath process or queue. Conceptually, a template gives you the ability to invoke different Orchestrator resources (e.g., start a job, add a Queue item) when different events occur within your application (e.g., new object created, object status change) while maintaining a single authenticated connection.

• Start a Job - Specific
• Start a Job - JobsCount
• Start a Job - All