With APAR PH44152, z/OS Jobs REST services were enhanced to support more asynchronous notification events.
Before the enhancement, when you submit a JCL through the following z/OSMF REST API, you can specify a destination URL for receiving an HTTP POST when the job is complete.
PUT /zosmf/restjobs/jobs[/-<JESB>]
With the enhancement, your destination URL can receive an HTTP POST when the job is ready for execution or started execution. A new custom header "X-IBM-Notification-Options" is added to support this feature.
X-IBM-Notification-Options
Specifies the events of a submitted job. This header consists of a JSON string with a single property called events. The value of the events property is a list of strings that indicates the job events which trigger HTTP POSTs. If any of the job events happen, the destination URL specified in X-IBM-Notification-URL receives an HTTP POST. Valid event types are ready, active, and complete and are case-insensitive. The maximum number of characters is 4096. If no values or invalid event types are provided, an exception occurs.
• Ready - Job is ready for execution.
• Active - Job started execution.
• Complete - Job completed execution.
This header is only valid if you are using JES2 EDS for job notifications over HTTP. It will not take effect if you are using the Common Information Model (CIM) jobs indication provider. If this header is specified, the header X-IBM-Notification-URL must also be specified, otherwise it is ignored.
Example:
X-IBM-Notification-Options: {"events": ["active", "ready", "complete"]}
The notification is in the form of a JSON document(Content-Type: application/json), which contains job status information.
The description of the JSON job notification document is as below.
| Property |
Description |
| job-correlator |
Job correlator. If this value is null, the job was submitted to JES3. |
| jobid |
Job ID. |
| jobname |
Job name. |
| owner |
The z/OS user ID associated with the job. |
| class |
Job execution class. |
| event |
ready, active, or complete, based on the event that drove the HTTP POST to occur. |
| member |
1. For the ready event, indicates where the job converted and was placed onto the execution queue.
2. For the active event, indicates where the job was selected to run.
3. For the complete event, indicates where the job reached a "completed" state. Generally, it is the same as the member where the job ran, except in some error cases where that might not be true. |
| event-time |
Timestamp indicating the date and time when the job notification event occurred. Timestamps are presented in the JSON UTC format: "yyyy-mmddThh:mm:ss.mmmmmmZ". |
retcode={
ABENDUnnnn |
ABEND Sxxx |
CANCELED |
CC nnnn |
CONV ABEND |
CONV ERROR |
JCL ERROR |
SEC ERROR |
SYS FAIL
} |
Job completion code. One of the following values: For ready and active event types, property value returns as null. For event type complete, this property stands for Job completion code. One of the following values:
ABENDUnnnn
Job ended with the user abend code nnnn.
ABEND Sxxx
Job ended with the system abend code xxx.
CANCELED
Job was canceled.
CC nnnn
Job ended with the completion code nnnn.
CONV ABEND
Converter ended abnormally when processing the job.
CONV ERROR
Converter error when processing the job.
JCL ERROR
Job encountered a JCL error.
SEC ERROR
Job failed a security check.
SYS FAIL
System failure. |
| completion-type |
Specific completion type:
0
No completion information was received.
1
Job ended normally.
2
Job ended with a completion code.
3
Job encountered a JCL error.
4
Job was canceled.
5
Job abended.
6
Converter error when processing the job.
7
Job encountered a security error.
8
Job failed in EOM.
9
Job failed a security check.
10
System failure. |
| completion-code |
Completion code. Set for completion-type values 1 and 2. Otherwise, null. |
| abend-code |
Job completed with abend code. Set for completion-type values 5 and 8. Otherwise, null. When set, one of the following values:
Unnnn
Job ended with the user abend code nnnn.
Sxxx
Job ended with the system abend code xxx. |
APAR OA61231 introduces support for JES2 EDS for job notifications over HTTP. The notification URL supplied to the z/OS jobs REST interface services is passed to JES2 via SYS_JOB_NOTIFY JES symbol when submitting a job through the internal reader (see description of SYS_JOB_NOTIFY in JES Symbol Service (IAZSYMBL) in z/OS JES Application Programming).
There is a new RACF check added for job notifications. Using RACF, you can control which users can request such job notifications by defining a profile in JESJOBS class. For additional information, see Controlling job notifications in z/OS JES2 Initialization and Tuning Guide and description of SYS_JOB_NOTIFY in JES Symbol Service (IAZSYMBL) in z/OS JES Application Programming.
To use the asynchronous job notifications function of z/OSMF through JES2 EDS for job notifications over HTTP, you must enable the following z/OS elements:
- JES2 Email Delivery Services (EDS); see Using JES2 EDS for job notification over HTTP in z/OS JES2 Initialization and Tuning Guide.
- Enable JES2 support for job notifications over HTTP; see description of SYS_JOB_NOTIFY in JES Symbol Service (IAZSYMBL) in z/OS JES Application Programming.
For more information about this support, see APAR PH44152.