Searching the Help
To search for information in the Help, type a word or phrase in the Search box. When you enter a group of words, OR is inferred. You can use Boolean operators to refine your search.
Results returned are case insensitive. However, results ranking takes case into account and assigns higher scores to case matches. Therefore, a search for "cats" followed by a search for "Cats" would return the same number of Help topics, but the order in which the topics are listed would be different.
Search for | Example | Results |
---|---|---|
A single word | cat
|
Topics that contain the word "cat". You will also find its grammatical variations, such as "cats". |
A phrase. You can specify that the search results contain a specific phrase. |
"cat food" (quotation marks) |
Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase. |
Search for | Operator | Example |
---|---|---|
Two or more words in the same topic |
|
|
Either word in a topic |
|
|
Topics that do not contain a specific word or phrase |
|
|
Topics that contain one string and do not contain another | ^ (caret) |
cat ^ mouse
|
A combination of search types | ( ) parentheses |
|
- Web Service Interfaces
- Reference information for all web services
- Action Web Service Interface
- Downtime Web Service Interface
- Event Synchronization Web Service Interface
- Event Web Service Interface
- Monitoring Automation Web Service Interface
- Status Web Service Interface
- Tool Execution Web Service Interface
- User Management Web Services Interface
Reference information for all web services
This section describes what to consider when using any of the available web service interfaces.
Consider the following with regard to authentication and security when using web services:
-
Web services can only be executed by regular OMi users.
-
User rights assumed when executing a web service request are identical to the user rights you would have when performing the same operation using the OMi user interface, being logged in as the user whose credentials are used for web service authentication.
-
Network encryption and data integrity is supported only when using the HTTPS protocol.
The following code sample shows a JAVA implementation of basic authentication using a username/password combination:
Example:
import org.apache.commons.codec.binary.Base64; import javax.ws.rs.core.Response; import javax.ws.rs.core.MediaType;
/** Create the request URL (assuming the capitalized variables are set to appropriate values). **/ String url = "http://" + WS_SERVER_HOSTNAME + ROOT_PATH + REQUEST;
byte[] encodedUserPassword = Base64.encodeBase64((username + ":" + password).getBytes());
Response response = client.target(url).request(MediaType.APPLICATION_XML_TYPE). header("Authorization", "Basic " + new String(encodedUserPassword)).get();
The following types of authentication are also supported:
- Manual entry of user name and password combination valid for logging on to OMi. This method is useful for ad-hoc access to the web service, for example when using a plug-in such as Poster.
- Light-Weight Single Sign-on (LWSSO)
- Windows Authentication (WinAuth)
- Common Access Card (CAC)
If you implement a web service endpoint that can be directly called by OMi, error handling is as follows:
-
HTTP status of
2xx
returned. The following HTTP status codes indicate a request was processed successfully:-
200
(OK) -
201
(Created) -
202
(Accepted)
-
-
HTTP status of
3xx
returned. These are redirection status. Redirection is not supported by the service. They are treated the same as4xx
, therefore the request will be marked asFAILED
and no further retries are done. -
HTTP status of
4xx
returned. Any status of4xx
is considered an error in the client request, therefore the request will be marked as FAILED and no further retries are done. -
HTTP status of
5xx
returned. Any status of5xx
is considered an error on the server. In this case it is expected that the server will recover at some future time and be able to accept the request. The request will be put back in the queue. Retries are done once a minute until the request succeeds or the request times out (default is 12 hours and may be changed in the Infrastructure Settings). New events and updates are forwarded in the order the forward request was received. Should a request fail due to a5xx
error it will block all other requests for this server. All new events in the queue are delivered before delivering any outstanding updates. -
Any type of
IOException
encountered while trying to communicate with the server will result in the request being re-queued and then retried as described for HTTP status of5xx
.
Web Services return error codes that help administrators identify the cause of possible problems. Administrators can control the types of error codes returned from the Web Service by changing the level of verbosity in the Infrastructure Settings Manager. The following options are available:
Option | Description |
---|---|
Standard |
Default. Returns to the caller of the web service the appropriate HTTP error code, as listed in the HTTP 1.1 standard, along with a standard error text message describing the error. |
Verbose |
Recommended for development environments. Returns a detailed message describing the reason for the error. |
Brief |
Returns only error codes 400 (Bad Request) or 503 (Service Unavailable), depending on the type of the error, and an error identifier. A detailed error message may be obtained by locating the identifier and detailed error message in the error logs. |
-
Navigate to the in the Infrastructure Settings Manager:
Administration > Setup and Maintenance > Infrastructure Settings
Alternatively, click Infrastructure Settings.
-
Select application Operations Management and find the section Operations Management - Web Service Settings > Error Response Verbosity.
-
Optional. Change the default value Standard to another value.
-
Review the error log file on the OMi Gateway Server:
<OMi_HOME>/log/opr-ws-response.log
Web Service modify operations must be secured by setting the X-Secure-Modify-Token
HTTP header on modify requests (PUT, POST, and DELETE). This header provides enhanced security protection against malicious exploits of web applications.
Protection for modify operations is by default enabled in the Web Service Settings in the Infrastructure Settings Manager. You can disable the setting for backwards compatibility (see Disable Enhanced Security Protection).
Setting the X-Secure-Modify-Token HTTP Header
Web Service clients must first obtain the secureModifyToken
cookie, and then set the value of the cookie in the X-Secure-Modify-Token
HTTP header:
-
Obtain the
secureModifyToken
cookie before executing any modify requests (PUT, POST, or DELETE).The recommended approach to obtain the
secureModifyToken
cookie at client startup is to execute an HTTP GET request for the Web Service Service Document at/opr-web/rest
.After the HTTP GET operation has completed the cookie is set. During the life of the client and the single sign-on session, the value of the cookie may change. Before each modify operation the HTTP client should get the current value of the cookie from the client. It is not recommended to save this value in a local variable for later use, as it may change during the life of the HTTP client.
-
Set the
X-Secure-Modify-Token
HTTP header.The
X-Secure-Modify-Token HTTP
header must be set by all Web Service clients when executing modify operations (PUT, POST, or DELETE). The value to set this HTTP header to is specified in thesecureModifyToken
cookie.
Note The client must set all cookies returned by the server in subsequent requests. For example, LWSSO_COOKIE_KEY
and JSESSIONID
are additional cookies returned by the server and must be set in subsequent requests to the server. If a new session is established, the secureModifyToken
previously obtained through a GET request becomes invalid. Therefore the other cookies are also required.
Sample Code Using a Standard Java HTTP Client
The following sample code first gets the value of the secureModifyToken
cookie and then sets the X-Secure-Modify-Token
HTTP header.
The following method gets all the cookies from an initial GET request. The standard Java HTTP client does not automatically manage cookies for the user like the Apache HttpClient does. The cookies need to be obtained and managed separately.
private static List<HttpCookie> getCookies(final String path)
{
final URL url = new URL(path);
final HttpURLConnection connection = url.openConnection();
final List<HttpCookie> result = new ArrayList<HttpCookie>();
connection.setRequestMethod("GET");
// Set the username and password for the request
byte[] encodedUserPassword = Base64.encodeBase64((username + ":" + password).getBytes());
connection.setRequestProperty("Authorization", "Basic " + new String(encodedUserPassword));
connection.connect();
int response = connection.getResponseCode();
if (response == 200)
{
for (int i=1; (final String headerName = connection.getHeaderFieldKey(i)) != null; i++)
{
if (headerName.equals("Set-Cookie"))
{
final String cookieString = connection.getHeaderField(i);
final List<HttpCookie> cookies = HttpCookie.parse(cookieString);
if (cookies != null && !cookies.isEmpty())
result.addAll(cookies);
}
}
}
return result;
}
The following code adds the cookies to the POST request and the HTTP header X-Secure-Modify-Token
if the cookie secureModifyToken
exists.
final URL url
final List<HttpCookie> cookies = getCookies("http://" + localHostName + ":" + port + "/opr-web/rest");
final URL url = new URL("https://" + localHostName + ":" + port + "/opr-web/rest/9.10/event_list");
final HttpURLConnection connection = url.openConnection();
// Set the cookies and HTTP header for the request
for (HttpCookie cookie : cookies)
{
// add the cookies to the request
connection.addRequestProperty("Cookie", cookie.getName() + "=" + cookie.getValue());
if (cookie.getName().equalsIgnoreCase("secureModifyToken"))
{
// add the HTTP header
connection.setRequestProperty("X-Secure-Modify-Token", cookie.getValue());
}
}
...
Sample Code Using an Apache HttpClient
The following sample code first gets the value of the secureModifyToken
cookie and then sets the X-Secure-Modify-Token
HTTP header.
The following method may return null, in which case it should be assumed the target web service does not require the X-Secure-Modify-Token
HTTP header. (For example, OMi versions lower than 9.10 do not require this HTTP header.)
private static String getSecureModifyToken(final HttpClient client, final String url)
{
int rc = -1;
String secureModifyToken = null;
// get the service document from the base path
final HttpMethod getMethod = new GetMethod(url);
getMethod.setFollowRedirects(true);
getMethod.setDoAuthentication(true);
getMethod.setRequestHeader("Accept", "text/plain, text/xml, application/xml, application/atomsvc+xml");
getMethod.setRequestHeader("Accept-Language", System.getProperty("user.language", "en") + "-"
+ System.getProperty("user.country", "US"));
try
{
client.executeMethod(getMethod);
rc = getMethod.getStatusCode();
}
catch (IOException ioe)
{
// ignore any errors for backwards compatibility
}
if (rc == HttpStatus.SC_OK)
{
// look for the secureModifyToken
Cookie[] cookies = client.getState().getCookies();
if (cookies != null && cookies.length > 0)
{
for (Cookie cookie : cookies)
{
if (SECURE_MODIFY_TOKEN.equalsIgnoreCase(cookie.getName()))
secureModifyToken = cookie.getValue();
}
}
}
return secureModifyToken;
}
HttpClient client = new HttpClient();
client.getState().setCredentials(new AuthScope(hostname, port),
new UsernamePasswordCredentials(username, password));
final String secureModifyToken = getSecureModifyToken(client,
"https://" + localHostName + ":" + port + "/opr-web/rest");
String url = "https://" + localHostName + ":" + port + "/opr-web/rest/9.10/event_list";
PostMethod method = new PostMethod(url);
if (secureModifyToken != null)
method.setRequestHeader("X-Secure-Modify-Token", secureModifyToken);
...
Sample Code Using an Apache Wink REST Client
The following sample code first gets the value of the secureModifyToken
cookie and then sets the X-Secure-Modify-Token
HTTP header.
The following method gets all the cookies from an initial GET request. The Apache Wink REST Client does not automatically manage cookies for the user like the Apache HttpClient does. The cookies need to be obtained and managed separately.
private static Set<Cookie> getCookies(final String url, final RestClient client)
{
final Set<Cookie> cookies = new HashSet <Cookie>();
final Resource resource = client.resource(url);
// Set the username and password for the request
byte[] encodedUserPassword = Base64.encodeBase64((username + ":" + password).getBytes());
resource.header("Authorization", "Basic " + new String(encodedUserPassword));
final ClientResponse response = resource.get();
final MultivaluedMap<String, String> headers = response.getHeaders();
if (headers != null)
{
for (final Map.Entry<String, List<String>> header : headers.entrySet())
{
if ("Set-Cookie".equalsIgnoreCase(header.getKey()))
{
for (final String value : header.getValue())
{
if (value != null && value.length() > 0)
try
{
cookies.add(Cookie.valueOf(value));
}
catch (IllegalArgumentException e)
{
// ignore this entry
}
}
}
}
}
return cookies;
}
The following code adds the cookies to the REST resource and the HTTP header X-Secure-Modify-Token
if the cookie secureModifyToken
exists.
final RestClient client = new RestClient();
final Set<Cookie> cookies = getCookies("https://" + localHostName + ":" + port + "/opr-web/rest", client);
String url = "https://" + localHostName + ":" + port + "/opr-web/rest/9.10/event_list";
final Resource resource = client.resource(url);
// Set the username and password for the request
byte[] encodedUserPassword = Base64.encodeBase64((username + ":" + password).getBytes());
resource.header("Authorization", "Basic " + new String(encodedUserPassword));
// Set the cookies and HTTP header for the request
for (Cookie cookie : cookies)
{
// add the cookies to the resource
resource.cookie(cookie);
if (cookie.getName().equalsIgnoreCase("secureModifyToken"))
{
// add the HTTP header
resource.header("X-Secure-Modify-Token", cookie.getValue());
}
}
...
Disable Enhanced Security Protection
Web service clients that set the X-Secure-Modify-Token
HTTP header may fail when communicating with web services installed with the OMi version 9.0x and lower. You may therefore disable enhanced security protection in the Web Service Settings in the Infrastructure Settings Manager.
-
Navigate to the Infrastructure Settings Manager:
Administration > Setup and Maintenance > Infrastructure Settings
Alternatively, click Infrastructure Settings.
Edit Operations Management - Web Service Settings > Secure Modify.
-
Change the default value true to false.
-
Optional. Implement the following additional measures for end users to reduce their exposure to malicious attacks when using OMi:
-
Do not allow your web browser to save user names and passwords.
-
Do not use the same web browser to access OMi and the Internet at the same time (tabbed browsing). While logged in to OMi, the web browser should not be used to browse other web sites.
-
HTML-enabled applications that integrate web browsers (for example email or newsreader applications) pose additional risks because simply viewing an email message or a news message may lead to the execution of an attack. Caution should be taken when using client workstations connected to OMi and to such applications.
-
If the CA SiteMinder Web Agent is configured for CssChecking=YES
, characters configured in the CA SiteMinder Web Agent BadUrlChars
parameter are rejected by the CA SiteMinder Web Agent. By default the following characters are included in this list:
-
Single quotation mark (‘)
-
Greater than sign (>)
-
Less than sign (<)
Event Web Service clients must not use these characters in the query parameter section of the URL:
-
String literals: As the single quotation mark (') may be rejected in environments with CA SiteMinder, surround string literals with double quotation marks (""). See Value types for more information.
As CA SiteMinder blocks the % encoding, the string literal itself must escape the offending characters using the dollar sign ($) instead of percent (%), for example:
-
Replace single quotation marks (‘) with $60.
-
Replace greater than signs (>) with $3E.
-
Replace less than signs (<) with $3C
See URL escape codes for more information.
-
-
Operators: As the greater than sign (>) and less than sign (<) may be rejected by the CA SiteMinder agent, use the GT and LT aliases instead. See Operator aliases for more information.
By default, the timeout period of an OMi REST web service session is 30 seconds. You can change the default in the Infrastructure Settings Manager:
Administration > Setup and Maintenance > Infrastructure Settings
Alternatively, click Infrastructure Settings.
Select Operations Management from the Applications drop-down list. In the Web Service Settings table, edit the REST web service Session timeout setting.
Alternatively, add the sessionTimeOut
property to the HTTP request header, or add the query parameter sessionTimeOut
to the HTTP URL. The sessionTimeOut
parameter in the HTTP URL overrides the sessionTimeOut
property in the HTTP request header, and both override the default timeout set in the infrastructure setting.
The timeout period is set when the web service client logs onto OMi for the first time.
You can define a number of settings for web services in the Infrastructure Settings:
Administration > Setup and Maintenance > Infrastructure Settings
Alternatively, click Infrastructure Settings.
Select Operations Management - Web Service Settings.
Details about the effect of these settings are provided with each setting in the Infrastructure Settings Manager.
We welcome your comments!
To open the configured email client on this computer, open an email window.
Otherwise, copy the information below to a web mail client, and send this email to ovdoc-asm@hpe.com.
Help Topic ID:
Product:
Topic Title:
Feedback: