SA Platform API design

The Platform API is defined by Java interfaces and organized into Java packages. To support a variety of client languages and remote access protocols, the API follows a function-oriented, call-by-value model.

• Services
• Objects in the API
• Exceptions
• Event Cache
• Searches
• Security
• API Documentation and the Twister
• Constant field values

Services

In the Platform API, a service encapsulates a set of related functions. Each service is specified by a Java interface with a name ending in Service, such as ServerService, FolderService, and JobService.

Services are the entry points into the API. To access the API, clients invoke the methods defined by the server interface. For example, to retrieve a list of software installed on a managed server, a client invokes the getInstalledSoftware method of the ServerService interface. Examples of other ServerService methods are checkDuplex, setPrimaryInterface, and changeCustomer.

The SA Platform API contains over 70 services – too many to describe here. The following table lists a few of the services that you may want to try out first. For a full list of services, in a browser go to the URL shown in API Documentation and the Twister.

Partial list of services of the SA API

Service name	Some of the operations provided by this service
AuditTaskService	Create, get, and run audit tasks.
ConfigurationService	Create application configurations, get the software policies using an application configuration.
DeviceGroupService	Create device groups, assign devices to groups, get members of groups, set dynamic rules.
EventCacheService	Trigger actions such as updating a client-side cache of value objects. See Event Cache.
FolderService	Create folders, get children of folders, set customers of folders, move folders.
JobService	Get progress and results of jobs, cancel jobs, update job schedules.
NasConnectionService	Get host names of NA servers, run commands on NA servers.
NetworkDeviceService	Get information such as families, names, models, and types, according to specified search filters.
ServerService	Get information about servers, reconcile (remediate) policies on servers (install software), get and set custom fields and attributes.
SoftwarePolicyService	Create software policies, assign policies to servers, get contents of policies, remediate (reconcile) policies with servers.
SolPatchService	Install and uninstall Solaris patches, add policy overrides.
VirtualColumnService	Manage custom fields and custom attributes.
WindowsPatchService	Install and uninstall Windows patches, add policy overrides.

Objects in the API

Although the SA Platform API is function-oriented, its design enables clients to create object-oriented libraries. TheSA data model includes objects such as servers, folders, and customers. These are persistent objects; that is, they are stored in the Model Repository. In the API, these objects have the following items:

• A service that defines the object’s behavior. For example, the methods of the ServerService specify the behavior of a managed server object.
• An object (identity) reference that represents an instance of a persistent object. For example, ServerRef is a reference that uniquely identifies a managed server. In the ServerService, the first parameter of most methods is ServerRef, which identifies the managed server operated on by the method. The Id attribute of a ServerRef is the primary key of the server object stored in the Model Repository.
• One or more value objects (VOs) that represent the data members (attributes, fields) of a persistent object. For example, ServerVO contains attributes such as agentVersion and loopbackIP. The attributes of ServerHardwareVO include manufacturer, model, and assetTag. Most attributes cannot be changed by client applications. If an attribute can be changed, then the API documentation for the setter method includes “Field can be set by clients.”

For performance reasons, update operations on persistent objects are coarse-grained. The update method of ServerService, for example, accepts the entire ServerVO as an argument, not individual attributes.

Exceptions

All of the API exceptions that are specific to SA are derived from one of the following exceptions:

OpswareException - Thrown when an application-level error occurs, such as when an end-user enters an illegal value that is passed along to a method. Typically, the client application can recover from this type of exception. Examples of exceptions derived from OpswareException are NotFoundException, NotInFolderException, and JobNotScheduledException.

OpswareSystemException - Thrown when an error occurs within SA. Usually, the SA Administrator must resolve the problem before the client application can run.

The following exceptions are related to security:

AuthenticationException - Thrown when an invalid SA user name or password is specified.

AuthorizationException - Thrown when the user does not have permission to perform an operation or access an object. For more information on permissions, see the SA Administer section.

Event Cache

Some client applications need to keep local copies of SA objects. Accessed by clients through the EventCacheService, the cache contains events that describe the most recent change made to SA objects. Clients can periodically poll the cache to check whether objects have been created, updated, or deleted. The cache maintains events over a configured sliding window of time. By default, events for the most recent two hours are maintained. To change the sliding window size, edit the Web Services Data Access Engine configuration file, as described in the Server Automation Administer section on the HPE SSO portal.

Searches

The search mechanism of the SA Platform API retrieves object references according to the attributes (fields) of value objects. For example, the getServerRefs method searches by attributes of the ServerVO value object. The getServerRefs method has the following signature:

public ServerRef[] getServerRefs(Filter filter)...

Each get*Refs method accepts the filter parameter, an object that specifies the search criteria. A filter parameter with a simple expression has the following syntax:

value-object.attribute   operator   value

(This syntax is simplified. For the full definition, see Filter grammar.)

The following examples are filter parameters for the getServerRefs method:

ServerVO.hostName = "d04.example.com"
ServerVO.model BEGINS_WITH "POWER"
ServerVO.use IN "UNKNOWN" "PRODUCTION"

Complex expressions are allowed, for example:

(ServerVO.model BEGINS_WITH "POWER") AND (ServerVO.use = "UNKNOWN")

Not every attribute of a value object can be specified in a filter parameter. For example, ServerVO.state is allowed in a filter parameter, but ServerVO.OsFlavor is not. To find out which attributes are allowed, locate the value object in the API documentation and look for the comment, “Field can be used in a filter query.”

Security

Users of the SA Platform must be authenticated and authorized to invoke methods on the SA Automation Platform API. To connect to SA, a client supplies an SA user name and password (authentication). To invoke methods, the SA user must belong to a user group with the necessary permissions (authorization). These permissions restrict not only the types of operations that users can perform, but also limit access to the servers and network devices used in the operations.

Before application clients can run on the platform, the SA Administrator must specify the required users and permissions with the Command Center. For instructions, see the "User Group and Setup" section in the SA Administer section. For information about security-related exceptions, see Exceptions.

Communication between clients and SA is encrypted. For Web Services clients, the request and response SOAP messages (which implement the operation calls) are encrypted using SSL over HTTP (HTTPS).

API Documentation and the Twister

SA includes API documentation (Javadocs) that describe the SA Platform API. To access the API documentation, specify the following URL in a browser:

https://<SA_core_host>/twister

The <SA_core_host> is the IP address or host name of the SA core server running the Command Center component.

The Twister is a program that lets you invoke API methods, one at a time, from within a browser. For example, to invoke the ServerService.getServerVO method, perform the following steps:

1. Open the API documentation in a browser.
2. In the All Classes pane, select com.opsware.server.
3. In the com.opsware.server pane, select ServerService.
4. In the main pane, scroll down to the getServerVO method.
5. Click Try It for the getServerVO method.
6. Enter your SA user name and password.
7. In the Twister pane for ServerService.getServerVO, enter the ID of a managed server in the oid field.
8. Click Go. The Twister pane displays the attributes of the ServerVO object returned.

Constant field values

Some of the API’s value objects (VOs) have fields with values defined as constants. For example, JobInfoVO has a status field that can have a value defined by constants such as STATUS_ACTIVE, STATUS_PENDING, and so forth. The API specifies constants as Java static final fields, but the WSDLs generated from the API do not define the constants. To view the definitions for constants, in the API documentation, go to the Constant Field Values page:

https://<SA_core_host>/twister/docs/constant-values.html

For example, the Constant Field Values page defines STATUS_ACTIVE as the integer 1.