Reference - IOM REST API - Schedules 1.0


Product Version

3.0

Product To Version


Status

final

Download Specification 

This API specification is available for download as an Open API 3.0 YAML file: 

Authentication

Basic Authentication

Please configure your clients to use this authentication method to submit user name and password.

Bearer Token Authentication

To generate a valid JWT, just log into the OMT, inspect the browser cookies and use the value of the cookie called 'OMS_IDENTITY' as JWT. Within a UI-client (e.g., Postman) choose "Bearer Token" and just type in a valid Json Web Token (JWT).

Authorization

The permission "View schedules" (group REST services) is required to use the GET endpoints and must be assigned at shop or supplier, that has a relation to the transmission.
The permission "Manage schedules" (group REST services) is required to use the POST endpoints and must be assigned at shop or supplier, that has a relation to the transmission.

API Specification

Introduction

OpenAPI Version: 3.0.0
IOM Schedule REST API Version: 1.0

The IOM Schedule REST API supports tasks to view and manage schedules of the IOM.

scheduleConfigs API

GET
/scheduleconfigs Get schedules by search criterias.

Request Path

/scheduleconfigs

Description

Returns all schedules for selected search criterias.
This will include basic and runtime configuration. For attributes having a runtime equivalent, those - when set - will be used for the search instead of the basic configuration.

Request Body

--

Request Parameters

LocationNameFormatDescription
in queryactivebooleanWhether the schedule is active or not.
in queryidsarrayThe id of the schedule.
in queryjobNamesarrayThe name of the job associated to the schedule.
in querykeysarrayThe key associated to the schedule.
in queryisLockedbooleanWhether the schedule is currently locked or not.
in querywillRetrybooleanFailed schedules with a retry timestamp.
in queryorderBy--
in querysortDirection--
in querylimitintegerThe number of items to return.
If not set the limit is 1000. | Default: 1000
in queryoffsetintegerThe number of items to skip before starting to collect the result set. | Default: 0

Response

200 - OK

The response for a schedule collection request.
ScheduleCollectionContainer application/json{
  • "meta":
    object
    A CollectionMetaData object. The meta data of the collection.
    {
    • "totalCount":
      integer
      The total number of objects in the collection (without offset and limit). | Format: int64 | Example: 10000
    }
  • "data":
    array
    An array of Schedule objects. The core data of the schedule collection.
    [
    Schedule: Represents the current state of the schedule including basic and runtime configuration.
    The basic configuration parameters have the suffix `Configured`.
    The runtime configuration parameters have the suffix `Runtime`. If not set, the basic configuration will be used.

    {
    • "id":
      integer
      The schedule identifier. | Example: 107
    • "activeConfigured":
      boolean
      Only active schedules can be run. Basic configuration, can be overwritten with activeRuntime. | Example: true
    • "activeRuntime":
      boolean
      Runtime configuration to overwrite the activeConfigured-flag. | Example: true
    • "configId":
      integer
      Referrences an internal implementation. Must not be modified. This is a information for the internal job name associated to the schedule.' | Example: 1
    • "key":
      string
      Textual schedule identificator, not enforced to be unique. Must not be modified. | Example: CHECK_FOR_DATAPACK_FILES
    • "cronConfigured":
      string
      Cron expression to define the job run times. Must match the quartz cron syntax. Basic configuration, can be overwritten with cronRuntime. | Example: 0 45 23 L 1/1 ? *
    • "cronRuntime":
      string
      Runtime configuration to overwrite the cronConfigured expression. | Example: 0 45 23 L 1/1 ? *
    • "reactivateOnStartConfigured":
      boolean
      When true, jobs that did reach their maxNoOfRetries will be resetted automatically on the next controller startup.
      This happens during a deployment or fail over. Basic configuration, can be overwritten with reactivateOnStartRuntime. | Example: true
    • "reactivateOnStartRuntime":
      boolean
      Runtime configuration to overwrite the reactivateOnStartConfigured-flag.
    • "jobName":
      string
      Name of the internal job associated to the schedule. | Example: checkForDatapackFiles
    • "lastRun":
      string
      Last check or execution of the schedule (successfully or not). This attribute is further updated for schedules that won't be executed after the maxNoOfRetries has been reached. | Format: date-time
    • "lockedSince":
      string
      Corresponds to the start time of jobs currently running. | Format: date-time
    • "retryCount":
      integer
      Number of failures since the last successful run. | Example: 2
    • "maxNoOfRetriesConfigured":
      integer
      How often a failed schedule will be retried.
      The schedule will stop execute after this limit is reached. To nevertheless force the schedule execution you can either raise this limit with maxNoOfRetriesRuntime or set a next execution time per hand (choosing a timestamp in the past should trigger the schedule within the next minute). | Example: 25
    • "maxNoOfRetriesRuntime":
      integer
      Runtime configuration to overwrite maxNoOfRetriesConfigured. | Example: 30
    • "retryDelayConfigured":
      string
      Time interval between retries of failed schedules. Basic configuration, can be overwritten with retryDelayRuntime. | Example: 7m
    • "retryDelayRuntime":
      string
      Runtime configuration to overwrite retryDelayConfigured. | Example: 7m
    • "nextRetryDate":
      string
      When a failed schedule will next be retried. Can be overwritten at runtime with nextRun. | Format: date-time
    • "fixedNextRun":
      string
      Runtime configuration. When set, this define the next time when the schedule should run.
      This attribute is resetted to null when the schedule is then being attempted (independently of it's success or error status).
      The nextRetryDate, crons and maxNoOfRetries have no effect when fixedNextRun is set; only the active[Runtime] status is still respected. | Format: date-time
    • "description":
      string
      The description of the schedule. | Example: Check for datapack files.
    }
    ]
}

400 - Bad Request

- Generic or business logic validation error.
ErrorReport application/json{
  • "status":
    integer
    The HTTP status code. | Format: int32 | Example: 403
  • "errors":
    array
    An array of Error objects.
    [
    Error:
    {
    • "code":
      string
      Required | Exception / Error code | Example: VALIDATION_EXCEPTION
    • "message":
      string
      Required | Exception / Error message | Example: Attribute XYZ is mandatory
    • "value":
      object
      Value which caused the exception / error.
    }
    ]
}

401 - Unauthorized

- Authentication information is missing or invalid.
Response HeaderDescription
WWW-Authenticate

403 - Forbidden

- the user is not authorized to use this resource.

406 - Not Acceptable

- A representation of the response in the media type that was requested in the ACCEPT header cannot be provided.

500 - Internal Server Error

- An unexpected error occured.
GET
/scheduleconfigs/{scheduleId} Get a schedule by id.

Request Path

/scheduleconfigs/{scheduleId}

Description

Returns a schedule for the given id.
This will include basic and runtime configuration. For attributes having a runtime equivalent, those - when set - will be used for the search instead of the basic configuration.

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathscheduleIdintegerRequired | The id of the schedule. | Example: 107

Response

200 - OK

Definition of the requested schedule.
Schedule application/json{
  • "id":
    integer
    The schedule identifier. | Example: 107
  • "activeConfigured":
    boolean
    Only active schedules can be run. Basic configuration, can be overwritten with activeRuntime. | Example: true
  • "activeRuntime":
    boolean
    Runtime configuration to overwrite the activeConfigured-flag. | Example: true
  • "configId":
    integer
    Referrences an internal implementation. Must not be modified. This is a information for the internal job name associated to the schedule.' | Example: 1
  • "key":
    string
    Textual schedule identificator, not enforced to be unique. Must not be modified. | Example: CHECK_FOR_DATAPACK_FILES
  • "cronConfigured":
    string
    Cron expression to define the job run times. Must match the quartz cron syntax. Basic configuration, can be overwritten with cronRuntime. | Example: 0 45 23 L 1/1 ? *
  • "cronRuntime":
    string
    Runtime configuration to overwrite the cronConfigured expression. | Example: 0 45 23 L 1/1 ? *
  • "reactivateOnStartConfigured":
    boolean
    When true, jobs that did reach their maxNoOfRetries will be resetted automatically on the next controller startup.
    This happens during a deployment or fail over. Basic configuration, can be overwritten with reactivateOnStartRuntime. | Example: true
  • "reactivateOnStartRuntime":
    boolean
    Runtime configuration to overwrite the reactivateOnStartConfigured-flag.
  • "jobName":
    string
    Name of the internal job associated to the schedule. | Example: checkForDatapackFiles
  • "lastRun":
    string
    Last check or execution of the schedule (successfully or not). This attribute is further updated for schedules that won't be executed after the maxNoOfRetries has been reached. | Format: date-time
  • "lockedSince":
    string
    Corresponds to the start time of jobs currently running. | Format: date-time
  • "retryCount":
    integer
    Number of failures since the last successful run. | Example: 2
  • "maxNoOfRetriesConfigured":
    integer
    How often a failed schedule will be retried.
    The schedule will stop execute after this limit is reached. To nevertheless force the schedule execution you can either raise this limit with maxNoOfRetriesRuntime or set a next execution time per hand (choosing a timestamp in the past should trigger the schedule within the next minute). | Example: 25
  • "maxNoOfRetriesRuntime":
    integer
    Runtime configuration to overwrite maxNoOfRetriesConfigured. | Example: 30
  • "retryDelayConfigured":
    string
    Time interval between retries of failed schedules. Basic configuration, can be overwritten with retryDelayRuntime. | Example: 7m
  • "retryDelayRuntime":
    string
    Runtime configuration to overwrite retryDelayConfigured. | Example: 7m
  • "nextRetryDate":
    string
    When a failed schedule will next be retried. Can be overwritten at runtime with nextRun. | Format: date-time
  • "fixedNextRun":
    string
    Runtime configuration. When set, this define the next time when the schedule should run.
    This attribute is resetted to null when the schedule is then being attempted (independently of it's success or error status).
    The nextRetryDate, crons and maxNoOfRetries have no effect when fixedNextRun is set; only the active[Runtime] status is still respected. | Format: date-time
  • "description":
    string
    The description of the schedule. | Example: Check for datapack files.
}

400 - Bad Request

- Generic or business logic validation error.
ErrorReport application/json{
  • "status":
    integer
    The HTTP status code. | Format: int32 | Example: 403
  • "errors":
    array
    An array of Error objects.
    [
    Error:
    {
    • "code":
      string
      Required | Exception / Error code | Example: VALIDATION_EXCEPTION
    • "message":
      string
      Required | Exception / Error message | Example: Attribute XYZ is mandatory
    • "value":
      object
      Value which caused the exception / error.
    }
    ]
}

401 - Unauthorized

- Authentication information is missing or invalid.
Response HeaderDescription
WWW-Authenticate

403 - Forbidden

- the user is not authorized to use this resource.

406 - Not Acceptable

- A representation of the response in the media type that was requested in the ACCEPT header cannot be provided.

500 - Internal Server Error

- An unexpected error occured.

scheduleStates API

GET
/schedulestates Get the schedules current states by search criterias.

Request Path

/schedulestates

Description

Returns all schedules for the selected search criterias.
For attributes having a runtime equivalent those - when set - will be used for the search instead of the basic configuration.

Request Body

--

Request Parameters

LocationNameFormatDescription
in queryactivebooleanWhether the schedule is active or not.
in queryidsarrayThe id of the schedule.
in queryjobNamesarrayThe name of the job associated to the schedule.
in querykeysarrayThe key associated to the schedule.
in queryisLockedbooleanWhether the schedule is currently locked or not.
in querystoppedbooleanSchedules that will not run by themselves (inactive or having reached the maxNoOfRetries).
in queryorderBy--
in querysortDirection--
in querylimitintegerThe number of items to return.
If not set the limit is 1000. | Default: 1000
in queryoffsetintegerThe number of items to skip before starting to collect the result set. | Default: 0

Response

200 - OK

The response for a schedule collection request.
ScheduleStateCollectionContainer application/json{
  • "meta":
    object
    A CollectionMetaData object. The meta data of the collection.
    {
    • "totalCount":
      integer
      The total number of objects in the collection (without offset and limit). | Format: int64 | Example: 10000
    }
  • "data":
    array
    An array of ScheduleState objects. The core data of the schedule state collection.
    [
    ScheduleState: Represents the current state of the schedule.
    For attributes having a runtime equivalent those - when set - will be used for the search instead of the basic configuration.

    Note that attributes marked as `read-only`, will be ignored as part of a request.
    To support automatically generated mappers, the schema property of OpenApi-specification �readOnly�, was not used here.

    {
    • "id":
      integer
      The id of the schedule. read-only | Example: 107
    • "active":
      boolean
      Current active status. Only active schedules can be run. | Example: true
    • "configId":
      integer
      Referrences an internal implementation. Must not be modified. This is a information for the internal job name associated to the schedule. read-only | Example: 1
    • "key":
      string
      Textual schedule identificator, not enforced to be unique. read-only | Example: CHECK_FOR_DATAPACK_FILES
    • "cron":
      string
      Current cron expression.Cron expression to define the job run times. Must match the quartz cron syntax. | Example: 0 45 23 L 1/1 ? *
    • "reactivateOnStart":
      boolean
      Current value. When true, jobs that did reach their maxNoOfRetries will be resetted automatically on the next controller startup. This happens during a deployment or fail over. | Example: true
    • "jobName":
      string
      Name of the internal job associated to the schedule. read-only | Example: checkForDatapackFiles
    • "lastRun":
      string
      Last check or execution of the schedule (successfully or not). This attribute is further updated for schedules that won't be executed after the maxNoOfRetries has been reached. read-only | Format: date-time
    • "lockedSince":
      string
      Corresponds to the start time of jobs currently running. read-only | Format: date-time
    • "retryCount":
      integer
      Number of failures since the last successful run. | Example: 2
    • "maxNoOfRetries":
      integer
      Current value. How often a failed schedule will be retried. The schedule will stop execute after this limit is reached. To nevertheless force the schedule execution you can either raise this limit or set a next execution time per hand (choosing a timestamp in the past should trigger the schedule within the next minute). | Example: 25
    • "retryDelay":
      string
      Current value. Time interval between retries of failed schedules. | Example: 7m
    • "nextRun":
      string
      Next time when a failed schedule will be retried.
      This value can be set by hand (fixedNextRun) or is defined after an attempt failure as long as the maxNoOfRetries is not reached.
      Is ignored by inactive schedules. When not set, then the next attempt is determined from the cron expression (given the schedule is active and the maxNoOfRetries has not been reached). This attribute is internally resetted to null when the schedule has run successfully or after the maxNoOfRetries has been reached. | Format: date-time
    • "description":
      string
      Schedule description. read-only | Example: Check for Datapack files.
    }
    ]
}

400 - Bad Request

- Generic or business logic validation error.
ErrorReport application/json{
  • "status":
    integer
    The HTTP status code. | Format: int32 | Example: 403
  • "errors":
    array
    An array of Error objects.
    [
    Error:
    {
    • "code":
      string
      Required | Exception / Error code | Example: VALIDATION_EXCEPTION
    • "message":
      string
      Required | Exception / Error message | Example: Attribute XYZ is mandatory
    • "value":
      object
      Value which caused the exception / error.
    }
    ]
}

401 - Unauthorized

- Authentication information is missing or invalid.
Response HeaderDescription
WWW-Authenticate

403 - Forbidden

- the user is not authorized to use this resource.

406 - Not Acceptable

- A representation of the response in the media type that was requested in the ACCEPT header cannot be provided.

500 - Internal Server Error

- An unexpected error occured.
GET
/schedulestates/{scheduleId} Get the schedule state by id.

Request Path

/schedulestates/{scheduleId}

Description

Returns the states of a single schedule for the given id.

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathscheduleIdintegerRequired | The id of the schedule. | Example: 107

Response

200 - OK

Definition of the requested schedule.
ScheduleState application/json{
  • "id":
    integer
    The id of the schedule. read-only | Example: 107
  • "active":
    boolean
    Current active status. Only active schedules can be run. | Example: true
  • "configId":
    integer
    Referrences an internal implementation. Must not be modified. This is a information for the internal job name associated to the schedule. read-only | Example: 1
  • "key":
    string
    Textual schedule identificator, not enforced to be unique. read-only | Example: CHECK_FOR_DATAPACK_FILES
  • "cron":
    string
    Current cron expression.Cron expression to define the job run times. Must match the quartz cron syntax. | Example: 0 45 23 L 1/1 ? *
  • "reactivateOnStart":
    boolean
    Current value. When true, jobs that did reach their maxNoOfRetries will be resetted automatically on the next controller startup. This happens during a deployment or fail over. | Example: true
  • "jobName":
    string
    Name of the internal job associated to the schedule. read-only | Example: checkForDatapackFiles
  • "lastRun":
    string
    Last check or execution of the schedule (successfully or not). This attribute is further updated for schedules that won't be executed after the maxNoOfRetries has been reached. read-only | Format: date-time
  • "lockedSince":
    string
    Corresponds to the start time of jobs currently running. read-only | Format: date-time
  • "retryCount":
    integer
    Number of failures since the last successful run. | Example: 2
  • "maxNoOfRetries":
    integer
    Current value. How often a failed schedule will be retried. The schedule will stop execute after this limit is reached. To nevertheless force the schedule execution you can either raise this limit or set a next execution time per hand (choosing a timestamp in the past should trigger the schedule within the next minute). | Example: 25
  • "retryDelay":
    string
    Current value. Time interval between retries of failed schedules. | Example: 7m
  • "nextRun":
    string
    Next time when a failed schedule will be retried.
    This value can be set by hand (fixedNextRun) or is defined after an attempt failure as long as the maxNoOfRetries is not reached.
    Is ignored by inactive schedules. When not set, then the next attempt is determined from the cron expression (given the schedule is active and the maxNoOfRetries has not been reached). This attribute is internally resetted to null when the schedule has run successfully or after the maxNoOfRetries has been reached. | Format: date-time
  • "description":
    string
    Schedule description. read-only | Example: Check for Datapack files.
}

400 - Bad Request

- Generic or business logic validation error.
ErrorReport application/json{
  • "status":
    integer
    The HTTP status code. | Format: int32 | Example: 403
  • "errors":
    array
    An array of Error objects.
    [
    Error:
    {
    • "code":
      string
      Required | Exception / Error code | Example: VALIDATION_EXCEPTION
    • "message":
      string
      Required | Exception / Error message | Example: Attribute XYZ is mandatory
    • "value":
      object
      Value which caused the exception / error.
    }
    ]
}

401 - Unauthorized

- Authentication information is missing or invalid.
Response HeaderDescription
WWW-Authenticate

403 - Forbidden

- the user is not authorized to use this resource.

406 - Not Acceptable

- A representation of the response in the media type that was requested in the ACCEPT header cannot be provided.

500 - Internal Server Error

- An unexpected error occured.
PATCH
/schedulestates/{scheduleId} Set the runtime configuration of a schedule.

Request Path

/schedulestates/{scheduleId}

Description

Allows to overwrite basic configuration parameters with runtime values.

Request Body

ScheduleUpdate application/json{
  • "active":
    boolean
    Only active schedules will be run. | Example: true
  • "cron":
    string
    Cron expression to define the job run times. Must match the quartz cron syntax. | Example: 0 45 23 L 1/1 ? *
  • "reactivateOnStart":
    boolean
    When true, jobs that did reach their maxNoOfRetries will be resetted automatically on the next controller startup. This happens during a deployment or fail over. | Example: true
  • "maxNoOfRetries":
    integer
    How often a failed schedule will be retried. The schedule will stop execute after this limit is reached. To nevertheless force the schedule execution you can either raise this limit with maxNoOfRetriesRuntime or set a next execution time per hand (choosing a timestamp in the past should trigger the schedule within the next minute). | Example: 25
  • "retryDelay":
    string
    Time interval between retries of failed schedules. | Example: 7m
  • "fixedNextRun":
    string
    Fix time when the schedule will next be attempted. When set, the cron expression and maxNoOfRetries will be ignored. Setting this time in the past will call it as soon as possible (due schedules are checked for only once per minute).
    This value will be removed unconditionally after the attempt. | Format: date-time
  • "removeLock":
    boolean
    Internally, the lock exists when the start time of running jobs is set within the attribute lockedSince. You cannot modify this timestamp but can set it to null in order to remove the lock. Beware that this may lead to parallel process executions. | Example: false
  • "resetList":
    array
    An array of string literals. List of attribute where a possible runtime configuration must be removed. Those of these attributes also present with a value within the request will be ignored (the reset list wins.)
}

Request Parameters

LocationNameFormatDescription
in pathscheduleIdintegerRequired | The id of the schedule. | Example: 107

Response

200 - OK

Returns the updated schedule definition.
ScheduleState application/json{
  • "id":
    integer
    The id of the schedule. read-only | Example: 107
  • "active":
    boolean
    Current active status. Only active schedules can be run. | Example: true
  • "configId":
    integer
    Referrences an internal implementation. Must not be modified. This is a information for the internal job name associated to the schedule. read-only | Example: 1
  • "key":
    string
    Textual schedule identificator, not enforced to be unique. read-only | Example: CHECK_FOR_DATAPACK_FILES
  • "cron":
    string
    Current cron expression.Cron expression to define the job run times. Must match the quartz cron syntax. | Example: 0 45 23 L 1/1 ? *
  • "reactivateOnStart":
    boolean
    Current value. When true, jobs that did reach their maxNoOfRetries will be resetted automatically on the next controller startup. This happens during a deployment or fail over. | Example: true
  • "jobName":
    string
    Name of the internal job associated to the schedule. read-only | Example: checkForDatapackFiles
  • "lastRun":
    string
    Last check or execution of the schedule (successfully or not). This attribute is further updated for schedules that won't be executed after the maxNoOfRetries has been reached. read-only | Format: date-time
  • "lockedSince":
    string
    Corresponds to the start time of jobs currently running. read-only | Format: date-time
  • "retryCount":
    integer
    Number of failures since the last successful run. | Example: 2
  • "maxNoOfRetries":
    integer
    Current value. How often a failed schedule will be retried. The schedule will stop execute after this limit is reached. To nevertheless force the schedule execution you can either raise this limit or set a next execution time per hand (choosing a timestamp in the past should trigger the schedule within the next minute). | Example: 25
  • "retryDelay":
    string
    Current value. Time interval between retries of failed schedules. | Example: 7m
  • "nextRun":
    string
    Next time when a failed schedule will be retried.
    This value can be set by hand (fixedNextRun) or is defined after an attempt failure as long as the maxNoOfRetries is not reached.
    Is ignored by inactive schedules. When not set, then the next attempt is determined from the cron expression (given the schedule is active and the maxNoOfRetries has not been reached). This attribute is internally resetted to null when the schedule has run successfully or after the maxNoOfRetries has been reached. | Format: date-time
  • "description":
    string
    Schedule description. read-only | Example: Check for Datapack files.
}

400 - Bad Request

- Generic or business logic validation error.
ErrorReport application/json{
  • "status":
    integer
    The HTTP status code. | Format: int32 | Example: 403
  • "errors":
    array
    An array of Error objects.
    [
    Error:
    {
    • "code":
      string
      Required | Exception / Error code | Example: VALIDATION_EXCEPTION
    • "message":
      string
      Required | Exception / Error message | Example: Attribute XYZ is mandatory
    • "value":
      object
      Value which caused the exception / error.
    }
    ]
}

401 - Unauthorized

- Authentication information is missing or invalid.
Response HeaderDescription
WWW-Authenticate

403 - Forbidden

- the user is not authorized to use this resource.

406 - Not Acceptable

- A representation of the response in the media type that was requested in the ACCEPT header cannot be provided.

415 - Unsupported Media Type

- The media type of the sent body is not supported.

500 - Internal Server Error

- An unexpected error occured.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets