Skip to main content
Version: 6.0

Job Scheduler API

Job​

A Job represents a list of active actions that work with search results. The search is performed according to the schedule specified when creating the task. The API allows you to retrieve information about jobs, add, update, and delete them.

Job Structure​

NameSyntaxDescription
name<string>Job name.
title<string>Job title.
description<string>Job description.
throttle<object>Job throttling (More details Throttle).
actions<array>List of active actions. Each active action is an object (More details Actions API).
global_params<object>Global job parameters in key-value format.
search<object>Search parameters that are executed when the job runs (More details Search).
run_with_roles<array>List of roles that can execute the job.
schedule<object>Job execution schedule (More details Schedule).
enabled<bool>Job status (enabled, disabled).
lock_duration_seconds<int>Time interval from the executed query to the next execution.
jitter<float>Random time offset.
_permissions<object>Job access permissions.

Throttle​

NameSyntaxDescription
time<string>Throttling time.
fields<array>List of fields by which throttling is performed. The list contains field names in string format.
Throttling

Suppression — a mechanism that filters out duplicate search results by specified fields during a defined time period.

Schedule​

NameSyntaxDescription
cron<object>Schedule task via Cron.
interval<object>Schedule task via interval values.
warning

The cron and interval parameters are mutually exclusive. If the cron field is specified, then the interval field must be absent (and vice versa).

Cron​

NameSyntaxDescription
expression<string>Cron expression.
timezone<string>Time zone.

Interval​

NameSyntaxDescription
start_time<string>Time from which the interval count starts.
period<int>Interval length.
unit<string>Unit of measurement. For example, MINUTES, HOURS, DAYS, etc.
NameSyntaxDescription
query<string>Query.
time_field<string>Name of the field containing the timestamp.
earliest<string>Start time of the search.
latest<string>End time of the search.

CRUD for Job​

Retrieve a List of All Jobs​

GET _core/job_scheduler/jobs/

Retrieve a Job by ID​

GET _core/job_scheduler/jobs/{job_id}

Add a New Job​

POST _core/job_scheduler/jobs/
{
  "title": "Testing Email with smtpConnection",
  "description": "test description",
  "throttle": {
    "time": "5m",
    "fields": []
  },
  "actions": [
    {
      "script": {
        "context": "/app/opensearch/utils/python/bin/python3 /app/opensearch/utils/scripts/file_write_script.py",
        "is_once": false,
        "local_params": {}
      }
    }
  ],
  "global_params": {
    "key": "value"
  },
  "search": {
    "sme": {
      "query": "source internal_audit-* qsize=5;",
      "time_field": "@timestamp",
      "earliest": "now-24h",
      "latest": "now"
    }
  },
  "run_with_roles": [],
  "name": "Testing_Email_with_smtpConnection",
  "schedule": {
    "cron": {
      "expression": "* * * * *",
      "timezone": "Asia/Dubai"
    }
  },
  "enabled": false,
  "lock_duration_seconds": 30,
  "_permissions": {
    "owner": "admin",
    "read": {
      "roles": [],
      "users": []
    },
    "write": {
      "roles": [],
      "users": []
    }
  }
}

Updating the task​

PUT _core/job_scheduler/job/{job_id}
{
  "title": "Testing Email with smtpConnection",
  "throttle": {
    "time": "5m",
    "fields": []
  },
  "actions": [
    {
      "script": {
        "context": "/app/opensearch/utils/python/bin/python3 /app/opensearch/utils/scripts/file_write_script.py",
        "is_once": false,
        "local_params": {}
      }
    }
  ],
  "global_params": {},
  "search": {
    "sme": {
      "query": "source internal_audit-* qsize=5;",
      "time_field": "@timestamp",
      "earliest": "now-24h",
      "latest": "now"
    }
  },
  "run_with_roles": [],
  "name": "Testing_Email_with_smtpConnection",
  "schedule": {
    "cron": {
      "expression": "* * * * *",
      "timezone": "Asia/Dubai"
    }
  },
  "enabled": false,
  "lock_duration_seconds": 30,
  "_permissions": {
    "owner": "admin",
    "read": {
      "roles": [],
      "users": []
    },
    "write": {
      "roles": [],
      "users": []
    }
  }
}

Deleting a Job​

DELETE _core/job_scheduler/jobs/{job_id}

Writing to a Database​

The Write to DB settings are necessary for creating the corresponding active action. To create a Write to DB action, you must first have a list of JDBC users and a list of connections.

JDBC User​

NameSyntaxDescription
name<string>Arbitrary name for identifying the JDBC user.
username<string>User login used for database authentication.
password_id<string>Keystore key identifier. The password is obtained using a key with the prefix jobscheduler.jdbc.password.

Example:

{
  "name": "name",
  "username": "username",
  "password_id": "passwordId"
}

Connection​

NameSyntaxDescription
name<string>Database name.
driver<object>Database driver (e.g., postgres, clickhouse).
host<string>Host address where the database is located (e.g., localhost or an IP address).
port<string>Port number used to connect to the database.
db<string>Name of the database to which the connection is made.

Example:

{
  "name": "myDatabase",
  "driver": "postgres",
  "host": "localhost",
  "port": "5432",
  "db": "myDbName"
}

CRUD for JDBC User​

Retrieve a List of All Users​

GET _core/job_scheduler/jdbc_user/

Retrieve a User by ID​

GET _core/job_scheduler/jdbc_user/{jdbc_user_id}

Add a New User​

POST _core/job_scheduler/jdbc_user/
{
  "name": "name",
  "username": "username",
  "password_id": "passwordId"
}

Update a User​

PUT _core/job_scheduler/jdbc_user/{jdbc_user_id}
{
  "name": "name",
  "username": "username",
  "password_id": "passwordId"
}
Attention!

The password_id parameter must contain not the password itself, but the key identifier in Keystore. The key must have the prefix jobscheduler.jdbc.password..

info

The name parameter is used to specify an arbitrary name for the JDBC user, while username specifies the login used to connect to the database.

Update a User​

PUT _core/job_scheduler/jdbc_user/{jdbc_user_id}
{
  "name": "name",
  "username": "username",
  "password_id": "passwordId"
}

Delete a User​

DELETE _core/job_scheduler/jdbc_user/{jdbc_user_id}

User Password Setup​

POST _core/keystore/jobscheduler.jdbc.password.{password_id}
{
  "value" : "password"
}

CRUD for Connection​

Retrieve a List of All Connections​

GET _core/job_scheduler/jdbc_connection/

Retrieve a Connection by ID​

GET _core/job_scheduler/jdbc_connection/{connection_id}

Add a New Connection​

POST _core/job_scheduler/jdbc_connection
{
  "name": "myDatabase",
  "driver": "postgres",
  "host": "localhost",
  "port": "5432",
  "db": "myDbName"
}
warning

The driver parameter, indicating which JDBC driver will be used, can accept the following values:

  • postgres
  • mssql
  • oracle
  • hive
  • sap
  • clickhouse
info

The name parameter defines an arbitrary name for identifying the database, while db specifies its exact system name for establishing a connection.

Update a Connection​

PUT _core/job_scheduler/jdbc_connection/{connection_id}
{
  "name": "myDatabase",
  "driver": "postgres",
  "host": "localhost",
  "port": "5432",
  "db": "myDbName"
}

Delete a Connection​

DELETE _core/job_scheduler/jdbc_connection/{connection_id}

Mail​

The Mail settings are necessary for creating the corresponding active action and for sending emails to a group of recipients. To do this, you must first create the necessary number of recipients and then create a group from them. Using the API, the user can configure recipients, recipient groups, and SMTP.

warning

If smtp_id is not specified in the Mail Action, the sender settings will be taken from the .sm_settings index.

warning

If the recipient_group_id parameter is not specified in the Mail Action, the recipient will be the user specified in the to parameter.

Recipient

NameSyntaxDescription
name<string>Recipient name.
description<string>Recipient description.
type<string>Address type.
address<string>Recipient's email address.

Example:

{
  "name": "name",
  "description": "description",
  "type": "EMAIL",
  "address": "test@test.ru"
}

Recipient Group​

NameSyntaxDescription
name<string>Recipient group name.
description<string>Recipient group description.
recipient_ids<array>IDs of recipients recorded in the recipient index.
recipient_emails<array>List of recipient email addresses not recorded in the recipient index.

Example:

{
  "name": "name",
  "description": "description",
  "recipient_ids": ["id1", "id2"],
  "recipient_emails": ["test@test.org", "test2@test.org"]
}

SMTP​

The SMTP structure is as follows:

NameSyntaxDescription
name<string>SMTP server name.
description<string>SMTP server description.
host<string>SMTP server host address.
port<string>Port on which the SMTP server operates (e.g., 12345).
user<string>Username for authentication on the SMTP server.
user_email<string>Email address associated with the SMTP server account.
password_id<string>Keystore key identifier. The password is obtained using a key with the prefix jobscheduler.email.password..
timeout<int>Connection timeout to the SMTP server in milliseconds.
proto<string>Protocol used to connect to the SMTP server (e.g., ssl).

Example:

{
  "name": "name",
  "description": "description",
  "host": "host",
  "port": "12345",
  "user": "user",
  "user_email": "test@test.com",
  "password_id": "passwordId",
  "timeout": 5000,
  "proto": ""
}

CRUD for Recipient​

Retrieve a List of All Recipients​

GET _core/job_scheduler/recipients

Retrieve a Recipient by ID​

GET _core/job_scheduler/recipients/{recipient_id}

Add a New Recipient​

POST _core/job_scheduler/recipients
{
  "name": "name",
  "description": "description",
  "type": "EMAIL",
  "address": "test@test.org"
}

Update a Recipient​

PUT _core/job_scheduler/recipients/{recipient_id}
{
  "name": "name",
  "description": "description",
  "type": "EMAIL",
  "address": "test@test.org"
}

Delete a Recipient​

DELETE _core/job_scheduler/recipients/{recipient_id}

CRUD for Recipient Group​

Retrieve a List of All Recipient Groups​

GET _core/job_scheduler/recipient_groups

Retrieve a Recipient Group by ID​

GET _core/job_scheduler/recipient_groups/{recipient_group_id}

Add a New Recipient Group​

POST _core/job_scheduler/recipient_groups
{
  "name": "name",
  "description": "description",
  "recipient_ids": [
    "id1",
    "id2"
  ],
  "recipient_emails": [
    "test@test.org",
    "test2@test.org"
  ]
}

Update a Recipient Group​

PUT _core/job_scheduler/recipient_groups
{
  "name": "name",
  "description": "description",
  "recipient_ids": [
    "id1",
    "id2"
  ],
  "recipient_emails": [
    "test@test.org",
    "test2@test.org"
  ]
}

Delete a Recipient Group​

DELETE _core/job_scheduler/recipient_groups/{recipient_group_id}

CRUD for SMTP​

Retrieve a List of All SMTP​

GET _core/job_scheduler/smtp

Retrieve an SMTP by ID​

GET _core/job_scheduler/smtp/{smtp_id}

Add a New SMTP​

POST _core/job_scheduler/smtp
{
  "name": "name",
  "description": "description",
  "host": "host",
  "port": "12345",
  "user": "user",
  "user_email": "test@test.com",
  "password_id": "passwordId",
  "timeout": 5000,
  "proto": ""
}

Update an SMTP​

PUT _core/job_scheduler/smtp/{smtp_id}
{
  "name": "name",
  "description": "description",
  "host": "host",
  "port": "12345",
  "user": "user",
  "user_email": "test@test.com",
  "password_id": "passwordId",
  "timeout": 5000,
  "proto": ""
}

Delete an SMTP​

DELETE _core/job_scheduler/smtp/{smtp_id}
DELETE _core/job_scheduler/smtp/{smtp_id}