API v1 - Schedules

Overview

This is a guide to providing details on the Schedule API from the family of the Group API. The Schedule endpoint allows users to explore the "resource" details to run the job within the Project Group in the Matillion ETL instance. By "resources" here, we refer to retrieving schedule metadata such as; name, DayOfweek, time to run the job, version name, environment name, and job name, other resources are getID, update, export/import and delete job schedules within Projects and Groups in which they reside.

Important Information

This document is part of a series on API v1 - Group and the Matillion ETL API - v1.
Users responsible for experimenting with Matillion ETL API services require access to the Matillion ETL instance and ought to know how to make REST API calls either employing a REST API GUI client such as Postman or employing a command-line interface like cURL.
Matillion ETL API endpoints require authorisation to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.

Schedule API Endpoints

API Base URL

http(s)://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/schedule

API Endpoints and Function

Schedule endpoint API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET, POST, and DELETE data. The Schedule endpoint API service is accessed through the Uniform Resource Identifier (URI). All following references in this document will assume the API Base URL. The available API endpoints are listed below:

Method	Path	URI	Function
GET	/name	http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/name	Get the name of the selected schedule within the group.
GET	/id	http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/id	Get the Queue Id of the schedule.
GET	/export	http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/export	Produces an export container containing this schedule.
POST	/import	http://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/schedule/import	Import the resource data to the instance.
POST	/delete	http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/delete	Delete the selected schedule via a HTTP POST request.
POST	/update	http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/update?ignoreUnresolved=false WITH POST DATA arg1	Update the selected schedule within the project.
DELETE	/scheduleName	http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>	Delete the selected schedule via a HTTP DELETE request.

Graphical Representation

To illustrate the Schedule API v1, endpoints and methods to the further, below is the graphical flow of the /schedule endpoint showing possible PATH, GET, POST, and DELETE options.

Schedule endpoint Flow

URL Parameters and Description

Below is the list of endpoint parameters and their brief description:

Parameters Name	Description
<InstanceAddress>	This is the server IP address or domain name.
<groupName>	The name of the group.
<projectName>	The name of the project within the group.
<name>	To get the name of the resource.
<update>	This allows to update the selected resource.
<delete>	Delete the selected resource.
<id>	The queue id of the resource.

Endpoints and Server Response

This chapter describes the Schedule API endpoints with some server response examples. These APIs offers REST-based web service, offering ease of use and a flexible choice of programming language.

All the APIs listed in this chapter are available to use with GET/POST/DELETE methods to retrieve the data used to get, update, or delete the schedule.

List of endpoints for the /schedule:

GET/name
GET/id
GET/export
POST/import
POST/delete
POST/update
DELETE/scheduleName

Below is the detailed description of these endpoints with example response from the server.

GET/name

This example is a GET method REST API request that will provide the name of the schedule created for the job to run within the project in the instance.

Base URL

http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/name

Server Response
```
Example-Schedule
```

GET/id

This is to get the queue id for the selected schedule within the project.

Base URL

http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/id

Server Response
```
123
```

GET/export

To export the selected schedule from the project within the Matillion instance, provide the scheduleName and use the /export endpoint. This example using GET method REST API call to export the selected schedule and all associated information aligned with the group.

Base URL

http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/export

Server Response

{
    "objects": [
        {
            "name": "Example-Schedule",
            "minute": "30",
            "hour": "12",
            "dayOfWeek": true,
            "monday": true,
            "tuesday": false,
            "wednesday": false,
            "thursday": false,
            "friday": false,
            "saturday": false,
            "sunday": false,
            "daysOfMonth": "",
            "enabled": true,
            "timezone": "Europe/London",
            "versionName": "default",
            "jobName": "dim_airport_setup",
            "environmentName": "test",
            "preventDuplicateJob": false
        }
    ],
    "version": "master",
    "environment": "redshift"
}

POST/import

This will import the resource data which is exported as shown in the above example using /import endpoint. If a resource of the same name already exists, you must delete the existing resource before importing the new or you can change the name of the imported resource (Schedule-Imported)in the POST BODY. This API call is a POST method API call as we will have to attach the resource data, in the body as a JSON file to import into the Matillion ETL instance.

Base URL

http://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/schedule/import

POST Body (JSON)

{
    "objects": [
        {
            "name": "Schedule-Imported",
            "minute": "30",
            "hour": "16",
            "dayOfWeek": true,
            "monday": true,
            "tuesday": false,
            "wednesday": false,
            "thursday": false,
            "friday": false,
            "saturday": false,
            "sunday": false,
            "daysOfMonth": "",
            "enabled": true,
            "timezone": "UTC",
            "versionName": "default",
            "jobName": "dim_airport_setup",
            "environmentName": "T3st",
            "preventDuplicateJob": true
        }
    ],
    "version": "master",
    "environment": "redshift"
}

Below is the description of the fields included in the POST body:

Field name	Data type	Description
name	String	The name of the schedule.
minute	String	The minute past the hour that the job should run. Minutes are 0-59 inclusive. To run the job multiple times in an hour, separate minutes with a comma. For example: "0,15,30,45". Use the wildcard character, *, to signify every minute in an hour.
hour	String	The hour of the day that the job should run. Hours are 0 to 23 inclusive. Combined with "minute", this gives the time of day for the job to execute. For example, { "minute": "30", "hour": "16" } would execute the job at 4:30pm on the specified day(s). To run the scheduled job multiple times a day, separate the hours it will run at with a comma, for example: "0,3,7,12,16,19". Use the wildcard character, *, to signify every hour.
dayOfWeek	Boolean	Jobs can be scheduled to run on a specific day of the week. If true, you must also specify one or more days with a value of true. If false, you must specify a value for daysOfMonth.
monday	Boolean	If true and dayOfWeek is also true, the job will execute every week on Monday. There are also fields for Tuesday, Wednesday, etc., and these can be set true in any combination to cause the job to run on multiple days of the week.
daysOfMonth	String	A comma-separated list of days within the month which the the scheduled job will run on. Use the wildcard character, *, to signify every day of the month. Use L to denote the last day of the month. You can use an expression such as 15W to designate the closest weekday to the 15th.
enabled	Boolean	Set false to disable the schedule, otherwise set true.
timezone	String	The time zone used to schedule the job. The job itself is run by Matillion ETL, which is always based on UTC and is offset to local time using the timezone you select.
versionName	String	The version of the project you wish to run.
jobName	String	The orchestration job you wish to run.
environmentName	String	The environment you wish to run the job against.
preventDuplicateJob	Boolean	Set true to specify that a scheduled job run should not queued if that same job from a previous schedule is still running, preventing duplicates from stacking up in the queue.
ignoreMisfires	Boolean	Set true to cause scheduled jobs that missed their trigger time to run as soon as possible, thus ignoring misfires.
version	String	The project version that the resource data will be imported into.
environment	String	The Matillion ETL environment that the resource data will be imported into.

Server Response

{
  "name": "Schedules",
  "statusList": [
    {
      "success": true,
      "name": "Schedule-Imported"
    }
  ],
  "success": true
}

URL Parameters
There is an optional parameter, onConflict, which determines what should happen if an import clashes with something that already exists. For an explanation of this parameter's use, read API Import conflicts - Explanation in Matillion ETL API - v1.

POST/delete

This will be a POST method API call. The /delete endpoint will allow to delete the selected schedule from the project.

Base URL

http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/delete

Server Response

{
  "success": true,
  "msg": "Successfully deleted the schedule: Example-Schedule",
  "id": -1
}

POST/update

The /update endpoint will allow to update the selected schedule. This will be a POST method API call as we will have to attach the project, in the body as a JSON file to import into the Matillion ETL instance.

Please Note

Make sure, if the resource of the same name already exists, you must delete the existing resource before importing the new or should change the name of the project to be imported in the POST Body.

Base URL

http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/update?ignoreUnresolved=false WITH POST DATA arg1

POST BODY(JSON)

{
            "name": "Schedule-Imported01",
            "minute": "30",
            "hour": "16",
            "dayOfWeek": true,
            "monday": true,
            "enabled": true,
            "timezone": "UTC",
            "versionName": "default",
            "jobName": "dim_airport_setup",
            "environmentName": "test",
            "preventDuplicateJob": true
}

Below is the description of the fields included in the POST body:

Field name	Data type	Description
name	String	The name of the schedule.
minute	String	The minute past the hour that the job should run. Minutes are 0-59 inclusive. To run the job multiple times in an hour, separate minutes with a comma. For example: "0,15,30,45". Use the wildcard character, *, to signify every minute in an hour.
hour	String	The hour of the day that the job should run. Hours are 0 to 23 inclusive. Combined with "minute", this gives the time of day for the job to execute. For example, { "minute": "30", "hour": "16" } would execute the job at 4:30pm on the specified day(s). To run the scheduled job multiple times a day, separate the hours it will run at with a comma, for example: "0,3,7,12,16,19". Use the wildcard character, *, to signify every hour.
dayOfWeek	Boolean	Jobs can be scheduled to run on a specific days of the week. If true, you must also specify one or more days with a value of true. If false, you must specify a value for daysOfMonth.
monday	Boolean	If true and dayOfWeek is also true, the job will execute every week on Monday. There are also fields for Tuesday, Wednesday, etc., and these can be set true in any combination to cause the job to run on multiple days of the week.
daysOfMonth	String	A comma-separated list of days within the month which the the scheduled job will run on. Use the wildcard character, *, to signify every day of the month. Use L to denote the last day of the month. You can use an expression such as 15W to designate the closest weekday to the 15th.
enabled	Boolean	Set false to disable the schedule, otherwise set true.
timezone	String	The time zone used to schedule the job. The job itself is run by Matillion ETL, which is always based on UTC and is offset to local time using the timezone you select.
versionName	String	The version of the project you wish to run.
jobName	String	The orchestration job you wish to run.
environmentName	String	The environment you wish to run the job against.
preventDuplicateJob	Boolean	Set true to specify that a scheduled job run should not queued if that same job from a previous schedule is still running, preventing duplicates from stacking up in the queue.
ignoreMisfires	Boolean	Set true to cause scheduled jobs that missed their trigger time to run as soon as possible, thus ignoring misfires.

Server Response

{
  "success": true,
  "msg": "Successfully updated schedule [Schedule-Imported01]",
  "id": 0
}

DELETE/scheduleName

To remove any resource from the list, we will use DELETE API request. In this example, we will delete a schedule created to run a job in the Matillion ETL instance.

Base URL

http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>

Server Response

{
  "success": true,
  "msg": "Successfully deleted schedule [Example-Schedule]",
  "id": -1
}

Please Note

There are often multiple ways of achieving the same task within the API as resources and methods branch out and overlap.