Using a service account to run tasks

Use a service account to run tasks in the following endpoint: https://api.<env>.cloud.talend.com/processing/executions

Before you begin

Ensure that the service account to be used to issue API calls has appropriate permissions. These permissions could be:
- The Engines - Use permission. The ID of this permission is TMC_ENGINE_USE. In this example, the service account was granted this permission as previously described in Creating a service account.
- The Operations - Manage permission. The ID of this permission is TMC_OPERATOR.
With either of the permissions, the service account must also be granted the Execute permission on the workspace to which the task to be run belongs. If not done yet, follow this procedure to assign the permission.
Once generated, a service account token expires after 30 minutes. If it expires, generate a new token using the POST method at the endpoint https://api.<env>.cloud.talend.com/security/oauth/token. For more information about generating a token, see Generating a service account token.

About this task

In this section, the following API call is issued:

method: POST
endpoint:  https://api.<env>.cloud.talend.com/processing/executions
headers: {
 "Content-Type": "application/json",
 "Authorization": "Bearer <service_account_token>"
}
payload: {
  "executable": "id_of_the_task_to_be_run",
  "logLevel": "WARN"
}

It is implemented in Talend API Tester for demonstration purposes.

In Talend API Tester, you can use an expression builder to dynamically retrieve the service account token from its related API request.

Procedure

Select POST from the Method list and in the field aside, enter the user management endpoint to be used: https://api.<env>.cloud.talend.com/processing/executions
Click Add header. In the name field that is displayed, enter Content-Type and in the value field, enter application/json.

Click Add header and in the name field that is displayed, enter Authorization and in the value field, enter Bearer and the service account access token in plain text or click the to build a dynamic expression. Enter a whitespace to separate Bearer and the token.

Since you need to renew the token once the current one expires, it is recommended to use an expression to enable this API request to dynamically use the latest token once it is renewed by the token API request.

In Talend API Tester, you can use the expression builder to write the expression. Note that the token API request must have been saved in your repository. In the previous section, this API request was saved and named as Renew the SAT.

This makes the value of Authorization look like this:
```
Bearer ${"service-account 2021"."Service Account Token scenario"."Renew the SAT"."response"."body"."access_token"}
```

4. In the BODY area, enter the information that specifies the task to be run by the service account. { "executable": "id_of_the_task_to_be_run", "logLevel": "WARN" }
In this example, no parameters are specified in the body so that this task run uses the default parameters created during the creation of the task. If you need to use custom values for your task parameters, such as connection parameters, add these parameters to the body, for example:

{ "parameters": [    { "name": "authentication_type", "value": "Basic", "encrypted": false }, { "name": "basic_username", "value": "my_user_name", "encrypted": false }, { "name": "basic_password", "value": "my_password", "encrypted": true }, { "name": "basic_security_token", "value": "my_salesforce_security_token", "encrypted": true } ] }

5. Send and save the request.

Results

The ID of this run is returned with the status code 201.

{
  "executionId": "16fefb53-035a-4249-af9d-f80a3b47b132"
}

What to do next

Use this ID at the endpoint /executions/{runId}/logs to monitor this task run. For further information, see Monitoring task runs in Talend Cloud Management Console

Previous section: Assigning workspace permissions to a service account