Send a notification and mail from a z/OSMF task or z/OSMF user

HTTP method and URI path

POST /zosmf/notifications/new

Query Parameters

None

Description

The content of the notification as well as the mail contains the user input data. This operation does not support application linking. A notification with the same subject and content will be sent to all recipients. If the “attachment” parameter is specified, the attachment will only appear in the recipients' mail.

Request Content

The value of the post body should be JSON Object-like. See Table 1.

Table 1. Request content from a notification that requires user input
Input	Description	Type	Required or Optional
assignees	User IDs or groups.	String	Required
subject	Subject of the notification. The allowable length is 1-500.	String	Required
content	Notification body. The allowable length is 0-5000.	String	Optional
attachment	Array of the file paths, up to 5 attachments are allowed.	String	Optional
pluginId	ID of the plug-in where the notification is initiated.	String	Required, only if the notification is from a z/OSMF task.
taskId	ID of the task where the notification is initiated.	String	Required, only if the notification is from a z/OSMF task.
product	Product of Mapping.	String	Required, only if the notification is from a third party product.
eventGroup	Event group of Mapping.	String	Required, only if the notification is from a third party product.
data	Payload content of a notification.	JSON String	Required, only if the notification is from a third party product.
alert	Displayed on APP in the systems that support the alert function.	String	Optional

Response Content

On completion, the request returns a JSON object with details about the notification. The response content is shown in Table 2.

Table 2. Response content from a notification that requires user input
Field	Type	Description
apiVersion	String	The version of the Notification Services API.
result	JSONObject	Contains all of the output for each notification destination. It includes 1-3 keys depending on how many destinations the notification is sent to. Each key represents one destination, and its value is a JSONObject which might have messages and return codes.

Authorization Requirements

Use of the Notification RESTful services API requires the client to be authenticated. For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

You will also need SAF authority, as described in Appendix A in IBM z/OS Management Facility Configuration Guide

HTTP status codes

On successful completion, HTTP status code 200 OK is returned and the response body is provided. See Table 2.

The HTTP status codes and error handling are described in Error handling.

Escaping special characters

The format of a notification should be a valid JSONObject. If a special character exists it must be escaped. If " exists, it needs to be escaped as \". If \ exists, it needs to be escaped as \\.

Example HTTP interaction

Request

POST zosmf/notifications/new

{"subject":"Test with unix attachment",
"content":"See if there is an attachment.",
"assignees":"zosmfad",
"attachment":"[\"/var/zosmf/data/logs/IZUG0.log\"]"}

Response

{"apiVersion":"1.0",
"result":{"mail":{"messages":{"errorData":[{"messageText":"IZUG615E: The
connection to the SMTP host \"smtp.gmail.com\" port \"587\" failed with
error type \"ConnectionTimedout\" .",
"messageId":"IZUG615E"}]},
"rc":"ConnectionTimedout"},
"notification":{"messages":null}}}