Alerts

This chapter describes the alerts resource, properties and operations.

Overview

An appliance issues alerts to inform the user or administrator about events requiring a response.

The following types of alerts are available:

A notification alert is a message notifying a user of some occurrence in the system that requires the user's awareness or response. That is, a notification can be informational in nature, or it can be an error that requires a response from you. These alerts are viewable by any user role.

An error alert is a message notifying the administrator of system-detected software error. The administrator is expected to submit the alert diagnostic information to the appliance support team. These alerts are viewable only by users with the administrator role.

Resource Properties

An alerts instance is represented by the following fields.

Type values are described in Data types.

Name Type Rqd/Opt Description
correlid String Opt The correlation id to group multiple alerts
diag-info String/URI Rqd The URI of this alert's diagnostic information
msgid String Rqd The alert message identifier, which identifies the cause of the error but does not uniquely identify a specific alert instance
msgtext String Rqd The alert message text, in the language requested by the user, see Native Language Support
self String/URI Rqd The URI of this instance
size Long Rqd The size of the alerts diagnostic information
timestamp Timestamp Rqd The alert's date/time of issuance
type String Enum Rqd The alert type, refer to type Enum values f for supported values

type Enum values

Resource Operations

Retrieve a list of alerts

Use this operation to retrieve a list of alerts.

Status FW release SW release Notes
implemented None MVP none

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations .

When the provided API token represents a user with user authority:

When the provided API token represents a user with administrator authority:

Network

This operation is available from the following network(s):

HTTP Method and URI

GET /api/com.ibm.zaci.system/alerts
Query Parameters
Name Type Rqd/Opt Multiple occurences Description
after Timestamp Opt No Only return alert instances whose timestamp property is greater than or equal to the specified value
before Timestamp Opt No Only return alert instances whose timestamp property is less than or equal to the specified value
msgid String Opt Yes Only return alert instances whose msgid property matches the specified value
type String Enum Opt Yes Only return alert instances whose type property matches the specified value

Refer to the Filtering topic for detailed usage information.

Notes

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types

Request message body

None

Response

An HTTP status code of 200 indicates a successful operation. The response message body contains data formatted as requested in the Accept header, with kind=collection. The instances array contains zero or more objects, as described under the Resource Properties topic.

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

The result may contain error entries indicating partial errors while processing the log having the msgid=AZIZ0006E.

Example: Retrieve all alerts

Request

GET /api/com.ibm.zaci.system/alerts HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 15 May 2015 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 439

{
"kind": "collection",
"self": "/api/com.ibm.zaci.system/alerts",
"namespace": "com.ibm.zaci.system",
"namespace-version": "1.0",
"resource": "alerts",
"instances": [
    {
    "type": "error",
    "msgid": "AZIZ0010E",
    "msgtext": "Internal software error 025a000a 00000001.",
    "timestamp": 1430158827,
    "size": 3158827,
    "self": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000001",
    "diag-info": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000001/diag-info"
    },
    {
    "type": "error",
    "msgid": "AZIZ0001E",
    "msgtext": "My concurrent dump",
    "timestamp": 1430158827,
    "size": 3158827,
    "self": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000",
    "diag-info": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000/diag-info"
    },
    {
    "type": "notification",
    "msgid": "AZIZ0006E",
    "msgtext": "An unexpected error occurred reading the log entry.",
    "timestamp": 1430158827,
    "size": 3158827,
    "self": "/api/com.ibm.zaci.system/alerts/<none>"
    "diag-info": "/api/com.ibm.zaci.system/alerts/<none>/diag-info"
    }
    ]
}

Example: Retrieve only user-initiated dumps

Request

GET /api/com.ibm.zaci.system/alerts?msgid=AZIZ0001E&msgid=AZIZ0002E HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 15 May 2015 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 439

{
"kind": "collection",
"self": "/api/com.ibm.zaci.system/alerts",
"namespace": "com.ibm.zaci.system",
"namespace-version": "1.0",
"resource": "alerts",
"instances": [
    {
    "type": "error",
    "msgid": "AZIZ0001E",
    "msgtext": "My concurrent dump",
    "timestamp": 1430158827,
    "size": 3158827,
    "self": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000",
    "diag-info": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000/diag-info"
    }
    ]
}

Retrieve an alert

Use this operation to retrieve information about a specific alert.

Status FW release SW release Notes
implemented None MVP None

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations.

The user represented by the API token must have the authority to view the requested alert.

Network

This operation is available from the following network(s):

HTTP Method and URI

GET /api/com.ibm.zaci.system/alerts/[{instance-id}|{correl-id}]

In this request, the URI variable {instance-id} is the alert instance identifier (uuid) or the correlation identifier (correlid). The URI is obtained via the Retrieve a list of alerts operation or via the Create an error alert operation.

Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types

Request message body

None

Response

An HTTP status code of 200 indicates a successful operation. The response message body contains data formatted as requested in the Accept header, with kind=instance. The properties object is described under the Resource Properties topic.

An HTTP status code of 202 indicates that the alert is still in the process of being created. The response message body contains data formatted as requested in the Accept header, with kind=response. The format of the parameters object is described in the following table.

Name Type Description
percent-complete Integer The percentage of the Create an error alert operation that has been performed.

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Example

Request

GET /api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000 HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 15 May 2015 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-length:200

{
"kind": "instance",
"resource-name": "alerts",
"resource-version": "1.0",
"properties": {
    "type": "error",
    "msgid": "025a000a",
    "msgtext": "Internal software error 025a000a 00000001.",
    "timestamp": 1430158827,
    "size": 3158827,
    "self": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000",
    "diag-info": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000/diag-info"
    }
}

Create an error alert

Use this operation to create a new error alert.

Parallel operations may be rejected with HTTP status 409 Conflict.

Status FW release SW release Notes
implemented None MVP None

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

Network

This operation is available from the following network(s):

HTTP Method and URI

POST /api/com.ibm.zaci.system/alerts
Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types
Content-type media types

Request message body

The request message body must contain data formatted as specified in the Content-type header, with kind=request. The format of the parameters object is described in the following table.

Name Type Rqd/Opt Description
reason String Rqd A textual description of the issue, up to 200 characters.
The comma character is not permitted, any occurrences are converted to a blank. Leading and trailing blanks are removed.
diag-info String Enum Opt concurrent, diagnostic information is collected without stopping the appliance.
disruptive, diagnostic information is collected after stopping the appliance.
If not specified, the default value is concurrent.

Response

An HTTP status code of 202 indicates that the request has been accepted.

For a concurrent request, the response message body contains data formatted as requested in the Accept header, with kind=response.

Name Type Description
self String/URI The URI of the alert being created

The returned URI can be used to poll the status of the create request, via the Retrieve an alert operation.

For a disruptive request, a reboot has been scheduled. No response body is provided. The reboot operation is asynchronous, so you must now poll for the appliance to be operational. Please see Check appliance operational status. During this loop, there will likely be a short time where the appliance still responds (shutdown in progress), then a time where your connection is refused, then a time where the appliance is active but not operational. You must handle these transient errors by continuing to poll. The Retrieve appliance information operation returns a boot-time property that can be helpful in distinguishing between appliance instances.

An HTTP status code of 409 indicates that another create request blocking the request is already active. Retry your request at a later time.

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Example

Request

POST /api/com.ibm.zaci.system/alerts HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-length:200

{
"kind": "request",
"parameters": {
    "reason": "No response from REST APIs for over 5 minutes.",
    "diag-info": "concurrent"
    }
}

Response

HTTP/1.1 202 ACCEPTED
Date: Tue, 15 May 2015 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-length:200

{
"kind": "response",
"parameters": {
    "self": "/api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000"
    }
}

Delete an alert

Use this operation to delete an alert.

Status FW release SW release Notes
not implemented None 2.X None

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

Network

This operation is available from the following network(s):

HTTP Method and URI

DELETE /api/com.ibm.zaci.system/alerts/{instance-id}

In this request, the URI variable {instance-id} is the alert instance identifier. The URI is obtained via the Retrieve a list of alerts operation.

Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

Request message body

None

Response

An HTTP status code of 204 indicates a successful operation.

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Example

Request

DELETE /api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000 HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 204 NO CONTENT
Date: Tue, 15 May 2015 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0

Download an error alert's diagnostic information

Use this operation to download diagnostic information for an error alert, for submission to the appliance support team.

notification alerts do not contain diagnostic information, 404 Not Found is returned.

Note: Successful completion of this operation makes the alert eligible for automatic deletion. The alert may be deleted at any time.

Status FW release SW release Notes
implemented None MVP no encryption or signing

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

Network

This operation is available from the following network(s):

HTTP Method and URI

GET /api/com.ibm.zaci.system/alerts/[{instance-id}|{correlid}]/diag-info

In this request, the URI variable {instance-id} is the alert instance identifier (uuid) or the correlation identifier (correlid). The URI is obtained from the Retrieve an alert operation or the Retrieve a list of alerts operation.

When an correlation identifier is supplied the response may contain multiple diagnostic information for multiple alerts. If multiple alerts are contained the response will contain an archive containing the alerts.

Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types

Request message body

None

Response

An HTTP status code of 200 indicates a successful operation. The response message body contains the diagnostic information in the format requested by the Accept header. A Content-Disposition header is used to provide a suggested file name.

An HTTP status code of 410 (GONE) indicates that the data has been cleaned up and is therefore no longer available.

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Special reason codes:

HTTP Status Secure Service Container Reason Description
410 1 FFDC data is no longer available.

Example

Request

GET /api/com.ibm.zaci.system/alerts/00000000-0000-0000-0000-000000000000/diag-info HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/octet-stream

Response

HTTP/1.1 200 OK
Date: Tue, 15 May 2015 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-type: application/octet-stream
Content-length: 200000
Content-Disposition: Attachment; filename=1459437401161099.data

... binary data ...

Archive all alerts

Use this operation to hide all alerts and any associated diagnostic data.

Caution: This operation cannot be undone.

Status FW release SW release Notes
implemented None MVP None

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

Network

This operation is available from the following network(s):

HTTP Method and URI

DELETE /api/com.ibm.zaci.system/alerts
Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

Request message body

None

Response

An HTTP status code of 204 indicates a successful operation, the archive has completed. A notification alert, AZIZ9999I, is issued to document the operation. Refer to the AZIZ Messages chapter of the zACI External Interfaces document for more information.

An HTTP status code of 202 indicates that the archive has been scheduled, but has not yet completed. If desired, the caller may poll for the archive to complete by using the Retrieve a list of alerts operation to search for the AZIZ9999I notification alert .

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Example

Request

DELETE /api/com.ibm.zaci.system/alerts HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0

Response

HTTP/1.1 204 NO CONTENT
Date: Tue, 15 May 2015 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0