Scheduling

Schedule Orchestration and Analytic Execution

Scheduling the execution of an orchestration or an individual analytic can be done on time-based intervals.

REST APIs are provided for managing a scheduled analytic or orchestration execution (also called a job). Using these APIs you can perform the following actions.

Create a job definition
Retrieve job definitions
Retrieve job history
Update job definitions
Delete existing jobs

When creating or updating a job, you can enable a job execution by setting the job state to Active. To disable a job, set the state to Inactive.

Task Roadmap: Scheduling a Job

A task roadmap provides the recommended order of steps to complete a process and serves as a planning guide. Use the following roadmap as a guide to schedule an analytic or orchestration execution.

You can schedule an orchestration or an individual analytic to be executed on time-based intervals using REST APIs. A scheduled analytic or orchestration execution is call a job


	Task	Information
1.	Understand how to find the URI values and to configure the REST headers for each API	See Binding an Application to an Analytics Framework Instance Verifying the Binding Configuring REST Request Headers
2.	Review what actions can be scheduled	See Schedule Orchestration and Analytic Execution
3.	Ensure you have a dedicated OAuth2 client to execute your scheduled jobs	See Using Predix console: Creating an OAuth2 Client afs-get-started.html#task_9144ad8f-1c20-40bf-8dbd-43ff69594f43 Using command line: Configuring an OAuth2 Client for Scheduler Using UAAC
4.	Test that the dedicated OAuth2 client is set up correctly	See Validating an OAuth2 Client for Scheduler
5.	Schedule the job	See Scheduling a Job

Scheduling a Job

The following steps demonstrate how to schedule a job that will invoke an HTTP REST endpoint every 30 seconds.

Before You Begin

You must have the HTTP endpoint for the job you are going to schedule.

About This Task

In this example, it is assumed that the HTTP method is POST and REST endpoint is <JOB_EXECUTION_ENDPOINT>.

Note:

If a job fails after execution check its job history in the scheduler service. In the case where 25 jobs have failed, the job will be automatically suspended by the system.

There are five main parts in the request for scheduling a job.


Part	Header/Element	Description
Authorization with the scheduler service	"`Authorization`" and "`Predix-Zone-Id`" headers	These are the standard headers to enforce authorization for Predix services. For more information, see Configuring REST Request Headers.
Authorization for job execution	"`Refresh-Token-For-Job-Execution`" header	(Optional) When a job is triggered, the scheduler makes a REST API call to the job execution endpoint configured in the job request body. If the job execution endpoint is secured by OAuth2, the scheduler requires an OAuth2 token to invoke the job execution endpoint successfully. Scheduler uses this refresh token to generate the OAuth2 access token. If this header is not set, scheduler will use "Client Credentials" grant type to generate an access token.
Metadata of a job	"`name`", "`description`", and "`state`" elements	"`name`" is a required element. "`state`" can be "`active`" or "`inactive`". "`state`" is set to "`active`" by default.
Scheduling configuration of a job	"`cron`" element	Required in the request body. Configures when the job will be triggered.
Execution configuration of a job	"`executionRequest`" element	Required in the request body. Configures how the job execution endpoint should be invoked when the job is triggered.

Procedure

Get the URL and action (POST, GET, etc.) for the job being scheduled.
For example:
```
POST <JOB_EXECUTION_ENDPOINT>
```

Schedule a job.

Issue the following REST API request.
```
POST <scheduler_uri>/api/v1/scheduler/jobs
```
The job request must contain the job schedule in a CRON expression-like structure. The job request must also contain the detailed information about the HTTP request that will be invoked by the scheduled job trigger. For more information, see Job Scheduling Configuration Reference and Job Execution Configuration Reference.
If the job execution endpoint is secured by OAuth2 and the grant type is refresh_token, provide the OAuth2 refresh token associated with the dedicated OAuth2 client.

To do this, add the following header (in addition to the standard “Authorization” and “Predix-Zone-Id” headers): "Refresh-Token-For-Job-Execution” header, with the value set to the refresh token value.

For more information about setting up an authorized OAuth2 client, see Configuring an OAuth2 Client for Scheduler Using UAAC.

The following is a sample request to schedule a job.

{
  "name": "Sample Job Name",
  "description": "Sample Job Description",
  "state": "Active",
  "cron": {
    "seconds": "0/30",
    "minutes": "*",
    "hours": "*",
    "dayOfMonth": "*",
    "months": "*",
    "dayOfWeek": "?",
    "years": "*",
    "timeZoneId": "UTC"
  },
  "executionRequest": {
    "url": "<JOB_EXECUTION_ENDPOINT>",
    "httpMethod": "POST",
    "httpHeaders": [
      {
        "name": "Content-Type",
        "value": "application/json"
      }
    ],
    "inputData": "<JOB_EXECUTION_DATA>"
  }
}

The following is a sample response from scheduling a job. The response contains the job id that can be used for managing this job. The service also provides an API to retrieve all job definitions (GET /api/v1/jobs). This can be used to find a job id.

{
    "name": "Sample Job Name",
    "id": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
    "cron": {
        "hours": "*",
        "minutes": "*",
        "seconds": "0/30",
        "years": "*",
        "timeZoneId": "UTC",
        "months": "*",
        "dayOfWeek": "?",
        "dayOfMonth": "*"
    },
     
    "createdBy": "analytics-admin",
    "createdTimestamp": "2015-11-03 13:00:47.728",
    "description": "Sample Job Description",
    "executionRequest": {
        "url": "<JOB_EXECUTION_ENDPOINT>",
        "httpMethod": "POST",
        "httpHeaders": [
            {
                "name": "Content-Type",
                "value": "application/json"
            }
        ],
        "inputData": "<JOB_EXECUTION_DATA>"
    },
    "updatedBy": "analytics-admin",
    "updatedTimestamp": "2015-11-03 13:00:47.728"
}

Retrieve the job execution history by issuing the following REST API request. This request will get the status and the result of past job executions.

GET <scheduler_uri>/api/v1/scheduler/jobs/{jobId}/history

The following is a sample response of job history retrieval.

[
  {
    "id": "de6f80af-fa8b-4b03-8f8f-12bcc4c0440e",
    "jobId": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
    "fireTime": "2015-10-06 17:13:00.0",
    "scheduledFireTime": "2015-10-06 17:12:34.0",
    "cron": "0/30 ?",
    "timeZoneId": "UTC",
    "httpMethod": "POST",
    "url": "<JOBEXECUTIONENDPOINT>",
    "httpStatusCode": 200,
    "result": null,
    "statusMessage": "completed"
  },
  {
    "id": "fe04fd6a-e7ad-4f1f-85ec-012a1af40963",
    "jobId": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
    "fireTime": "2015-10-06 17:13:30.0",
    "scheduledFireTime": "2015-10-06 17:12:34.0",
    "cron": "0/30 ?",
    "timeZoneId": "UTC",
    "httpMethod": "POST",
    "url": "<JOBEXECUTIONENDPOINT>",
    "httpStatusCode": 200,
    "result": null,
    "statusMessage": "completed"
  },
  {
    "id": "3adbb8e1-0ddd-4c5d-af39-8e84cb4c9e38",
    "jobId": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
    "fireTime": "2015-10-06 17:14:00.0",
    "scheduledFireTime": "2015-10-06 17:12:34.0",
    "cron": "0/30 ?",
    "timeZoneId": "UTC",
    "httpMethod": "POST",
    "url": "<JOBEXECUTIONENDPOINT>",
    "httpStatusCode": 200,
    "result": null,
    "statusMessage": "completed"
  }
]

The result field contains the execution response.

If running a scheduled analytic, use the requestId in the response. See About Running a Single Analytic for more information.
If running a scheduled orchestration, see Retrieving an Orchestration Execution Status for more information.

Managing Suspended Jobs

If a job fails after execution you should check its job history in the scheduler service. The job is automatically suspended by the system if there are 25 consecutive job failures, or if the refresh token has expired. In either case, verify the job's status and re-activate it by following the steps in this task.

Procedure

Retrieve the job execution history to get the status of past job executions as follows.

GET <scheduler_uri>/api/v1/scheduler/jobs/{jobId}/history

The following is a sample response of job history retrieval.

[
    {
        "id": "de6f80af-fa8b-4b03-8f8f-12bcc4c0440e",
        "jobId": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
        "fireTime": "2015-10-06 17:14:00.0",
        "scheduledFireTime": "2015-10-06 17:14:00.0",
        "cron": "0/30 * * * * ?",
        "timeZoneId": "UTC",
        "httpMethod": "POST",
        "url": "<JOB_EXECUTION_ENDPOINT>",
        "statusMessage": "suspended"
    },
    {
        "id": "de6f80af-fa8b-4b03-8f8f-12bcc4c0440e",
        "jobId": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
        "fireTime": "2015-10-06 17:14:00.0",
        "scheduledFireTime": "2015-10-06 17:14:00.0",
        "cron": "0/30 * * * * ?",
        "timeZoneId": "UTC",
        "httpMethod": "POST",
        "url": "<JOB_EXECUTION_ENDPOINT>",
        "statusMessage": "failed <failure reason>"
    },
    {
        "id": "fe04fd6a-e7ad-4f1f-85ec-012a1af40963",
        "jobId": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
        "fireTime": "2015-10-06 17:13:30.0",
        "scheduledFireTime": "2015-10-06 17:13:30.0",
        "cron": "0/30 * * * * ?",
        "timeZoneId": "UTC",
        "httpMethod": "POST",
        "url": "<JOB_EXECUTION_ENDPOINT>",
        "statusMessage": "failed <failure reason>"
    },
    {
        "id": "3adbb8e1-0ddd-4c5d-af39-8e84cb4c9e38",
        "jobId": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
        "fireTime": "2015-10-06 17:13:00.0",
        "scheduledFireTime": "2015-10-06 17:13:00.0",
        "cron": "0/30 * * * * ?",
        "timeZoneId": "UTC",
        "httpMethod": "POST",
        "url": "<JOB_EXECUTION_ENDPOINT>",
        "statusMessage": "failed <failure reason>"
    }
]

If your job has been suspended by the scheduler service, determine the cause.
- If the suspension is due to the refresh token expiry, proceed to the next step and provide a new refresh token.
- If the suspension is due to the job failures, correct the failures and proceed to the next step.

Modify the job contents and re-activate the job by setting the "state" to "Active".

Issue the following REST API call.

PUT <scheduler_uri>/api/v1/scheduler/jobs/<job_id>

If the job execution endpoint is secured by OAuth2, provide the OAuth2 refresh token associated with the dedicated OAuth2 client.

To do this, add the following header (in addition to the standard “Authorization” and “Predix-Zone-Id” headers): "Refresh-Token-For-Job-Execution” header, with the value set to the refresh token value.

For more information about setting up an authorized OAuth2 client, see afs-get-started.html#task_ny3_mr5_vv.

The following is a sample request to update a job.

{
  "name": "Sample Job Name",
  "id": "b3142c28-18f9-4cc5-87e2-883bf7d3f7dc",
  "description": "Sample Job Description",
  "state": "Active",
  "cron": {
    "seconds": "0/30",
    "minutes": "*",
    "hours": "*",
    "dayOfMonth": "*",
    "months": "*",
    "dayOfWeek": "?",
    "years": "*",
    "timeZoneId": "UTC"
  },
  "executionRequest": {
    "url": "<JOB_EXECUTION_ENDPOINT>",
    "httpMethod": "POST",
    "httpHeaders": [
      {
        "name": "Content-Type",
        "value": "application/json"
      }
    ],
    "inputData": "<JOB_EXECUTION_DATA>"
  }
}

After the job has been re-activated, continue checking the job history to make sure that the failures have been corrected.

Job Execution Configuration Reference


Field	Mandatory	Allowed Values	Description
`url`	Yes		REST API endpoint to invoke when the job execution is triggered by the job scheduler.
`httpMethod`	Yes	`GET`, `POST`, `HEAD`, `OPTIONS`, `PUT`, `PATCH`, `DELETE`, `TRACE`	HTTP method
`httpHeaders`	No		HTTP headers needed by the REST API endpoint
`inputData`			Input data for the REST API request

Job Scheduling Configuration Reference


Field	Mandatory	Allowed Values	Allowed Special Characters	Notes
`seconds`	Yes	0-59	, - * /
`minutes`	Yes	0-59	, - * /
`hours`	Yes	0-23	, - * /
`dayOfMonth`	Yes	1-31	, - * ? / L W	Special character '?' can not be used in both `dayOfMonth` and `dayOfWeek` fields at same time. Example: To schedule a job for 15th day of the month, set `dayOfMonth` to 15 and `dayOfWeek` to '?'.
`months`	Yes	1-12 or JAN-DEC	, - * /	The allowed abbreviated month names are JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV and DEC.
`dayOfWeek`	Yes	1-7 or SUN-SAT	, - * ? / L #	The allowed abbreviated names for the days are SUN, MON, TUE, WED, THU, FRI and SAT. Example: To schedule a job for 15th day of the month, set `dayOfMonth` to 15 and `dayOfWeek` to '?'.
`years`	No (Default: empty)	empty, 1970-2099	, - * /
`timeZoneId`	No (Default: UTC)	Java Time Zone ID

Table 1. Special Characters Summary
Character	Description
','	Used to specify a list of values. For example, setting `months` field to "JAN,MAY,SEP' means the month of January, May and September.
'-'	Used to specify a list of values. For example, setting `months` field to 'JUN-AUG' means the month of June, July and August.
'*'	Used to specify "all values". For example, '*' in `seconds` field it means every second.
'?'	Used to specify "no special value".
'L'	`dayOfMonth` - Used to specify the last day of the month. For example, 31st in January, 28th in February for non-leap year. and so on. `dayOfWeek` - Used by itself, 'L' specifies '7' or 'SAT'. 'L' can be combined with another value, for example '3L', to designate "the last Tuesday of the month". (3 specifies 'TUES').
'W'	Special character for `dayOfMonth`. Used to specify the weekday nearest to the given day. For example, '20W; specifies "nearest weekday to the 20th day of the month". A weekday is Monday to Friday.
'#'	Special character in `dayOfWeek`. Used with a number before and a number after. For example, 'm#n' where 'm' specifies the day of the week and 'n' specifies the n^th occurrence in the month. '3#2' specifies "the second Tuesday of the month" ('3' = "Tuesday" and '#2' = 'second one in the month").

For more information about these special characters, please see the CronTrigger Tutorial in Quartz documentation at http://www.quartz-scheduler.org/documentation/quartz-2.x/tutorials/crontrigger.

For more information about available values for Java time zoneid, please see Java documentation at http://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html.