RESTful Web Services › How to Utilize CA OPS/MVS Web Services › Making Web Service Requests to Generate an API Event

Making Web Service Requests to Generate an API Event

You can generate a generic API event to run in CA OPS/MVS by POSTing a request to the event web service. The API event has an event qualifier generated using the web service request begins with WS. Thus, you can write a rule for “)API WS*” to trigger on events that this web service generates. A sample rule APIWSEV is provided in the &hlq.CCLXRULS data set to demonstrate how the API rule can be coded to fire on web service requests.

The event web service is asynchronous in nature. An HTTP POST request is the mechanism to generate the API event. No information is returned regarding the execution of the event.

The POST requires the request to include XML data which allows the requester to specify the information needs for your API event. This information includes: an event code (any string up to a length of 8 bytes) and an event text string – up to 256 bytes in length. This XML is defined with the following schema:

<?xml version="1.0" encoding="utf-8"?>
<WSEvent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xsi:schemaLocation="http://www.ca.com/automation/opsmvs/websvc/msgData WSEvent.xsd"
    xmlns="http://www.ca.com/automation/opsmvs/websvc/msgData">
<EvtCode>ID string</EvtCode> 
<EvtText>any string of printable data</EvtText>
</WSEvent>

The EvtCode tag specifies an 8-byte string of your choosing. This value is reflected when the API rule fires in variables API.ID.

Note: The web service request always prepends the string ‘WS’ to this tag to come up with the API qualifier. Thus, the API event will fires on qualifier: WStag.

The EvtText tag specifies a 255-byte string of your choosing. This value is reflected when the API rule fires in variables API.TEXT.

A sample security rule (SECWSEV) to control access to the underlying OPSAPI function is available in the distributed CCLXRULS library. This rule uses the same user list that is initialized by SECWSGV, so you should enable this rule concurrently with SECWSGV. However, this rule is merely a sample. You can choose to write your own rules to accept or reject all web services requests in any manner or combinations that you see fit.

Additionally, a sample rule APIWSEV has been provided to demonstrate firing a rule when a generic event initiated through the web service “event” request. Note that since this event is “generic”, there is virtually no limit to the automation that can be initiated by such an event. With an API rule, you can parse the incoming text string (see API.TEXT above) and determine the automation that you want to invoke.

Example Web Services Calls

The following RESTful Requests table shows these URIs:

Qualifying Event URI Requests

Subsystem Query String

Any POST request to URI event can include the sub query string to direct the request to a specific OPS/MVS subsystem.

Note: All requests are relative to the host to which the request is directed.

If the subsystem that you specified does not exist on the server host, you receive the following error:

OPxnnnnI OPSAPI COMMAND REJECTED - SUBSYSTEM OPSx IS NOT ACTIVE

appCode = -nnnn

The following Qualifying URI Requests table shows these query strings that are attached to the URI:

Responses from the Web Services

GET responses are HTTP documents that contain the following information:

HTTP status code

This code indicates the success or failure of the request.

HTTP header

The response headers relevant to the request.

HTTP body

Contains a schema-defined XML document representing the table information requested. In the case of an error, an XML document containing relevant error information is returned in the HTTP body. This XML document conforms to the WSResult schema.

Note: For HTTP Status Codes, values less than 300 represent success. Any other value represents a failure. See RFC2616 for a comprehensive list of HTTP codes.

The following table lists common HTTP status codes:

Note: For a comprehensive list of HTTP status codes, see RFC2616.

Example: TableList XML Response

The following example shows an excerpt from an XML response document from this URI request:

GET /opsmvs/web/tables
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TableList count="13" xsi:schemaLocation="http://www.mydomain.com/automation/opsmvs/websvc/msgData">
    <Table href="http://servername:8090/opsmvs/web/tables/COLUMN">
        <TableName>COLUMN</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/USER1">
        <TableName>EDDMA01</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/USER1_SSMTEMP">
        <TableName>EDDMA01_SSMTEMP</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/EMPTY">
        <TableName>EMPTY</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/TABLE">
        <TableName>TABLE</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/TABLE4">
        <TableName>TABLEL4</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/TABLE5">
        <TableName>TABLE5</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/TABLE6">
        <TableName>TABLE6</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/TABLEA">
        <TableName>TABLEA</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/TABLEB">
        <TableName>TABLEB</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/SSM_MANAGED_TBLS">
        <TableName>SSM_MANAGED_TBLS</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/STCTBL">
        <TableName>STCTBL</TableName>
    </Table>
    <Table href="http://servername:8090/opsmvs/web/tables/TABLE">
        <TableName>TABLE</TableName>
    </Table>
</TableList>

The TableList element (delimited by tags <TableList> and </TableList>) indicates that the whole response is concerned with a list of tables. Inside TableList, Table contains one further element, TableName that contains the actual name of the table.

Example: TableList XML Response with Column Names and Attributes

The column information is arranged in a hierarchical fashion.

The ColumnList element is at the highest level. It contains one or more Column elements. Each Column element has attributes attached to it which contain various properties pertinent to that column.

The following example shows an excerpt from an XML response document from this URI request:

GET /opsmvs/web/tables/STCTBL
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TableList count="1" xsi:schemaLocation="http://www.mydomain.com/automation/opsmvs/websvc/msgData">

 <Table href="http://servername:8090/opsmvs/web/tables/STCTBL">
    <TableName>STCTBL</TableName>
   <ColumnList count="14">
     <Column href="http://servername:8090/opsmvs/web/tables/STCTBL/NAME"
      datatype="CHAR" datalen="18"
	properties="UC NN PK">
	<ColumnName>NAME </ColumnName>

   <ColumnName href="http://servername:8090/opsmvs/web/tables/STCTBL/INTERNAL_DATA1" 
     datatype="HEX" datalen="32">INTERNAL_DATA1</ColumnName>
        </ColumnList>
  </Table>
</TableList>

This response is also a TableList XML document. However, it now has additional elements that relate to columns under the Table element. Like TableList, The ColumnList starts a list of columns. The Column element contains several attributes that hold properties that apply to the entire column. The ColumnName element defines the column name itself as a data value, and several properties of the column are returned as attributes.

In the previous XML response document, the NAME column has the CHAR data type, with a maximum length of 18. This column is a PRIMARY KEY, accepts only UPPER CASE text, and does not accept NOT NULL as a value.

The INTERNAL DATA1 column contains hexadecimal data with a maximum of length of 32.

Example: TableList XML Metadata

The response XML returns several pieces of metadata as attributes of the ColumnName element. The following list describes these attributes:

datatype

Specifies the type of data that the column can contain

datalen

Specifies the length of the data that the column contains

href

Specifies a RESTful URI to the next resource in the table

properties

Specifies a (possibily empty) list of properties that are associated with this column.

The following table summarizes the possible values for each of the attributes:

Example: TableList XML Response with Column Data

The column information is arranged in a hierarchical fashion.

The ColumnList element is at the highest level. It contains one or more Column elements. Each Column element has attributes attached to it which contain various properties pertinent to that column. Also, if requested in the URI, one or more ColumnData elements are present, and a count attribute is present to indicate how many data rows exist.

The following example shows an excerpt from an XML response document from this URI request:

GET /opsmvs/web/tables/STCTBL/NAME CURRENT_STATE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TableList count="1"
xsi:schemaLocation="http://mydomain.com/automation/opsmvs/websvc/msgData">
    <Table href="http://servername:8090/opsmvs/web/tables/STCTBL">
        <TableName>STCTBL</TableName>
        <ColumnList count="2">
            <Column count="3" href="http://servername:8090/opsmvs/web/tables/STCTBL/NAME" datatype="CHAR" datalen="18" properties="UC NN PK">
                <ColumnName>NAME</ColumnName>
                <ColumnData>OPSMAIN</ColumnData>
                <ColumnData>OPSME</ColumnData>
                <ColumnData>OPSMISC4</ColumnData>
            </Column>
            <Column count="3" href="http://servername:8090/opsmvs/web/tables/STCTBL/CURRENT_STATE" datatype="CHAR" datalen="8" properties="UC DF">
                <ColumnName>CURRENT_STATE</ColumnName>
                <ColumnData>ACTIVE</ColumnData>
                <ColumnData>INACTIVE</ColumnData>
                <ColumnData>UNKNOWN</ColumnData>
            </Column>
        </ColumnList>
    </Table>
</TableList>

This response is also a TableList XML document. However, it now has additional elements that relate to columns and column data under the Column element.

Like the previous example, the ColumnList starts a list of columns and the Column element contains a ColumnName element to define the name of the column. Additionally, there is a count attribute that defines how many rows of data are present in ColumnData elements within the Column element.

How to Retrieve Attributes from the XML Response

OPSWebSvcAppClientDist.zip contains two sample Java client programs. This file installs into the web HSF/ZFS. You can find the source for all the samples in the directory OPSWebSvcApp\src\com\ca\automation\opsmvs\apps\webclient after you unzip OPSWebSvcAppClientDist.zip. A precompiled copy of these sample programs is provided, but if they do not run properly from your Windows workstation, run the buildapp.bat script to compile the java programs locally (requires a local JDK).

REXXCmdClient.java is a simple command line application for performing simple RESTful communication with CA OPS/MVS web services. Run runapp.bat from a Windows workstation to invoke REXXCmdClient. Driver.java is a simple GUI program for demonstrating RESTful requests to OPS/MVS web services. Run runswing.bat from a Windows workstation to invoke Driver.

Both programs demonstrate how to send HTTP requests, and how to parse and interpret the XML responses.

Follow these steps:

1. Unmarshal the XML string into the TableList class.
2. Call the getDatatype, getDatalen or getProperties methods to retrieve the datatype, datalen, and properties attributes.

   Note: You only need these methods to retrieve these attributes. The unmarshalToOb function in ClientWebUtil has a working example about how to accomplish this task.

3. If column data is present, call the getColumnData method to retrieve the list of data elements.

The requests and XML responses that are defined for CA OPS/MVS Web Services follow common and standards for any web services. Therefore, you can use a code from any language that supports HTTP requests and XML responses to utilize a CA OPS/MVS Web Service.