Received a "postAlert" method for creating alerts in SOI using the SOI connector accelerator. CA Engineering Services provided a document on how to install and use it. Following is an excerpt from it.
Using the REST API
The REST API which is included with Connector Accelerator allows users to send alerts and CIs to Connector Accelerator via HTTP using either a browser, a utility such as curl or via a programmatic method such as Perl or Java which can make HTTP connections
In fact the SOIPost client which is shipped with Connector Accelerator uses the same REST API to communicate with Connector Accelerator.
The basic URL syntax for posting to Connector Accelerator via the REST API is:
http://<server>:<port>/<function>?<param1>=<value1>&<param2>=<value2> ….
<server> represents the Connector Accelerator server
<port> represents the Connector Accelerator port as configured in the <Listener> tag
<function> is the API function and is one of “postAlert”, “delete”
When calling the REST API, any errors or missing parameters are reported directly in HTML in the http response.
postAlert
The postAlert function is the most common and is the same one used by the SOIPost client to send alerts.
Param1, 2, etc. must be sent so create the input map. The following parameters are required, similar to what is required by SOIPost.
NOTE: When using the REST API, the URLs and parameter names described below ARE case-sensitive
user_severity or Severity – You must specify the severity (corresponding to the –r parameter of SOIPost). If you assign it to user_severity then you can use all of the extended values and they will be transformed accordingly via connector policy. If you choose to use “Severity”, your values must conform to USM
hostname – As with SOIPost, hostname is a required attribute
Summary – This is the message summary and is the required USM summary. If “Message” is not present, Summary will be copied to Message, but you have the option of including the Message parameter if the values are different
For example,
http://soi:7777/postAlert?hostname=Myserver&Severity=Minor&Summary=This%20is%20a%20Test
NOTE that because we are using HTML for rest we have to use %20 to represent a space in the summary / message.
delete
The “delete” function provides away to remove a CI from SOI that may have been posted erroneously from SOIPost, or is in fact, no longer part of the environment
The delete function contains one parameter, id. The “id” parameter corresponds to the MdrElementID of the CI to be deleted
For example,
http://soi:7777/delete?id=MyServer
This would delete the “MyServer” CI presuming you are using the host name as the unique ID
Alert/CI Workflow for SOIPost and REST
The following is the workflow that takes place when the SOIPost client is executed. (The workflow is identical for the “postAlert” function of the REST API, beginning with step 3. Step 2 is you making the REST call.)
1) SOIPost takes the input parameters from the command-line and converts them into an input map consisting solely of name/value pairs of map attributes and their values.
2) An HTTP connection is established with Connector Accelerator on its listening port and the input map is transmitted to Connector Accelerator
3) Connector Accelerator performs validation on the input map, ensuring that all required attributes are present. If not, an error response is sent back to the client
4) Presuming that the map passes validation, TWO input maps are passed to SOI, one representing the data as a CI (Item), and one representing the data as an Alert. This is the critical piece of the workflow and allows for the creation of CIs on the fly. As you know, for an alert to be posted to SOI, there must be a corresponding CI to which to “bind” the alert. Using this “two map” (aka “two pass”) workflow ensures that the CI will also be posted. If you are familiar with the SNMP connector for SOI, it uses a similar workflow when processing incoming traps.
One other function of the workflow that is worthy of note: For each CI/alert posted via SOIPost or REST, a unique GUID is created to identify that client request. This attribute, called either “alertGUID” for Alerts or “ciGUID” for CIs is added to the map passed to SOI, and functions as an audit trail mechanism for troubleshooting purposes. If for some reason the alert or CI doesn’t end up in SOI properly, log files will contain reference to this GUID. The GUID is also passed back to the client in the response for this tracking purpose.