Subscribe

UiPath Marketplace

The UiPath Marketplace Guide

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 <a href="https://docs.uipath.com/orchestrator/docs/about-processes" target="_blank">About Processes</a> 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 <a href="https://platform.uipath.com/techpartners/techpartners/swagger/ui/index#/Releases" target="_blank">Releases</a> endpoint using the **Process Name** as your input parameter (e.g., `{{base url}}/odata/Releases?$filter=ProcessKey eq {{ProcessName}}`).
      * [API](https://docs.uipath.com/orchestrator/reference#section-retrieving-processes-according-to-their-name)
     * [Swagger](https://platform.uipath.com/techpartners/techpartners/swagger/ui/index#!/Releases/Releases_GetReleases)
      * [Postman](https://postman.uipath.rocks/?version=latest#e586540c-dd9a-48ca-9e23-8efe887252b7)

📘

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:
     * **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 <a href="https://platform.uipath.com/techpartners/techpartners/swagger/ui/index#!/Environments/Environments_GetEnvironments" target="_blank">GetEnvironments</a> endpoint using the **EnvironmentName** as your input parameter (e.g., *{{base url}}/odata/Environments?$expand=Robots&$filter=Name eq {{_EnvironmentName_}}*). 
           * [API](https://docs.uipath.com/orchestrator/reference#section-according-to-its-name)
           * [Swagger](https://platform.uipath.com/techpartners/techpartners/swagger/ui/index#!/Robots/Robots_GetRobots)
           * [Postman](https://postman.uipath.rocks/?version=latest#5d0b1f9d-0275-4d57-b144-fc72554995f1)
        * 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.
     * **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.
     * **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 <a href="https://platform.uipath.com/techpartners/techpartners/swagger/ui/index#/Releases" target="_blank">Releases</a> 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.

Updated about a month ago


How to Start a Job


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.