Job Scheduler API

Job

Job Overview

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

Name	Syntax	Description
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.
_permission	<object>	Job access permissions.

Throttle

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

Throttling

Throttling discards similar search results for the fields to be throttled over the selected time period.

Schedule

Name	Syntax	Description
cron	<object>	Schedule task via Cron.
interval	<object>	Schedule task via interval values.

warning

Cron and Interval are mutually exclusive. If the cron field is present, the interval field must be absent.

Cron

Name	Syntax	Description
expression	<string>	Cron expression.
timezone	<string>	Time zone.

Interval

Name	Syntax	Description
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.

Search

Name	Syntax	Description
query	<string>	Query.
timefield	<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/
{
  "name": "example_job",
  "title": "Example Job",
  "description": "This is an example job.",
  "throttle": {
    "time": "5m",
    "fields": ["field1", "field2"]
  },
  "actions": [
    {
      "type": "email",
      "to": "example@example.com",
      "subject": "Job Notification",
      "body": "This is a notification email."
    }
  ],
  "global_params": {
    "param1": "value1",
    "param2": "value2"
  },
  "search": {
    "query": "index=example earliest=-24h latest=now",
    "timefield": "@timestamp",
    "earliest": "-24h",
    "latest": "now"
  },
  "run_with_roles": ["role1", "role2"],
  "schedule": {
    "cron": {
      "expression": "0 0 * * *",
      "timezone": "UTC"
    }
  },
  "enabled": true,
  "lock_duration_seconds": 300,
  "jitter": 0.5,
  "_permission": {
    "read": ["role1", "role2"],
    "write": ["role1"]
  }
}

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

Name	Syntax	Description
name	<string>	User name.
username	<string>	Database username.
password_id	<string>	Key in the keystore with the prefix jobscheduler.jdbc.password., which can be used to retrieve the database user's password.

Example:

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

Connection

Name	Syntax	Description
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"
}

Delete a User

DELETE _core/job_scheduler/jdbc_user/{jdbc_user_id}

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"
}

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

Name	Syntax	Description
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

Name	Syntax	Description
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:

Name	Syntax	Description
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>	Key in the keystore with the prefix jobscheduler.email.password., which can be used to retrieve the user's 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}