Register an event type

You can use this operation to define a new event type to z/OSMF.

HTTP method and URI path

POST /zosmf/izual/rest/eventtype

where:

/zosmf/izual/rest identifies the Application Linking Manager interface.
eventtype identifies the event type component of the application linking process.

Standard headers

Use the following standard HTTP header with this request:

Content-Type: application/json

Custom headers

None.

Request content

Your request must include a JSON object that describes the event type to be registered, for example:

Figure 1. Registering an event type: request content

{
id: “IBM.ZOSMF.EVENT_TYPE_ID”,
displayName: “Default English name”,
desc: “Default English description”,
owner: “ownerId”,
params: {
  “key1”: “English description of the parameter.”,
  “key2”: “English description of the parameter.”}
}

The following values are supported:

id

Specify a unique identifier for the event type. It can contain up to 50 characters, including alphanumeric characters (A-Z, a-z, and 0-9), periods (.), and underscores (_). The event ID is required and must be unique.

It is recommended that IDs have the format company-name.product-name.event-name where:

company-name is the name of your company. Use a period as the delimiter within the company name. For example, for Tivoli products, the company name can be IBM.TIVOLI.
product-name is the name of the product for which the event type is being created.
event-name is the action that will be completed by the event handler. The event name should start with a verb that reflects this action. Use an underscore as the delimiter within the event name.
For example, to create an event type that allows a user to view the status of a job listed in z/OSMF, the event name portion of the ID can be VIEW_JOB_STATUS. The entire ID can be IBM.ZOSMF.VIEW_JOB_STATUS.

displayName

Specify the name of the event type. The name is required and can contain up to 50 characters.

Example: View job status.

desc

Specify a description of the event type. The description is optional and can contain up to 200 characters.

Example: Use this event type to view the status of a job. This event type is invoked when a user selects the View Job Status action.

owner

Specify the ID of the first z/OSMF task or external application that registered the event type. Typically, event types are registered by or on behalf of event handlers. They can also be registered by or on behalf of event requestors. This field is required, and can contain up to 50 characters, including alphanumeric characters (A-Z, a-z, and 0-9), periods (.), and underscores (_).

params

Specify the name and description of each parameter that event requestors can supply with an event. Enter each parameter name and description combination on a separate line, and enclose the entry in quotes. Use a colon to separate the parameter name and description, and a comma to end each entry. The final entry is not ended with a delimiter.

This area can contain up to 4,000 characters, including alphanumeric characters (A-Z, a-z, and 0-9), periods (.), underscores (_), and commas (,).

For example, to allow event requestors to provide a job ID, job name, and user ID for an event type that displays the status of a job, you would specify the following parameters:

params: {
"jobID": "ID assigned to the job.",
"jobName": "Name specified for the job.",
"userID": "ID of the user who submitted the job."
}

Usage considerations

See Usage considerations for the z/OSMF REST services.

Required authorizations

See Required authorizations.

IBM-supplied event types

z/OSMF includes a number of predefined event types, requestors, and handlers. For a list, see IBM z/OS Management Facility Configuration Guide.

Example of registering an event type

A sample request to register an event type is shown in Figure 2.

Figure 2. Example: Registering an event type

POST /zosmf/izual/rest/eventtype HTTP/1.1
Host: zosmf1.yourco.com

Accept: application/json
Content-Type: application/json

{
	"id":"IBM.ZOSMF.VIEW_JOB_STATUS",
	"displayName":"View Job Status",
	"owner":"SDSF", 
	"params":{"jobName": "Name of the job for which to view status."}
}

Expected response

On completion, the Application Linking Manager interface returns an HTTP response, which includes a status code indicating whether your request completed. Status code 200 indicates success. A status code of 4nn or 5nn indicates that an error has occurred. See Error handling.

The response also includes a JSON object with additional information about the results of the request. If your request is successful, the JSON object contains null data for the error and result fields, as shown in Figure 3.

Figure 3. Example: Returned results of a successful event registration

{"error":null,"result":null}

For an unsuccessful request, the JSON object contains an error message in the error fields, msgid and msgtext. The example in Figure 4 shows the results for an attempt to register an already-registered event with different parameters:

Figure 4. Example: Returned results of an unsuccessful event registration

{
"error":{
		"msgid":"IZUG690E",
		"msgtxt":"Event type \"IBM.ZOSMF.VIEW_JOB_STATUS\" is already defined, but 
				different parameters are specified."},
"result":null
}