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.

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:

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.

URL Parameters and Description

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

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.

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