Tidal Automation

https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/
Admin
Tidal Automation is an enterprise job scheduling solution that enables developers to define and...
Tokens:195,158
Snippets:548
Trust Score:8.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### Create Tag Map REST API Example (XML)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Tag%20Map

This example demonstrates how to create a Tag Map using the Tidal REST API. It utilizes the 'create' method of the Tag Map object. The request is formatted in XML.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:TagMap.create xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<object></object>
</tes:TagMap.create>
</entry>
```

--------------------------------

### Accessing REST API Documentation (Method 2)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Instructions for accessing REST API documentation by constructing a URL using the Plugin Name obtained from TA Web.

```APIDOC
## Accessing REST API Documentation (Method 2)

### Description
This method describes how to access documentation for REST API Objects and Methods by constructing a URL using the Plugin Name.

### Steps
1. Obtain the Plugin Name from the TA Web:
   a. Open the TA Web.
   b. Click `Master Status` in the `Navigator`. The Plugin name appears at the top of the panel after a few seconds.
2. Enter the following URL in your browser:

### Endpoint
`http://<ClientManager server hostname>:<port>/apidoc/<Plugin Name>`
```

--------------------------------

### Get List of Available Calendars via TA REST API

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Calendar

Provides an example of a REST API call to retrieve a list of all available calendars using the Calendar.getList method. This method requires no parameters and returns a list of calendars in an Atom feed format.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://purl.org/atom/ns#">
<id>xxx</id>
<tes:Calendar.getList xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
</tes:Calendar.getList>
</entry>
```

--------------------------------

### Setting Bind Password on Windows

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Command example for setting or changing the Active Directory or LDAP bind password in the clientmgr.props file on a Windows system. This is used for single-domain user authentication.

```batch
TIDAL\ClientManager\script\cm.cmd setbindpwd
```

--------------------------------

### Create Job with Custom Start Times

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

This endpoint allows for the creation of a job with specified custom start times. When defining multiple custom start times, ensure each time is separated by a backslash followed by a comma.

```APIDOC
## POST /api/jobs/create

### Description
Creates a new job with custom start times. Ensure custom times are properly escaped.

### Method
POST

### Endpoint
/api/jobs/create

### Parameters
#### Request Body
- **tes:Job.create** (object) - Required - The job creation payload.
  - **tes:job** (object) - Required - Job details.
    - **tes:name** (string) - Required - The name of the job.
    - **tes:type** (integer) - Required - The type of the job.
    - **tes:active** (string) - Required - Indicates if the job is active ('Y' or 'N').
    - **tes:ownerid** (integer) - Required - The ID of the job owner.
    - **tes:command** (string) - Required - The command to be executed by the job.
    - **tes:runuserid** (integer) - Required - The ID of the user to run the job.
    - **tes:agentid** (integer) - Required - The ID of the agent to run the job.
    - **tes:saveoutputoption** (string) - Required - Option to save job output ('Y' or 'N').
    - **tes:repeat** (string) - Required - Job repeat setting ('T' for time-based).
    - **tes:customstarttimes** (string) - Required - A list of custom start times, e.g., '1:30\,2:30'.

### Request Example
```xml
<entry xmlns="http://purl.org/atom/ns#">
  <tes:Job.create xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
    <tes:job>
      <tes:name>abc_job4</tes:name>
      <tes:type>2</tes:type>
      <tes:active>Y</tes:active>
      <tes:ownerid>1</tes:ownerid>
      <tes:command>hostname</tes:command>
      <tes:runuserid>1</tes:runuserid>
      <tes:agentid>6</tes:agentid>
      <tes:saveoutputoption>Y</tes:saveoutputoption>
      <tes:repeat>T</tes:repeat>
      <tes:customstarttimes>1:30\,2:30</tes:customstarttimes>
    </tes:job>
  </tes:Job.create>
</entry>
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the created job.

#### Response Example
```json
{
  "id": 101
}
```
```

--------------------------------

### Basic Authentication with Session Tokens (curl)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Demonstrates how to authenticate using basic authentication (username and password) when session tokens are enabled. It shows the initial curl command and the expected response containing session cookies (CSTSED and Session-Token) that must be used in subsequent requests.

```curl
curl -s -v -u <username>:<password> http://localhost:8080/api/production/MasterNode.checkMasterConnectionStatus
```

```http
< HTTP/1.1 200 OK
< Set-Cookie: CSTSED=node015x2z5kt91n8av8cgkl7zeh6v5; HttpOnly
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Content-Type: text/xml;charset=utf-8
< Set-Cookie:
< Session-Token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInJlbW90ZS1ob3N0XCI6 XCIwOjA6MDowOjA6MDowOjFcIixcInVzZXJcIjpcInZpbmNlbnRsXCIsXCJ1c2VyLWFnZW50XCI6XCJjdXJsLzcuNTUuMVwifSIsIml hdCI6MTYwMzMwNjk5MCwiZXhwIjoxNjAzMzA3MjkwfQ.E-VU4mOWsMhLzOk92tlZidE92UWFCscYkoWSeDvJVFAYRp7HnXF-tpkSqt4 ypVm07lDrxTLl6I7Tx4o0FeyyGQ; HttpOnly
< Transfer-Encoding: chunked
< 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><entry xmlns="http://purl.org/atom/ns#"><id>0</id><title>Y</title><source>com.tidalsoft.framework.rpc.Result</ source><tes:result xmlns:tes="http://www.tidalsoftware.com/client/tesservlet"><tes:message>Y</tes:message><tes:objectid>1< /tes:objectid><tes:id>0</tes:id><tes:operation>checkMasterConnectionStatus</tes:operation><tes:ok>true< /tes:ok></tes:result></entry>* Connection #0 to host localhost left intact
```

--------------------------------

### GET /api/jobs/{id}/shared-owners

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

Retrieves the shared owners for a specific job ID.

```APIDOC
## GET /api/jobs/{id}/shared-owners

### Description
Retrieves the shared owners for a specific Job ID.

### Method
GET

### Endpoint
/api/jobs/{id}/shared-owners

### Parameters
#### Path Parameters
- **id** (integer) - Required - The Job ID.

### Response
#### Success Response (200)
- **sharedOwners** (array) - An array of shared owner objects, each containing owner details.

#### Response Example
```json
{
  "sharedOwners": [
    {
      "id": 10,
      "name": "Owner One"
    },
    {
      "id": 20,
      "name": "Owner Two"
    }
  ]
}
```
```

--------------------------------

### Setting Bind Password on Unix

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Command example for setting or changing the Active Directory or LDAP bind password in the clientmgr.props file on a Unix system. This is used for single-domain user authentication.

```bash
/opt/TIDAL/ClientManager/bin/cm setbindpwd
```

--------------------------------

### Get a Specific Calendar

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Calendar

Retrieves a specific calendar by its ID. If the calendar is not found, an exception is returned.

```APIDOC
## GET /api/calendars/{id}

### Description
Retrieves a specific calendar by its ID. If the calendar is not found, an exception is returned.

### Method
GET

### Endpoint
/api/calendars/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the calendar to retrieve.

### Response
#### Success Response (200)
- **Calendar object** - The details of the requested calendar.

#### Response Example
```json
{
  "id": 30,
  "name": "Example Calendar",
  "description": "A sample calendar."
}
```
```

--------------------------------

### Accessing REST API Documentation (Method 1)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Instructions for accessing REST API documentation through the TA Web interface.

```APIDOC
## Accessing REST API Documentation (Method 1)

### Description
This method describes how to access documentation for REST API Objects and Methods via the TA Web interface.

### Steps
1. Open the TA Web.
2. Click `API Docs` on the `Help` menu.
```

--------------------------------

### Delete Tag Map REST API Example (XML)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Tag%20Map

This example shows how to delete a Tag Map using the Tidal REST API. It uses the 'delete' method of the Tag Map object. The request is formatted in XML.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:TagMap.delete xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<object></object>
</tes:TagMap.delete>
</entry>
```

--------------------------------

### Job Run Parameters

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/JobGroup

This section details the parameters available for configuring job runs, including error handling, time windows, tracking, and job types.

```APIDOC
## Job Run Parameters

### Description
This section details various parameters that can be used to configure job runs within the Tidal Content API. These parameters cover aspects such as error handling, time window settings, tracking information, and job categorization.

### Method
N/A (This is a documentation of parameters, not a specific endpoint)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **terminateparentonerrorflag** (String) - Optional - Flag to terminate parent when an error occurred during the jobrun.
- **timewindowfromtime** (Date) - Optional - Time window from time (Date).
- **timewindowfromtimeasstring** (String) - Optional - Time window from time (String).
- **timewindowoption** (Short) - Optional - Time window option.
- **timewindowuntiltime** (Date) - Optional - Time window until time (Date).
- **timewindowuntiltimeasstring** (String) - Optional - Time window until time (String).
- **trackingcommand** (String) - Optional - Tracking Command (length 4000).
- **trackingmethod** (Short) - Optional - Tracking method.
- **type** (Short) - Optional - Type of Job.
- **unixprofile** (Short) - Optional - Unix profile.
- **variables** (String) - Optional - Variables.
- **waitOperator** (String) - Optional - Wait operator.
- **workingdirectory** (String) - Optional - Working directory (length 4000).

### Request Example
N/A

### Response
N/A
```

--------------------------------

### GET /api/jobs/{id}/shared-owner-ids

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

Retrieves the shared owner IDs for a specific job ID.

```APIDOC
## GET /api/jobs/{id}/shared-owner-ids

### Description
Retrieves the shared owner IDs for a specific Job ID.

### Method
GET

### Endpoint
/api/jobs/{id}/shared-owner-ids

### Parameters
#### Path Parameters
- **id** (integer) - Required - The Job ID.

### Response
#### Success Response (200)
- **ownerIds** (array) - An array of shared owner IDs.

#### Response Example
```json
{
  "ownerIds": [10, 20, 30]
}
```
```

--------------------------------

### Create Web Service Action with Parameters

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Action

Creates a web service action with specific parameters, including request body templates and dynamic parameters.

```APIDOC
## Create Web Service Action with Parameters

### Description
Creates a web service action with specific parameters, including request body templates and dynamic parameters.

### Method
POST

### Endpoint
/api/actions/webservice

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the web service action.
- **ownerid** (integer) - Required - The ID of the owner.
- **serviceid** (integer) - Required - The ID of the service.
- **connectionid** (integer) - Required - The ID of the connection.
- **publicflag** (string) - Optional - Public flag ('Y' or 'N').
- **serviceinfo** (object) - Required - Detailed configuration for the web service action.
  - **action** (object) - Contains web service specific configurations.
    - **wstimeout** (integer) - Web service timeout in seconds.
    - **cmd** (string) - Command type (e.g., POST, GET).
    - **http_method** (string) - HTTP method to use.
    - **request_headers** (object) - Request headers.
    - **conn** (integer) - Connection ID.
    - **request_body** (string) - Request body content, potentially with placeholders like `:JobName`.
    - **form_parameters** (object) - Form parameters for the request.
    - **content_type** (string) - Content type of the request.
    - **accept_type** (string) - Accept header value.
    - **success_statuses** (string) - Comma-separated list of success status codes.
    - **match_type** (string) - Match type for response.
    - **match_it** (string) - Pattern to match in the response.
    - **match_not** (string) - Pattern not to match in the response.
    - **oauth_parameter_override** (string) - OAuth parameter override ('Y' or 'N').
    - **params** (object) - Parameters for the web service call.
      - **pcount** (integer) - Number of parameters.

### Request Example
```json
{
  "name": "testAction",
  "ownerid": 6,
  "serviceid": 25,
  "connectionid": 56,
  "publicflag": "Y",
  "serviceinfo": {
    "action": {
      "wstimeout": 75,
      "cmd": "POST",
      "http_method": "POST",
      "request_headers": {},
      "conn": 56,
      "request_body": "<?xml version=\"1.0\" encoding=\"UTF-8\"?> <AlarmMessage> <ReferenceID>:JobName</ReferenceID> <DateTime>:Date</DateTime> <Subject>Some subject</Subject> <InstanceName>:Agent</InstanceName> </AlarmMessage>",
      "form_parameters": {},
      "content_type": "",
      "accept_type": "text/xml, application/xml, application/atom+xml, application/json,application/x-www-form-urlencoded",
      "success_statuses": "200",
      "match_type": "",
      "match_it": "",
      "match_not": "",
      "oauth_parameter_override": "N",
      "params": {
        "pcount": 0
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created web service action.

#### Response Example
```json
{
  "id": "xxx"
}
```
```

--------------------------------

### Authentication

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

This section explains how to authenticate API calls using a Bearer token and provides an example using curl.

```APIDOC
## Authentication

To use a previously authorized token in an API call, specify the token in the HTTP Authorization header as follows:

```
Authorization: Bearer <your_token>
```

### Example using curl

```bash
curl -s -v -H 'Authorization: Bearer <your_token>' http://localhost:8080/api/production/MasterNode.checkMasterConnectionStatus
```

### Error Handling

If an improper token (expired or revoked) is used, the API will return a "401 Unauthorized" error.

### Client Manager Authentication Settings

The Client Manager authenticates tokens against a directory service (LDAP or Active Directory). Administrators must configure properties in the `clientmgr.props` file to enable this lookup.

**If Security.Authentication=ActiveDirectory:**

| Property Name              | Description
```

--------------------------------

### GET /api/jobs/{id}/sla-history

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

Retrieves SLA history records for a specific job ID.

```APIDOC
## GET /api/jobs/{id}/sla-history

### Description
Retrieves SLA history records directly from the database for a specific Job ID. The history records are returned in descending order of Create Time.

### Method
GET

### Endpoint
/api/jobs/{id}/sla-history

### Parameters
#### Path Parameters
- **id** (integer) - Required - The Job ID.

### Response
#### Success Response (200)
- **slaHistory** (array) - An array of SLA history records, each containing details like Create Time, Status, etc.

#### Response Example
```json
{
  "slaHistory": [
    {
      "createTime": "2023-10-27T10:00:00Z",
      "status": "Completed",
      "details": "SLA met"
    },
    {
      "createTime": "2023-10-26T10:00:00Z",
      "status": "Failed",
      "details": "SLA missed"
    }
  ]
}
```
```

--------------------------------

### POST /auth/authenticate

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Authenticates the client using the key generated from the /auth/key API. Upon successful authentication, it generates a Session ID and Session Token, which are necessary for accessing protected web contexts.

```APIDOC
## POST /auth/authenticate

### Description

This API endpoint is used for client authentication. It requires a key generated from a previous `/auth/key` API request. Successful authentication results in the generation of a Session ID and a Session Token, which are essential for accessing protected resources like `/client`, `/info`, and `/apidoc`.

### Method

POST

### Endpoint

`/auth/authenticate`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

- **key** (string) - Required - The Base64 encoded key obtained from the `/auth/key` endpoint.

### Request Example

```json
{
  "key": "<base64_encoded_key_from_/auth/key>"
}
```

### Response

#### Success Response (200)

- **sessionId** (string) - The unique session identifier.
- **sessionToken** (string) - The token used for subsequent authenticated requests.

#### Response Example

```json
{
  "sessionId": "<generated_session_id>",
  "sessionToken": "<generated_session_token>"
}
```
```

--------------------------------

### GET /api/jobs/{id}/tags

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

Retrieves a list of tag names mapped to a specific job.

```APIDOC
## GET /api/jobs/{id}/tags

### Description
Retrieves a list of tag names mapped to a job, returned as a comma-separated string.

### Method
GET

### Endpoint
/api/jobs/{id}/tags

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the job.

### Response
#### Success Response (200)
- **tags** (string) - A comma-separated string of tag names associated with the job.

#### Response Example
```json
{
  "tags": "Tag A, Tag B, Tag C"
}
```
```

--------------------------------

### Create Web Service Action with Parameters via REST API

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Action

This XML example illustrates creating a web service action with specific parameters using the Tidal REST API. It defines the action name, owner, service, and connection IDs, along with detailed service information including request body, headers, and accepted content types.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://purl.org/atom/ns#">
<id>xxx</id>
<title>API</title>
<tes:ServiceAction.create xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tes:ServiceAction>
<tes:name>testAction</tes:name>
<tes:ownerid>6</tes:ownerid>
<tes:serviceid>25</tes:serviceid>
<tes:connectionid>56</tes:connectionid>
<tes:publicflag>Y</tes:publicflag>
<tes:serviceinfo> < action> < wstimeout>75</wstimeout>< cmd>POST</cmd> < request_headers/>< conn>56</conn> < http_method>POST</http_method>< resource_path/> < request_body>&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;AlarmMessage&gt; &lt;ReferenceID&gt;:JobName&lt;/ReferenceID&gt; &lt;DateTime&gt;:Date&lt;/DateTime&gt; &lt;Subject&gt;Some subject&lt;/Subject&gt; &lt;InstanceName&gt;:Agent&lt;/InstanceName&gt; &lt;/AlarmMessage&gt;< /request_body>< form_parameters/> < content_type/>< accept_type>text/xml, application/xml, application/atom+xml, application/json,application/x-www-form-urlencoded</accept_type> < success_statuses>200</success_statuses>< match_type/> < match_it/>< match_not/> < oauth_parameter_override>N</oauth_parameter_override> < params>< pcount>0</pcount>< /params>< /action> </tes:serviceinfo>
</tes:ServiceAction>
</tes:ServiceAction.create>
</entry>
```

--------------------------------

### Get Shared Owners for Job (XML)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

Retrieves the shared owners for a specific Job ID.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Job.getSharedOwners xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<id>23</id>
</tes:Job.getSharedOwners>
</entry>
```

--------------------------------

### Job Parameters Reference

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/FTPJob

This section details various parameters that can be used when interacting with job-related endpoints in the Tidal Automation API.

```APIDOC
## Job Parameters Reference

### Description
This section details various parameters that can be used when interacting with job-related endpoints in the Tidal Automation API.

### Parameters
#### Request Body Parameters (Commonly Used)
- **repeatcount** (Short) - Optional - Repeat count
- **repeatinterval** (Short) - Optional - Repeat interval of Job
- **replacefiles** (String) - Optional - Replace files
- **rerundependency** (String) - Optional - Rerun dependency (length 1)
- **runbook** (String) - Optional - Run book
- **runuserid** (Integer) - Optional - Runuser id
- **runtimeusername** (String) - Optional - Run time user of the job
- **saveoutputoption** (String) - Optional - Option to save output (length 1)
- **serviceid** (Integer) - Optional - Service id
- **sshonly** (String) - Optional - Ssh Only
- **successorsvalue** (String) - Optional - Has successor (length 1)
- **targetfilename** (String) - Optional - Target file name
- **timewindowfromtime** (Date) - Optional - Time window from time (Date)
- **timewindowfromtimeasstring** (String) - Optional - Time window from time (String)
- **timewindowoption** (Short) - Optional - Time window option
- **timewindowuntiltime** (Date) - Optional - Time window until time (Date)
- **timewindowuntiltimeasstring** (String) - Optional - Time window until time (String)
- **trackingcommand** (String) - Optional - Tracking Command (length 4000)
- **trackingmethod** (Short) - Optional - Tracking method
- **type** (Short) - Optional - Type of Job
- **unixprofile** (Short) - Optional - Unix profile
- **userpasswordauthentication** (String) - Optional - User password authentication
- **variables** (String) - Optional - Variables
- **waitOperator** (String) - Optional - Wait operator
- **workingdirectory** (String) - Optional - Working directory (length 4000)

### Contact
Spotted a typo or can’t find help on a certain subject? Reach out to the Documentation team at docsupport@redwood.com.
```

--------------------------------

### Get Shared Owner IDs for Job (XML)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

Retrieves the shared owner IDs associated with a specific Job ID.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Job.getSharedOwnerIds xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<id>23</id>
</tes:Job.getSharedOwnerIds>
</entry>
```

--------------------------------

### Create Simple Job (REST API)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

Creates a simple job using the Job.create method. This example demonstrates how to define a job with a name, type, command, and other runtime criteria. The 'job' object contains all necessary details for job creation.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://purl.org/atom/ns#">
<id>xxx</id>
<tes:Job.create xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tes:job>
<tes:name>abc_job1</tes:name>
<tes:type>2</tes:type>
<tes:active>Y</tes:active>
<tes:ownerid>1</tes:ownerid>
<tes:command>hostname</tes:command>
<tes:runuserid>9</tes:runuserid>
<tes:agentid>59</tes:agentid>
<tes:saveoutputoption>Y</tes:saveoutputoption>
</tes:job>
</tes:Job.create>
</entry>
```

--------------------------------

### Filter Job Runs by Date and Name Prefix (GET and POST)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Retrieve job runs that match a specific date and whose names start with a given prefix. The GET request uses a URL parameter combining date equality and a STARTSWITH function, while the POST request uses an XML payload. This allows for more complex filtering criteria.

```Java
URL url = new URL("http://www.mycompanyscheduler.com:8080/api/tes-6.5/JobRun.getList?query= RUNDATE = '20201225' AND STARTSWITH( name, 'JP')");
```

```XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://purl.org/atom/ns#">
<atom:id>1</atom:id>
<atom:title>api</atom:title>
<JobRun.getList>
<selectColumns> id,ownerid,parentid,parentname,runtimeusername
</selectColumns>
<queryCondition>
RUNDATE = '20201225' AND STARTSWITH( name, 'JP')
</queryCondition>
</JobRun.getList>
</atom:entry>
```

--------------------------------

### Get List of Ownership Policies

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Ownership%20Policy

Retrieves a list of ownership policies using the shared owner ID via the `getPoliciesBySharedOwnerId` method.

```APIDOC
## GET /OwnershipPolicy/getPoliciesBySharedOwnerId

### Description
Retrieves a list of ownership policies associated with a specific shared owner ID.

### Method
GET

### Endpoint
/OwnershipPolicy/getPoliciesBySharedOwnerId

### Parameters
#### Query Parameters
- **sharedOwnerId** (string) - Required - The ID of the shared owner to filter policies by.

### Request Example
```
GET /OwnershipPolicy/getPoliciesBySharedOwnerId?sharedOwnerId=123
```

### Response
#### Success Response (200)
- **policies** (array of objects) - A list of ownership policies.
  - **policyId** (string) - The ID of the ownership policy.
  - **name** (string) - The name of the ownership policy.
  - **description** (string) - A description of the ownership policy.

#### Response Example
```json
{
  "policies": [
    {
      "policyId": "policy-abc",
      "name": "Default Policy",
      "description": "Standard ownership policy."
    },
    {
      "policyId": "policy-def",
      "name": "High Priority Policy",
      "description": "Policy for critical jobs."
    }
  ]
}
```
```

--------------------------------

### Accessing TA APIs via SOAP UI Tool

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Instructions for accessing TA APIs using the SOAP UI tool, including the required request format and endpoint.

```APIDOC
## Accessing TA APIs via SOAP UI Tool

### Description
TA APIs can be accessed from the SOAP UI tool. The request must be in XML format.

### Method
Send an XML request to the following endpoint:

### Endpoint
`http://<ClientManager_server_hostname>:<port>/api/<Plugin_Name>/postbody`
```

--------------------------------

### Client Manager Session Token Authentication

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Explains how to authenticate using session tokens, including basic authentication with username and password, and the use of session cookies (CSTSED and Session-Token) for subsequent requests.

```APIDOC
## Client Manager Session Token Authentication

When session tokens are enabled in the Client Manager configuration (Auth.Token.Enabled=Y), basic and API-token authentication are impacted.

### Basic Authentication Example

To authenticate using basic authentication (username and password):

```bash
curl -s -v -u <username>:<password> http://localhost:8080/api/production/MasterNode.checkMasterConnectionStatus
```

### Session Cookie Handling

The Client Manager sends a response containing session cookies (`CSTSED` and `Session-Token`) that must be included in all future requests to maintain the session.

**Initial Request Example:**

```bash
curl -s -v -u <username>:<password> http://localhost:8080/api/production/MasterNode.checkMasterConnectionStatus
```

**Subsequent Request Example (with cookies):**

```bash
curl -s -v http://localhost:8080/api/production/MasterNode.checkMasterConnectionStatus -H "cookie: CSTSED=node015x2z5kt91n8av8cgkl7zeh6v5" -H "cookie: Session-Token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInJlbW90ZS1ob3N0XCI6XCIwOjA6MDowOjA6MDowOjFcIixcInVzZXJcIjpcInZpbmNlbnRsXCIsXCJ1c2VyLWFnZW50XCI6XCJjdXJsLzcuNTUuMVwifSIsImlhdCI6MTYwMzMwNjk5MCwiZXhwIjoxNjAzMzA3MjkwfQ.E-VU4mOWsMhLzOk92tlZidE92UWFCscYkoWSeDvJVFAYRp7HnXF-tpkSqt4 ypVm07lDrxTLl6I7Tx4o0FeyyGQ"
```

All subsequent responses contain the cookies you must provide in the next request.
```

--------------------------------

### LDAP Group API

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/LDAP%20Group

This section details the API endpoint for creating an LDAP group. It explains the structure of the request body and provides an example.

```APIDOC
## POST /api/ldap/groups

### Description
Creates a new LDAP group within the TA system. This allows for the import of LDAP users and their associated security policies into TA for improved user audit trails and management.

### Method
POST

### Endpoint
/api/ldap/groups

### Parameters
#### Request Body
- **id** (integer) - Optional - The desired ID for the LDAP group. If not provided, the system may assign one.
- **title** (string) - Required - The title or name of the LDAP group.
- **category** (object) - Required - Defines the group category.
  - **term** (string) - Required - The term for the category (e.g., "0").
  - **scheme** (string) - Required - The scheme for the category (e.g., "group").
  - **label** (string) - Optional - A label for the category.
- **users_create** (object) - Required - Contains details for creating associated users within the LDAP group context.
  - **security_policy_name** (string) - Required - The name of the security policy to be applied.
  - **all_agents** (string) - Required - Specifies if the user has access to all agents ('Y' or 'N').
  - **win_group** (string) - Required - Specifies if the user is granted access to a specific Windows group ('Y' or 'N').
  - **domain** (string) - Required - The associated domain for the user.
  - **security_policy_id** (integer) - Required - The ID of the security policy.
  - **name** (string) - Required - The name of the user being created.
  - **superuser** (string) - Required - Specifies if the user is a superuser ('Y' or 'N').
  - **all_agent_lists** (string) - Required - Specifies if the user has access to all agent lists ('Y' or 'N').

### Request Example
```json
{
  "entry": {
    "id": "1",
    "title": "JMS",
    "category": {
      "term": "0",
      "scheme": "group",
      "label": ""
    },
    "users_create": {
      "security_policy_name": "Administrator",
      "all_agents": "Y",
      "win_group": "Y",
      "domain": "ad",
      "security_policy_id": 4,
      "name": "domain admins2",
      "superuser": "N",
      "all_agent_lists": "Y"
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the successful creation of the LDAP group.

#### Response Example
```json
{
  "message": "LDAP group 'JMS' created successfully."
}
```
```

--------------------------------

### Get Job Tags (XML)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Job

Retrieves a comma-separated string of tag names mapped to a specific job. Requires the job's ID.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Job.getTags xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<id>1</id>
</tes:Job.getTags>
</entry>
```

--------------------------------

### Generate API Key (curl)

Source: https://documentation.tidalsoftware.com/tidal-2024.2/Content/TA-REST-API-refrence-guide/Using%20the%20TA%20REST%20API

Shows how to generate a one-time use, base64 encoded API key using a POST request to the /auth/key endpoint. This key is required for client authentication and expires after 10 minutes if not used.

```curl
curl -s -v -X POST http://localhost:8080/auth/key
```

```http
< HTTP/1.1 200 OK
< Content-Type: application/base64; charset=ISO-8859-1
< Content-Length: 392
< 
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxqYQ/bDMFDqHMxteELuidZdAVGIMiiWr4K2u6bsKzrLEYWcoS+pVysagrAkgxVRt7972H1RN4GQo87NItxzbKgVs+hA4xgXOQh1MSmNOZrTJwp5wPUL4QqSuYKmiYfF64nDf9fo8nbs9sQtmLPigx0e1v3pjPIGi5iKkpbr+gPLLuy/U9Ns7hzISNiO/dwwJPE6oRFX7/t9dAsbybZVR5Vcm63Bz2VmgS5+LllIfp99QsP8HSNOF7jcvH7g5/v5/5JlmIwPFAKQi1zc9eEXBf6y1Inn5sGkZ4/46lEbzQtQRezL/dMv9oI2LFq1lUyb0mfVrMrU1DbyoPkbwwuVnyQIDAQAB
```
Tokens:
Raw