CA Service Operations Insight

Transcription

1 CA Service Operations Insight Web Services Reference Guide r3.2

2 This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the Documentation ) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation is proprietary information of CA and may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. If you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections , , and (c)(1) - (2) and DFARS Section (b)(3), as applicable, or their successors. Copyright 2013 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

3 CA Technologies Product References This document references the following CA Technologies products: CA Application Performance Management CA Business Intelligence CA Clarity Project and Portfolio Manager CA CMDB CA Configuration Automation (formerly CA Application Configuration Manager) CA ehealth Performance Manager (ehealth) CA Embedded Entitlements Manager (CA EEM) CA Event Integration CA Insight Database Performance Manager CA NSM CA Process Automation CA Service Desk CA Server Automation (formerly CA Spectrum Automation Manager) CA SiteMinder CA Spectrum CA Systems Performance for Infrastructure Managers CA SystemEDGE CA Virtual Assurance

4 Contact CA Technologies Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At you can access the following resources: Online and telephone contact information for technical assistance and customer services Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product Providing Feedback About Product Documentation If you have comments or questions about CA Technologies product documentation, you can send a message to techpubs@ca.com. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at

5 Contents Chapter 1: About This Guide 9 Intended Audience... 9 Related Publications... 9 Local Documentation and Online Bookshelf Chapter 2: CA SOI REST Web Services 13 REST Web Services Overview Base CA SOI REST Web Services URL Supported REST HTTP Methods Endpoints Web Application Description Language URL Common Requirements REST Web Services Authentication Configure Authentication-Related Security Filter Parameters REST Web Services Ordering Metric Service Ordering Group Ordering Customer Ordering CI Ordering Alert Queue Ordering Alert Ordering User Ordering Escalation Policy Ordering Escalation Policy Action Ordering Configuration Ordering Configuration Node Ordering Available CA SOI REST Web Services Alert Queue REST Web Services Alert REST Web Services CI REST Web Services Configuration REST Web Services Customer REST Web Services REST Web Services Escalation Policy Action REST Web Services Escalation Policy REST Web Services Group REST Web Services Contents 5

6 Meta REST Web Services Schedule REST Web Services Service REST Web Services User REST Web Services Chapter 3: REST Web Services Example 35 Chapter 4: Calling CA SOI REST Web Services from Perl Scripts 37 Prerequisites Set Up Users in a CA SOI Environment Code Overview Chapter 5: WS-MAN Web Services 45 Introduction to WS-MAN Web Services Web Services Architecture Resources and Operations Available Web Services Available Web Clients USM Entity Web Services Entity Web Services Overview Get an Entity Get a List of Entities Create an Entity Update an Entity Delete an Entity Entity Web Services Examples Subscribe to Notifications for Entity Changes USM Binary Relationship Web Services BinaryRelationship Web Services Overview Get a Relationship Get a List of Relationships Create a Relationship Update a Relationship Delete a Relationship Relationship Web Services Examples Subscribe to Notifications for Relationship Changes Notification Web Services Notification Web Services Overview How to Subscribe to Notifications for Entity, Relationship, and Alert Changes Create a Subscription Web Services Reference Guide

7 Delete a Subscription Pull a Subscription Notification Notification Web Services Examples Queue Web Services Queue Web Services Overview Get a Queue Get a List of Queues Create a Queue Update a Queue Delete a Queue Queue Web Services Examples Customer Web Services Customer Web Services Overview Get a Customer Get a List of Customers Customer Web Services Examples Alert Web Services Alert Web Services Overview Get an Alert Get a List of Alerts Create an Alert Update an Alert Clear an Alert Alert Web Services Examples Subscribe to Notifications for Alert Changes Propagation Policy Web Services Propagation Policy Web Services Overview Get a Propagation Policy Get a List of Propagation Policies Create a Propagation Policy Update a Propagation Policy Delete a Propagation Policy Propagation Policy Web Services Examples Escalation Policy Web Services Escalation Policy Web Services Overview Get an Escalation Policy Get a List of Escalation Policies Create an Escalation Policy Update an Escalation Policy Delete an Escalation Policy Escalation Policy Web Services Examples Escalation Action Web Services Contents 7

8 Escalation Action Web Services Overview Get an Escalation Action Get a List of Escalation Actions Create an Escalation Action Delete an Escalation Action Escalation Action Web Services Examples Web Services Reference Guide

9 Chapter 1: About This Guide This guide covers the Representational State Transfer (REST) and WS-Management (WS-MAN) web services that are available with CA SOI. The document describes the resources exposed and the available operations to perform against these web services. This section contains the following topics: Intended Audience (see page 9) Related Publications (see page 9) Local Documentation and Online Bookshelf (see page 11) Intended Audience This guide is intended for product administrators, domain manager administrators, or integration developers who are interested in extending the CA SOI solution by integrating its data with other products through REST and WS-MAN web services. The guide assumes experience working with these web services and prior knowledge of the related concepts. Related Publications The following publications, provided on the installation media and the CA SOI online bookshelf, provide complete information about CA SOI: Administration Guide Provides information about administering and maintaining the product after installation. Connector Guide Provides general information about connectors and the connector infrastructure and details about creating integrations through custom connectors and other methods. Event and Alert Management Best Practices Guide Provides concepts, procedures, and best practices for managing the event and alert stream that CA SOI receives from connectors. Implementation Guide Provides information about installing and implementing the product. Chapter 1: About This Guide 9

10 Related Publications Online Help Readme Provides information about performing tasks in CA SOI user interfaces. Provides information about known issues and information that is discovered after the guides were finalized. A CA SOI release may not have a Readme. Release Notes Provides information about operating system support, system requirements, database requirements, web browser support, and international support. Service Modeling Best Practices Guide Provides procedures and best practices for modeling services including the following methods: service imports, service discovery, and manual service modeling. Troubleshooting Guide Provides information and procedures to diagnose and resolve problems with CA SOI. User Guide Provides information for nonadministrative users about using the product, such as responding to alerts and viewing reports. The following publications provide information about CA Catalyst connectors and are located on each downloadable connector package: <Product Name> Connector Guide Provides information about a specific CA Catalyst connector, including prerequisites, installation, configuration, and data mapping. <Product Name> Connector Readme Provides known issues for a specific CA Catalyst connector and information discovered after the product-specific Connector Guide was finalized. 10 Web Services Reference Guide

11 Local Documentation and Online Bookshelf Local Documentation and Online Bookshelf CA SOI provides access to the documentation locally and online. Local Documentation The local documentation is installed in the SOI_HOME\Documentation folder and includes the PDFs for all guides. The online help is also installed with CA SOI and accessed through the Dashboard (PC and Mobile) and USM Web View. The local documentation is updated with specific releases only. Online Bookshelf The online bookshelf is on support.ca.com and provides the most current documentation set, which can be updated between releases. The online bookshelf also provides the documentation for the latest supported versions of CA Business Intelligence, CA EEM, and CA Process Automation. For a list of Bookshelf updates, click the Update History link on the Bookshelf. CA SOI provides access to the online bookshelf in the following locations: The Dashboard provides a Bookshelf link. The Operations Console provides a menu link under Help, Bookshelf. Note: If you are unable to access the online bookshelf, contact your system administrator to provide the documentation set PDFs. Chapter 1: About This Guide 11

12

13 Chapter 2: CA SOI REST Web Services This section provides information about REST web services in CA SOI. This section contains the following topics: REST Web Services Overview (see page 13) REST Web Services Authentication (see page 17) REST Web Services Ordering Metric (see page 19) Available CA SOI REST Web Services (see page 23) REST Web Services Overview This section helps administrators and integration developers understand how CA SOI REST web services work, including the base URL, supported methods, endpoints, and common requirements. Representational State Transfer (REST) is a client-server architectural style of building applications that leverages the fundamental properties of HTTP to manage objects accessible at a URL. REST architecture and applications are stateless, which means that no client context information is stored between requests. Each request contains all the information necessary to service the request. REST web services are lightweight, HTTP-based, easy to create and use, and have the desirable property of relating the classes of data to each other using hyperlinks. REST web services provide a simple yet powerful mechanism to interact with data. Using these web services, integration developers can configure the product and can make it communicate through the REST interface. They can use REST web services directly to send HTTP requests to the server for the resources they want to manipulate. CA SOI lets you expose CA SOI data over REST web services. Because of the inherent standards in the REST architecture, CA SOI REST web services make the CA SOI data accessible to many different development environments. Several resources such as CA SOI user interfaces and third-party interfaces can then consume the exposed data. This ability helps integration developers extend the CA SOI solution by integrating its data with other products through REST web services. These interfaces provide an HTTP-based integration point to the CA SOI data, allowing read or write access. Using these web services, you can access the CA SOI data directly from a browser or can integrate it into your own applications. You can use these web services with any language that understands how to manage HTTP integration. Chapter 2: CA SOI REST Web Services 13

14 REST Web Services Overview REST web services access resources by using a Uniform Resource Identifier (URI) a character string that identifies a name or resource on the Internet. An application using REST web services makes an HTTP request to a URI and parses the response. Such identification enables interaction with representations of the resource over a network. Each client-to-server request contains all the information necessary to understand the request, and does not use any stored context on the server. CA SOI REST web services follow Hypertext As The Engine Of Application State (HATEOAS) principle. This principle implies that the resources that a request returns to the server contain the next state changes the client can navigate as links. The representations of the resources are interrelated using URLs, enabling you to move from one state to another. This section helps you understand CA SOI REST web services as follows: Provides general concepts and common requirements about using CA SOI REST web services Provides information about how to retrieve, manipulate, and set data using various CA SOI REST web services Defines information that you can pass to the REST interface Provides information about how to send web services requests to perform specific tasks and verify that you get a meaningful response Note: REST web services use the HTTP protocol for communication. Familiarity with both the HTTP protocol and the REST architecture is required. This section, therefore, assumes that you have experience working with REST web services and prior knowledge of related concepts (such as WADL and Hypertext As The Engine Of Application State). Base CA SOI REST Web Services URL The base URL for all CA SOI REST web services is as follows: server port Specifies the server where the REST web service is located. Specifies the port number where the REST web service is located. The default port numbers are 7403 (secure) and 7070 (non-secure). Examples of base URLs are (secure) and (non-secure). 14 Web Services Reference Guide

15 REST Web Services Overview Note: By default, the non-secure interface is not allowed with the Basic authentication (user name and password), where the user name and password are sent as a plain text (Base64 encoded). If you want to allow Basic authentication over the non-secure connection, you can configure the web.xml file. You can always use the non-secure interface with other types of authentications: CA EEM token and JSESSION. However, you can use the secure interface with all three types of authentications: Basic (user name and password), CA EEM token, and JSESSION. For more information about these authentication methods, see the REST Web Services Authentication (see page 17). Supported REST HTTP Methods As an integration developer, you use REST HTTP methods with the REST web service URLs to manage information in your environment. REST HTTP methods help you achieve the following objectives: Access and modify associated resources Send an HTTP request to the server for the resource that you want to manipulate Control the attributes that you want to retrieve using HTTP headers CA SOI REST web services support the following REST HTTP methods: POST (Create) Creates a resource. The web service can respond with data or status indicating a success or failure. GET (Read) Performs a query on a resource and retrieves data. The data that is returned from the web service is a representation of the requested resource. PUT (Update) Updates an existing resource. DELETE (Delete) Removes an existing resource. Endpoints REST web services URLs are specific endpoints. Endpoints are types of items that you use with appropriate HTTP request methods to return a list of results or create, update, or delete an item. Chapter 2: CA SOI REST Web Services 15

16 REST Web Services Overview For example, the endpoint (used with the GET method) to get a list of links that let you find more information about a specific service (identified by a service ID) is as follows: GET Note: For more information about specific endpoints, see Available CA SOI REST Web Services (see page 23). Web Application Description Language URL You can obtain the complete Web Application Description Language (WADL) for CA SOI REST web services by adding application.wadl?format=xml to the base URL. The endpoint is used with the GET method as follows: GET This WADL file outlines the available operations. Common Requirements The following requirements are applicable to all the requests: CA SOI REST web services require one of the authentication (see page 17) methods for each call. CA SOI REST web services produce the output in Atom format. Atom represents a document format that is based on XML, and that describes lists of associated resources. For Atom version, do one of the following tasks: Send the Accept header Accept: application/atom+xml. Specify the URL query parameter format=atom. The query parameter format takes precedence over the format defined in the Accept header. CA SOI REST web services follow Hypertext As The Engine Of Application State (HATEOAS) principle. This principle implies that the resources that a request returns to the server contain the next state changes the client can navigate as links. The typical output of a CA SOI REST web service request is the Atom feed, which can be ordered and paged to organize the output properly. For ordering and paging, you can use the following parameters: metric Specifies the ordering domain. The values depend on the type of the returning object. The Ordering Metric (see page 19) section includes detailed information about what values you can use. 16 Web Services Reference Guide

17 REST Web Services Authentication desc size start (If true) Returns the result in the descending order. Specifies the size of the page; that is, how many results to show on a single page. The default value is 25. The default value is used when you do not specify any value for the parameter, or you provide an invalid value (for example, a negative value). Specifies the page from where to start; that is, how many results to skip from the beginning. The default value is 0; therefore, skip zero records implies start from the beginning. Note: Examples in this section demonstrate how CA SOI REST web services use create, read, update, and delete HTTP operations on CA SOI objects. Use these examples to understand how each REST operation interacts with CA SOI objects. REST Web Services Authentication This section helps administrators and integration developers understand the different authentication methods that the REST web services support and how to customize the acceptable authentication methods. CA SOI REST web services support authentication in three ways: using a user name and password (Basic authentication), using a CA EEM artifact, or using a JSESSIONID. Typical communication with CA SOI REST web services is authenticated through the user name/password or CA EEM artifact in the first call, and then using the JSESSIONID for all other subsequent calls. The last call is the logout call that invalidates the session. Therefore, for the first call, use one of the two methods: user name/password or CA EEM artifact. This first call returns the JSESSIONID, which the clients can then start using for making subsequent calls. The JSESSIONID authentication is the best performance authentication method, because it does not require the REST web service to verify the password or CA EEM artifact against CA EEM. Additional information about these authentications is as follows: Using the user name and password (Basic authentication) The user name and password are sent in the form of the Basic HTTP authentication in the HTTP header. The password is encoded by using Base64 encoding and can be easily decoded; therefore, this type of authentication is supported over a secure SSL channel (HTTPS protocol). For a typical CA SOI installation, it is port 7403, for example, Note: Only CA EEM users have access to CA SOI REST API. Therefore the samuser user is not able to access the REST API. Chapter 2: CA SOI REST Web Services 17

18 REST Web Services Authentication Using the one-time CA EEM artifact In this type of authentication, the CA EEM artifact can be obtained by calling the SafeSession.exportSession() method. You can use this type of authentication with both the protocols HTTP and HTTPS. Note: For more information about CA EEM sessions, see the CA EEM documentation. Using the JSESSIONID This type of authentication sends the JSESSIONID in the cookie header parameter. Both the previously mentioned authentication methods (user name/password and CA EEM artifact) set a cookie with the JSESSIONID value. The JSESSIONID can then be used in all subsequent calls through HTTP or HTTPS protocol. The session expires after 30 seconds of inactivity or after a call to the logout endpoint Note: You can also configure authentication-related security filter parameters in the web.xml configuration file. For more information, see Configure the Authentication-related Security Filter Parameters. Configure Authentication-Related Security Filter Parameters The web.xml file includes authentication-related security filter parameters. You can configure the values of these parameters based on your unique IT environment requirements. This file is available in the folder SOI_HOME\SAMUI\webapps\rest\WEB-INF. Note: SOI_HOME represents the location where CA SOI is installed; for example, C:\Program Files\CA\SOI. Follow these steps: 1. Locate the web.xml file in the folder SOI_HOME\SAMUI\webapps\rest\WEB-INF. 2. Open the file using a text editor and search for the following section in the file: <filter-name>securityfilter</filter-name> This section includes three parameters that you can configure. 3. Specify the appropriate value in the <param-value>...</param-value> field of the following parameters: allowplaincredentials Specifies whether to allow Basic authentication over the non-ssl connection. Possible values are true and false. The default value is false, which implies that the Basic authentication is not allowed over the non-ssl connection. 18 Web Services Reference Guide

19 REST Web Services Ordering Metric Default: false Note: If the REST interface is accessed using the loopback address ( or ::1), the Basic authentication is always allowed. cachecredentials Specifies whether the REST interface must cache the user credentials instead of verifying the password for each request. When you cache the user credentials, the password verification process becomes faster. Therefore, when you use the user name/password authentication method for all calls, the caching improves the response of the REST interface, because the CA EEM call is skipped. Possible values are true and false. The default value is true, which implies that the interface must cache the user credentials. Default: true Note: User credentials are cached for 10 minutes. Therefore, if a user changes the password, the old password remains active in the REST interface until the cached record expires. sessioninactivateinterval Specifies the time (in seconds) for which the REST interface must keep the session active. If no request is using the session during the specified time, the client must authenticate again. Default: Review the new information and save the file. The changes are saved. REST Web Services Ordering Metric This section includes the ordering metric values for REST web services. The ordering metric specifies the ordering domain of the web service request output to organize the output appropriately. This section includes ordering metrics values for the following output items: Service (see page 20) Group (see page 20) Customer (see page 21) CI (see page 21) Alert Queue (see page 22) Alert (see page 22) Chapter 2: CA SOI REST Web Services 19

20 REST Web Services Ordering Metric User (see page 22) Escalation Policy (see page 22) Escalation Policy Action (see page 23) Configuration (see page 23) Configuration Node (see page 23) Note: All metric values are not case-sensitive. Service Ordering The following table includes the ordering metric values for Service: Metric Value Description NAME HEALTH RISK Ordered by the service name Ordered by the service health Ordered by the service risk AVAILABILITY Ordered by the service availability (last 24 hours) QUALITY SLA PRIORITY ALERT_COUNT DOWN_ALERT_COUNT CRITICAL_ALERT_COUNT MAJOR_ALERT_COUNT MINOR_ALERT_COUNT Ordered by the service quality Ordered by the service SLA status Ordered by the service priority Ordered by the down alert count Ordered by the down alert count Ordered by the critical alert count Ordered by the major alert count Ordered by the minor alert count Group Ordering The following table includes the ordering metric values for Group: Metric Value NAME Description Ordered by the group name 20 Web Services Reference Guide

21 REST Web Services Ordering Metric Metric Value PRIVILEGE_SET Description Ordered by the privilege set, which implies that all administrator groups and user groups would be together Customer Ordering The following table includes the ordering metric values for Customer: Metric Value NAME HEALTH RISK QUALITY PRIORITY DOWN_ALERT_COUNT CRITICAL_ALERT_COUNT MAJOR_ALERT_COUNT MINOR_ALERT_COUNT Description Ordered by the customer name Ordered by the customer health Ordered by the customer risk Ordered by the customer quality Ordered by the customer priority Ordered by the down alert count Ordered by the critical alert count Ordered by the major alert count Ordered by the minor alert count CI Ordering The following table includes the ordering metric values for CI: Metric Value NAME HEALTH USM_TYPE IP_ADDRESS OPERATIONAL_MODE Description Ordered by the CI name Ordered by the CI health Ordered by the USM type Ordered by the IP address Ordered by the CI operational mode Chapter 2: CA SOI REST Web Services 21

22 REST Web Services Ordering Metric Alert Queue Ordering The following table includes the ordering metric values for Alert Queue: Metric Value NAME ALERT_COUNT DOWN_ALERT_COUNT CRITICAL_ALERT_COUNT MAJOR_ALERT_COUNT MINOR_ALERT_COUNT Description Ordered by the alert queue name Ordered by the down alert count Ordered by the down alert count Ordered by the critical alert count Ordered by the major alert count Ordered by the minor alert count Alert Ordering The following table includes the ordering metric values for Alert: Metric Value SEVERITY TIME Description Ordered by the alert severity Ordered by the occurrence time User Ordering The following table includes the ordering metric values for User: Metric Value NAME Description Ordered by the user name Escalation Policy Ordering The following table includes the ordering metric values for Escalation Policy: Metric Value NAME Description Ordered by the escalation policy name 22 Web Services Reference Guide

23 Available CA SOI REST Web Services Escalation Policy Action Ordering The following table includes the ordering metric values for Escalation Policy Action: Metric Value NAME Description Ordered by the escalation policy action name Configuration Ordering The following table includes the ordering metric values for Configuration: Metric Value NAME Description Ordered by the configuration name Configuration Node Ordering The following table includes the ordering metric values for Configuration Node: Metric Value NAME Description Ordered by the configuration node name Available CA SOI REST Web Services The following CA SOI REST web services are available: Alert Queue (see page 24) Alert (see page 25) CI (see page 25) Configuration (see page 26) Connector Customer (see page 27) (see page 28) Escalation Policy Action (see page 28) Escalation Policy (see page 29) Chapter 2: CA SOI REST Web Services 23

24 Available CA SOI REST Web Services Group (see page 29) Meta (see page 31) Schedule (see page 31) Service (see page 31) User (see page 32) Note: The complete documentation for CA SOI REST web services is available at: port>/rest/docs/rest/ Alert Queue REST Web Services Alert queues are user-defined alert groups. Alert queues let you group alerts as they come in based on specific criteria to monitor the status of your infrastructure more efficiently. Using the Alert Queue REST web services, you can perform various operations on alert management queues in CA SOI: Create an alert queue Get a list of alert queues Get a list of alerts in an alert queue Get the alert queue definition Get hyperlink entries associated with an alert queue Get the status information for an alert queue Update an alert queue Delete an alert queue The GET, PUT, POST, and DELETE HTTP methods are used to perform these tasks, as appropriate. For example, to delete an alert queue, the HTTP method DELETE is used. Note: The complete documentation for the CA SOI Alert Queue REST web services is available at: port>/rest/docs/rest/resource_alertqueueresource.html 24 Web Services Reference Guide

25 Available CA SOI REST Web Services Alert REST Web Services Alerts are fault conditions that the integrated domain manager reports. Each alert is associated with a CI and contains properties such as severity, a summary of the condition, and when the condition occurred. Alerts are service impacting when they affect a CI that is part of a managed service. They are non-service impacting when they affect CIs that are not part of a managed service. Using the Alert REST web services, you can perform various alert-related operations in CA SOI: Get a list of alerts Get hyperlink entries associated with an alert Get the alert definition Get the status information for an alert Get a list of escalation policy actions associated with an alert Perform an escalation policy action on a specific alert Update an alert Delete an alert The GET, PUT, POST, and DELETE HTTP methods are used to perform these tasks, as appropriate. For example, to delete an alert, the HTTP method DELETE is used. Note: The complete documentation for the CA SOI Alert REST web services is available at: port>/rest/docs/rest/resource_alertresource.html CI REST Web Services CIs in CA SOI represent IT elements managed by a domain manager. Each CI belongs to a type (defined in the USM schema) such as ComputerSystem, Database, Process, and Relationship. Connectors transform managed objects from domain managers to adhere to the USM schema and import the objects into CA Catalyst as CIs. The CI REST web services let you perform the following operations: Get hyperlink entries associated with a CI Get the status information for a CI Get the CI USM information Get a list of alerts impacting a specific CI Get a list of children for a specific CI Chapter 2: CA SOI REST Web Services 25

26 Available CA SOI REST Web Services Get a list of parents for a specific CI Get a list of services for a CI The GET HTTP method is used to perform these tasks. Note: The complete documentation for the CA SOI CI REST web services is available at: port>/rest/docs/rest/resource_ciresource.html Configuration REST Web Services The CA SOI Configuration REST web services give you the flexibility to view and update integration configuration values as and when required using the programmable interface. You can override the static configuration values (such as CA EEM configuration, configuration) specified at the time of installation. For example, CA SOI has a number of integrations with various external products. This integration information is stored in configuration files, which can require updates based on some changes in the deployment environment. You can use the Configuration REST web services to view and update these configurations. You can perform the following tasks using the Configuration REST web services: Get a list of configuration nodes Get a list of configuration sections for a configuration node Get the configuration section definition Get hyperlink entries associated with a configuration section Update a configuration section The GET and PUT HTTP methods are used to perform these tasks, as appropriate. For example, to update a configuration section, the HTTP method PUT is used. Note: The complete documentation for the CA SOI Configuration REST web services is available at: port>/rest/docs/rest/resource_configurationresource.html 26 Web Services Reference Guide

27 Available CA SOI REST Web Services Customer REST Web Services A customer in CA SOI is any consumer of a managed service. You create customers and associate them with service models to see the impact of service degradation on the service consumer. Customer management provides an extra layer of insight into how end users dependent on provided services are affected when those services experience downtime or degraded performance. Using the Customer REST web services, you can perform customer-related operations in CA SOI: Get a list of customers Get hyperlink entries associated with a customer Get the status information for a specific customer Get a list of services associated with a customer Get a list of alerts on all services associated with a customer Get a list of subcustomers Get information about the parent customer Get information about the selected customers Get information about services of a specific customer Get the customer definition Get a list of services associated with a customer (as XML) Create a top-level customer Create a subcustomer Set customer services Update a customer Delete a customer The GET, PUT, POST, and DELETE HTTP methods are used to perform these tasks, as appropriate. For example, to delete a customer, the HTTP method DELETE is used. Note: The complete documentation for the CA SOI Customer REST web services is available at: port>/rest/docs/rest/resource_customerresource.html Chapter 2: CA SOI REST Web Services 27

28 Available CA SOI REST Web Services REST Web Services The CA SOI REST web services give you the option to create and send s using the REST programming interface. For example, you can create and send s about alerts from your application using the web services. You can perform the following task using the REST web services: Send an The POST HTTP method is used to perform this task. Note: The complete documentation for the CA SOI REST web services is available at: port>/rest/docs/rest/resource_ resource.html Escalation Policy Action REST Web Services Escalation policy action defines the action to perform when the policy criteria are met. For example, you can set an escalation policy action where when an alert matches escalation policy criteria, the alert triggers an action that sends an to the technician responsible for the affected service. Using the Escalation Policy Action REST web services, you can perform escalation policy action-related operations in CA SOI: Get a list of escalation policy actions Get hyperlink entries associated with an escalation policy action Get the escalation policy action definition The GET HTTP method is used to perform these tasks. Note: The complete documentation for the CA SOI Escalation Policy Action REST web services is available at: port>/rest/docs/rest/resource_escalationpolicyactionresource.html 28 Web Services Reference Guide

29 Available CA SOI REST Web Services Escalation Policy REST Web Services Escalation policy automates alert escalation according to user-defined criteria. When the policy criteria are met, a specified escalation action runs. Using the Escalation Policy REST web services, you can perform the following operations: Get a list of escalation policies Get hyperlink entries associated with an escalation policy Get the escalation policy definition Create an escalation policy Update an escalation policy Delete an escalation policy Get a list of assigned service IDs for an escalation policy Get a list of assigned alert queue IDs for an escalation policy Get a list of assigned escalation policy action IDs for an escalation policy Get a list of assigned schedule IDs for an escalation policy Set a list of escalation policy services Set a list of escalation policy alert queues Set a list of escalation policy actions Set a list of escalation policy schedules The GET, PUT, POST, and DELETE HTTP methods are used to perform these tasks, as appropriate. For example, to delete an escalation policy, the HTTP method DELETE is used. Note: The complete documentation for the CA SOI Escalation Policy REST web services is available at: port>/rest/docs/rest/resource_escalationpolicyresource.html Group REST Web Services A user group in CA SOI includes users having the same level of access privileges. You can access CA SOI user groups using the Group REST web services. The Group REST web services let you perform the following user group-related tasks: Get a list of groups Get hyperlink entries associated with a group Get the status information for a group Create a group Chapter 2: CA SOI REST Web Services 29

30 . Available CA SOI REST Web Services Update a group Delete a group Get a list of users assigned to a group Assign users to a group Remove a user from a group Get the user definition in the assigned group Get the user group access status for all alert queues Set the user group access status for all alert queues Get a list of specific privileged alert queues for a group Set a list of specific privileged alert queues for a group Get the user group access status for all services Set the user group access status for all services Get a list of specific privileged services for a group Set a list of specific privileged services for a group Get the user group access status for all customers Set the user group access status for all customers Get a list of specific privileged customers for a group Set a list of specific privileged customers for a group Get a list of all the privileges for the Administrator role Get a list of all the privileges for the Operator role The GET, PUT, POST, and DELETE HTTP methods are used to perform these tasks, as appropriate. For example, to delete a group, the HTTP method DELETE is used. Note: The complete documentation for the CA SOI Group REST web services is available at: port>/rest/docs/rest/resource_groupresource.html 30 Web Services Reference Guide

31 Available CA SOI REST Web Services Meta REST Web Services Using the Meta REST web services, you can retrieve administrator and operator group privileges: Get a definition of the Administrator group Get a definition of the Operator group The GET method is used to perform these tasks. Note: The complete documentation for the CA SOI Meta REST web services is available at: port>/rest/docs/rest/resource_metaresource.html Schedule REST Web Services Using Schedule REST web services, you can manage, create, or delete escalation schedules: Get a list of schedules Create a schedule Get schedule details Delete a schedule Get hyperlink entries associated with a schedule The GET, POST, and DELETE methods are used to perform these tasks. Note: The complete documentation for CA SOI Schedule REST web service is available at: port>/rest/docs/rest/resource_scheduleresource.html Service REST Web Services Services in CA SOI represent discrete business functions that can contain CIs that multiple domain managers manage. A service typically consists of several CIs, which can be grouped to represent things like web server farms or clusters. Services can also contain subservices, which are subordinate service models. Service models typically represent high-level abstract entities; for example, a web-based retail transaction service, an application server service, and a printing service. Chapter 2: CA SOI REST Web Services 31

32 Available CA SOI REST Web Services Using the Service REST web services, you can retrieve data about CA SOI services. The HTTP method GET is used to retrieve this information. You make an HTTP request, which uses the GET method, to a specific URL. The web service interprets the method in the URI as the action it must perform. The web service then retrieves the required data from the request and returns the output based on that data. You can perform the following operations using the Service REST web services: Get a list of services Get hyperlink entries associated with a service Get the status information for a service Get the service USM information Get the service metric history information Get a list of service alerts Get a list of children for a service Get a list of parents for a service Get a list of services based on service IDs Get a list of subservices Create a service Update a service Delete a service The GET, PUT, DELETE, and POST HTTP methods are used to perform these tasks, as appropriate. For example, to retrieve a list of services, the HTTP method GET is used. Note: The complete documentation for the CA SOI Service REST web services is available at: port>/rest/docs/rest/resource_serviceresource.html User REST Web Services You can access CA SOI users using the User REST web services. This ability lets you manage CA SOI users; for example, you can create, list, and update users. 32 Web Services Reference Guide

33 Available CA SOI REST Web Services The User REST web services let you perform the following user-related tasks: Create a user Get a list of users Get hyperlink entries associated with a user Get the user definition Get a list of groups associated with a user Update a user The GET, PUT, and POST HTTP methods are used to perform these tasks, as appropriate. For example, to update a user, the HTTP method PUT is used. User creation and assignment works as follows: 1. The endpoint information in the Create a User section lets you create users in CA EEM. The created users remain in the unassigned state. You can list the unassigned users using the unassigned parameter while getting a list of users. 2. The created user is assigned to the CA SOI application and the group by using the endpoint information specified in the Assign Users to a Group section. Therefore, this way, you cannot only create users and add them to a group, but also add existing users (for example, users that are created manually) to a group. Note: The complete documentation for the CA SOI User REST web services is available at: port>/rest/docs/rest/resource_userresource.html Chapter 2: CA SOI REST Web Services 33

34

35 Chapter 3: REST Web Services Example This section provides an example use case for leveraging the REST web services in Perl scripts to perform bulk operations such as user and group creation. This section contains the following topics: Calling CA SOI REST Web Services from Perl Scripts (see page 37) Chapter 3: REST Web Services Example 35

36

37 Chapter 4: Calling CA SOI REST Web Services from Perl Scripts The following section provides information about how to use REST web services to retrieve, post, and process CA SOI data, using a Perl script. Perl scripts are useful for the initial setup of the CA SOI platform because they allow you to automatically enter or process large amounts of data. You can use Perl scripts for making all types of calls, but this document highlights the main ways to embed REST web services calls in your scripts. This section contains the following topics: Prerequisites (see page 37) Set Up Users in a CA SOI Environment (see page 38) Code Overview (see page 39) Prerequisites You must have: Perl version or higher installed. Note: Verify that the Perl module XML::XPath is installed. Access to the Perl Script Example files in the following location: SOI_HOME\tools\examples\REST_Perl_Example\ Chapter 4: Calling CA SOI REST Web Services from Perl Scripts 37

38 Available CA SOI REST Web Services Set Up Users in a CA SOI Environment You can use the Perl script to process an input file and assign users to groups according to the file. This method of entering users into the system and assigning them to groups is useful when you want to process large amounts of data. If a user does not exist in the system, it creates the user. The format of the input file is comma-separated with user name first and group name last on each line. Example The following example shows three users being assigned to two user groups, using REST web services from Perl. Configure the Perl Script username1, groupa username2, groupa username3, groupb A prerequisite is that all groups exist in the system. Note: If a group does not exist in the system, the line containing that group is skipped. The script then continues with the next line. The Perl script starts with an environment definition constant where you can set up connectivity to REST web services, user credentials, and so on. Example The following code snippet shows configuration constants from the beginning of the Perl script. my $headless_server = 'soi-r2-test06'; # hostname my $headless_port = '7070'; # port for plain HTTP access my $headless_ssl_port = '7403'; # port for HTTPS access my $headless_user = 'samuser'; # admin user name my $headless_password = 'P@ssword01'; # admin user password my $password_for_created_users ='changeit'; # password for the newly created users my $page_size = 10000; # page size in which the data are fetched # larger value more data fetched per one call. 38 Web Services Reference Guide

39 Available CA SOI REST Web Services Code Overview PERL code contains detailed comments. This code overview highlights some key components of the PERL script. The following section provides examples that cover all aspects of calling REST web services, such as authentication, retrieving paged data, and parsing and posting data. You can use these examples to help create your own scripts to call REST web services. You can find the Perl Script Example file in the following location: SOI_HOME\tools\examples\REST_Perl_Example\ HTTP Access To make HTTP and HTTPS calls, you can use the LWP::Simple module. Example The following example shows how to tell Perl to use the LWP::Simple module: use LWP::Simple; # LWP package to work with HTTP requests The following classes are the most important of the package: LWP::UserAgent Behaves as a simple browser, where you can configure basic authentication, cookies, and so on. LWP::Request Represents the HTTP request. Note: The LWP::Request is not required for the HTTP GET method, because the request comprises URL only. However, it is required for HTTP POST and HTTP PUT methods where you pass the URL and the payload. LWP::Result The class representing the HTTP response, which contains the result code, http header and body. Chapter 4: Calling CA SOI REST Web Services from Perl Scripts 39

40 Available CA SOI REST Web Services HTTP GET Call Use the PERL script to perform an HTTP GET call. Example The following code snippet shows an HTTP GET call. Note: The code snippet does not contain authentication to keep the example simple. my $browser = LWP::UserAgent->new(); # create browser my $response = $browser->get(' # call HTTP get if ($response->is_success) return $response->content; die "Error while calling http get"; SSL Communication and Basic Authentication Method # check HTTP status # return the result # error To use a secure communication channel, you can use SSL communication and a basic authentication method. Example The following code snippets shows SSL communication and a basic authentication method: $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME}=0; my $browser = LWP::UserAgent->new(); $browser->credentials( 'server:7403', 'REST Authentication', 'bob' => 'bobspasswd'); # skip SSL certificate verification # create browser # BASIC auth # REALM my $response = $browser->get(' # call HTTPS get if ($response->is_success) return $response->content; die "Error while callings http get"; # check HTTP status # return the result When you authenticate using user name and password, REST web services returns a cookie with the session ID. Example The following code snippet shows the code that reads the cookies and then how they are used. # regular expression to select the cookie if ($response->header('set-cookie')!~ /(JSESSIONID=\w+);/) { die "cookie with jsession not found\n Aborting"; } 40 Web Services Reference Guide

41 Available CA SOI REST Web Services my $cookie = $1; # the first group is the value The cookie can be used for authentication in all other calls by setting the cookie in the request headers. $browser->default_header('cookie' => $cookie); #set the sessionid as cookie HTTP POST with LWP::Request Creation In addition to HTTP GET, the PERL code calls HTTP POST in REST web services. Note: The Post call is similar to the HTTP GET, but it requires that you set the payload by creating an LWP::Request. Example The following code snippet shows the creation of an LWP::Request. Parsing Response my $request = => ' $request->header('accept' => 'application/xml'); $request->content("<user> <username>bob</username> <password>changeit</password> </user>"); $request->content_type("application/xml; charset=utf-8"); my $response = $browser->request($request); if ($response->code == 201) { } # location header has the URL to the newly created resource return $response->header('location'); die "Error while calling HTTP_POST" REST web services responses are typically ATOM feeds which are XML. An easy way to get certain information from XML is to use an XPath expression to query information. To download the XPath module to your PERL environment, enter the following call from your shell command line: cpan XML::XPath The call downloads the required module. You can start using the following module in your script: use XML::XPath; # XPath to parse XML (Atom) outputs use XML::XPath::XMLParser; Chapter 4: Calling CA SOI REST Web Services from Perl Scripts 41

42 Available CA SOI REST Web Services Example The following ATOM feed shows an example of a response from the REST interface. <?xml version="1.0" encoding="utf-8"?> <feed xmlns=" <title>users</title> <link rel="next-page" type="application/atom+xml" href=" title="next-page" /> <author> <name>ca SOI</name> </author> <id> <updated> t13:36:17z</updated> <restapi:totalcounthint xmlns:restapi=" <entry> <title>zaiwenuser</title> <link rel="entry" type="application/atom+xml" href=" title="entry" /> <id> <published> t13:36:17z</published> </entry> <entry> <title>zaiwen400</title> <link rel="entry" type="application/atom+xml" href=" title="entry" /> <id> <published> t13:36:17z</published> </entry> <entry> <title>zaiwen300</title> <link rel="entry" type="application/atom+xml" href=" title="entry" /> <id> <published> t13:36:17z</published> </entry> <entry> <title>zaiwen200</title> <link rel="entry" type="application/atom+xml" href=" title="entry" /> <id> <published> t13:36:17z</published> </entry> </feed> 42 Web Services Reference Guide

43 Available CA SOI REST Web Services If you want to return only one value in your XPath query, for example, to get a link to the next page, you can use XPath::findvalue() method which returns the one element. Example The following code snippet shows how to get the next page URL from the ATOM feed. my $xp = XML::XPath->new($response->content); my $next_page_url = $xp->findvalue('/feed/link[@rel=\'next-page\']/@href')->value(); In case your XPath returns list of values, use XPath::findnodes() method. Example This code snippet shows how to get all titles from the entries in the ATOM feed. my $xp = XML::XPath->new($response->content); = $xp->findnodes('/feed/entry/title'); foreach my $username (@usernames) { print $username->string_value; } Chapter 4: Calling CA SOI REST Web Services from Perl Scripts 43

44

45 Chapter 5: WS-MAN Web Services This section provides information about the WS-MAN web services that are available in CA SOI. Note: WS-MAN web services should be considered an obsolete API. Instead, we recommend using the REST (see page 13) API. This section contains the following topics: Introduction to WS-MAN Web Services (see page 45) USM Entity Web Services (see page 52) USM Binary Relationship Web Services (see page 57) Notification Web Services (see page 68) Queue Web Services (see page 74) Customer Web Services (see page 82) Alert Web Services (see page 85) Propagation Policy Web Services (see page 92) Escalation Policy Web Services (see page 100) Escalation Action Web Services (see page 109) Introduction to WS-MAN Web Services This section introduces the architecture of the CA SOI WS-MAN web services and the mechanisms used to interact with CA SOI data. Web Services Architecture CA SOI provides web services that comply with the WS-Management standard using a Wiseman implementation. The web services interface with the SA Manager to provide access to service, CI, alert, and other data. The web services use basic authentication to let clients access these resources through SOAP. Several Resource URIs are available through which the web services access the requested data. Chapter 5: WS-MAN Web Services 45

46 Introduction to WS-MAN Web Services The following diagram illustrates how the web service obtains data when it receives a request: The WSManServlet intercepts client SOAP requests directed at the endpoint URL and dispatches them to the appropriate Resource Handler instance identified by the ResourceURI contained in the EPR element of the SOAP message. Wiseman automatically identifies the appropriate Resource Handler class in the following format: Resource_Handler.java. Resources and Operations The Endpoint Reference transport address for all CA SOI WS-Management web services is as follows: samanager port Defines the name of the server that contains the SA Manager. Defines the SA Manager Tomcat port, which is 7090 by default. 46 Web Services Reference Guide