K

Executing Jobs

This document explains how to run jobs on a MikroTik router using both synchronous and asynchronous methods.

Synchronous Execution

The synchronous API is a wrapper around the MikroTik RouterOS native API. It allows you to make real-time API calls to the MikroTik via the management tunnel. This method is recommended for real-time read operations and not for configuration changes due to potential issues with delivery guarantees and idempotency.

The Synchronous API Object

PropertyTypeDescription
commandstringThe MikroTik API command to execute.
parametersstringOptional. Contains API parameters as defined in the MikroTik API documentation.

Endpoint

POST /api/synchronous/{router_id}

Payload Example: Listing ARP

{
  "command": "/ip/arp/print"
}

Response Example

{
  "status": "success",
  "data": [
    {
      "id": "*1",
      "address": "192.168.88.254",
      "mac_address": "50:32:37:7B:93:49",
      "interface": "bridge",
      "published": "false",
      "invalid": "false",
      "DHCP": "false",
      "dynamic": "true",
      "complete": "true",
      "disabled": "false"
    }
  ]
}

Making Configuration Changes

While it is possible to make changes using the synchronous API, it is recommended to use the asynchronous API for such operations. If you choose to use the synchronous API, use the /execute command with =script= in the parameters for easier command syntax.

Example: Adding an IP Address

{
  "command": "/execute",
  "parameters": "=script=/ip address add address=10.0.0.1/30 interface=ether1 disabled=no"
}

Important Note

The synchronous API does not guarantee delivery and does not implement idempotent requests. This means you might add the same configuration twice if using queuing systems on your side. Use this API mainly for real-time read operations.


Asynchronous Execution

The asynchronous API allows you to trigger actions on a MikroTik router without waiting for an immediate response. This method is more reliable for configuration changes and tasks that do not need to be executed in real-time.

How the Asynchronous System Works

  1. Job Submission: You submit a job to the API with a specific script and other optional parameters.
  2. Job Processing: The job is queued and processed asynchronously. If express_execute is set to true, the job is executed immediately.
  3. Notifications: You can provide a notify_url where the status of the job will be posted (e.g., loaded, running, completed, failed, or deleted).
  4. Acknowledgment: If needs_acknowledgement is true, the system waits for acknowledgment before marking the job as completed.

Request Body

PropertyTypeDescription
descriptionstringRequired. A brief description of the action. Visible in the portal when the user views the orchestration log. Max 100 characters.
scriptstringThe script to be executed asynchronously. Should be RouterOS commands separated by semicolons. Required, max 2000 characters.
make_backupbooleanIndicates whether a backup should be created before executing the script. Required, default is false.
express_executebooleanSpecifies whether the script should be executed without delay. When true, an attempt will be made to invoke the scheduler immediately. Default is false. Required.
needs_acknowledgementbooleanSpecifies whether the action requires acknowledgment. When false, the job will be marked as completed immediately, and no errors will be caught and reported. This is useful for tasks like rebooting a router when the script will be interrupted on the router before it notifies MikroCloud of the outcome. Required, default is true.
notify_urlstringThe URL to which notifications should be sent. Should start with https. MikroCloud will post job updates here when the job is loaded, running, completed, failed, or deleted. Optional.

Endpoint

POST /api/asynchronous/{router_id}

Example Request

{
  "description": "Log test message",
  "script": ":log info test",
  "make_backup": false,
  "express_execute": false,
  "needs_acknowledgement": false,
  "notify_url": "https://example.com/notify"
}

Response Example

{
  "status": "success",
  "data": {
    "idempotency_key": "7bbb8378-1675-515d-8ef4-ddb784fd0e52",
    "request_id": "2859d7db-bd7f-5d0d-b973-89142ff7b202",
    "target": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "notify_url": "https://example.com/notify",
    "date": "2024-05-28T08:05:28+00:00"
  }
}

The Response Object

PropertyTypeDescription
idempotency_keystringA unique key to ensure idempotent requests.
request_idstringThe unique identifier for the request.
targetstringThe router ID for which the job is being executed.
notify_urlstringThe URL to which notifications will be sent.
datestringThe timestamp of when the request was made.

Notification Payload

When a job is executed asynchronously, the status of the job is posted back to the provided notify_url. The payload includes details about the job, its status, and other relevant information.

Example Payload

{
  "job_id": "00000000-0000-0000-0000-000000000001",
  "customer_id": "00000000-0000-0000-0000-000000000002",
  "description": "example description",
  "router_id": "00000000-0000-0000-0000-000000000003",
  "idempotency_key": "00000000-0000-0000-0000-000000000004",
  "express_execute": false,
  "needs_acknowledgement": true,
  "make_backup": false,
  "seq_id": 1234567890,
  "started_at": "2024-05-28T06:14:19+00:00",
  "completed_at": "2024-05-28T06:14:21+00:00",
  "failed_at": null,
  "deleted_at": null,
  "status": "completed"
}

Payload Object

PropertyTypeDescription
job_idstringThe unique identifier for the job.
customer_idstringThe unique identifier for the customer.
descriptionstringA brief description of the job.
router_idstringThe unique identifier for the router.
idempotency_keystringA unique key to ensure idempotent requests.
express_executebooleanIndicates whether the job was executed immediately.
needs_acknowledgementbooleanSpecifies whether the action required acknowledgment.
make_backupbooleanIndicates whether a backup was made before executing the script.
seq_idintegerThe sequence ID of the job.
started_atstringThe timestamp of when the job started.
completed_atstringThe timestamp of when the job was completed.
failed_atstringThe timestamp of when the job failed, if applicable.
deleted_atstringThe timestamp of when the job was deleted, if applicable.
statusenumThe current status of the job (e.g., "completed", "failed", "deleted", "pending", "running").

Retrieve a List of Jobs

The /api/routers/{router_id}/jobs endpoint allows you to retrieve a list of jobs executed on a specific router. This can be useful for monitoring and managing the tasks performed on your MikroTik routers.

Endpoint

GET /api/routers/{router_id}/jobs

Sample Response

{
  "status": "success",
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "token": "exampleToken123",
      "idempotency_key": "00000000-0000-0000-0000-000000000002",
      "description": "Example Job Description",
      "express_execute": false,
      "needs_acknowledgement": true,
      "make_backup": false,
      "started_at": "2024-05-29T00:11:49+00:00",
      "completed_at": "2024-05-29T00:12:08+00:00",
      "failed_at": null,
      "deleted_at": null,
      "status": "completed"
    }
  ]
}

Was this page helpful?