Develop

NNMi offers many WS-I-compliant web services for reading, and updating the NNMi topology as well as related services for SNMP operations, reading/updating configuration and receiving a variety of notifications.

WS-Eventing is supported by NNMi to allow client web-services to subscribe to incident events from NNMi. By subscribing to the NNMi notification service, your client receives Incidents as they are added to the NNMi Event pipeline. In addition, any time an Incident’s lifecycleState or rcaState changes, you can receive an update indicating the change.

This section assumes that the you have some basic understanding of web services concepts and Java programming, although Java is not a required platform for interoperating with NNMi’s web services. For more details on web services, see the references listed at the end of this section.

See the nms-sdk-samples folder of your installation for examples. These samples demonstrate how to access each of the available web services. Additionally, there are sample Java classes available (see nms-sdk-sources.jar) to allow you to quickly build the sample projects provided. Note, however, that these Java classes are simply examples and not directly required by a web service client. Instead, these classes (if used in a Java client) are automatically generated from the service WSDL by a third-party web service client generation tool (for example, Axis or Sun’s Java Web Service Developer Pack).

The NNMi Web Service APIs support basic authentication and require credentials to be passed that match a permitted NNMi user role. Allowed roles include Web Services Client, Admin, or System. Use the Configuration: Users Accounts and Role workspace to create a user account with one of these roles.

Each of the client samples provided defaults to pass the following user name and password: webservices/nnm. This can be overridden at run time.

WS-I APIs

The interface specification for each of the NNMi web-service APIs is governed by the service WSDL that might be found at the URL described in the table below for the <serviceType> of interest. For each service, see the corresponding description in the tables found in Object Attributes section of this document for details about attributes returned or expected on input. Each of these services also allows for filtered reading of objects from NNMi’s data store. See the section on WS-I Filter Definition later in this document for more details.

URL Access to NNMi’s WS-I Supported Services

URL for NNMi WS-I Services	<serviceType>
http://<host>:<port>/<service>BeanService/<service>Bean?wsdl	Incident IncidentConfiguration Node Interface IPAddress IPSubnet
http://<host>:<port>/NmsSdkService/<service>Bean?wsdl	Card Port Security WsRegistry

In this instance:

• <host> is the NNMi management server
• <port> is the port that is configured to work with NNMi
• <service> is one of the supported NNMi services in the table above

For example, the WSDL for the Node service can be viewed on a system where NNMi is installed (and configured with port 80) by pointing a browser to the following URL: http://localhost/NodeBeanService/NodeBean?wsdl

Service Fault Handling

Many NNMi services will return an appropriate service fault for unrecoverable errors or invalid client input. When a fault is returned from an NNMi service, the request transaction is canceled and no updates or return data should be expected. The fault type will depend on the service request (Nms<serviceType>Fault, for example). Below is a list of some common general purpose fault messages shared by multiple services. For service-specific faults, see the service descriptions that follow. Additional troubleshooting information might also be found in the nnm-trace log at the time of the client request.

Common Service Faults

Service Fault Message	Description
Cannot interrogate model: <exception>	An unrecoverable error has occurred while performing a query within the NNMi persistence layer. The corresponding exception accompanies the fault.
Cannot invoke service: <exception>	The internal NNMi support service implementation has thrown an unrecoverable exception. The corresponding exception accompanies the fault.
Internal server error locating service implementation	The internal NNMi support service or bean is unavailable or unresponsive.
Unable to locate <object>	Indicates that the object input identifier is either invalid OR the object has been removed (possibly by user activity).
Unable to <perform requested activity>	Indicates that the service was unable to perform the requested operation. An example is “Unable to delete incident: <id>”. This is most likely due to invalid input or possibly internal error. Where possible, the service will return a more specific fault (e.g., “Unable to locate incident: <id>”) if the failure was due to invalid input. Again, the underlying cause of invalid identifier input may be due to user or other processes having removed the desired object.

Incidents

The Incident service permits a client to read, update, and create Incident objects in the NNMi data store.

• Incident[] getIncidents (Filter filter): Returns the count of objects that would be returned by getIncidents() using the same input filter.

  The filter must include a constraint with includeCias with a value of true in order to include incident Cias in the result. By default, incidents do not include Cias.

• Incident[] getChildIncidents (String id): Returns a complete list of correlated incidents for a given parent incident (corresponding to <id>) if there are any correlated children. Also see getChildCorrelations.

• addIncident (IncidentMgmtEvent): This operation is asynchronous and only submits the supplied IncidentMgmtEvent to the Events subsystem pipeline for processing. There is no guarantee that the event will be persisted for later retrieval. For example, an incident may not be persisted if the indicated source node cannot be resolved.

  Incidents added by addIncident are also not automatically forwarded to a global manager. An incident added to an NNMi regional manager must also be added to the global manager using addIncident on the global manager if that is the desired behavior.

• deleteIncident (String id)
• deleteIncidentByUuid (String uuid)
• updateNotes (String id, String notes): The supplied ‘notes’ value will completely replace the current object’s notes attribute value.
• updateLifecycleState (String id, String lifecycleState)
• updatePriority (String id, String priority)
• updateCias (String id, Cia[]): The supplied array of Cias will completely replace the current incident’s set of Cia values. To augment this list, read the current incident Cias using getIncidents prior to calling updateCias.
• IncidentCorrelation[] getChildCorrelations (String id): Returns a complete list of child correlations, if any, grouped by their correlation type. Also see getChildIncidents.
• String[] getAssignToPrincipals(): Returns a list of principals that might be assigned to any given incident. See updateAssignedTo.
• void updateAssignedTo (String id, String assignTo): Assigns an incident to a principal. See getAssignToPrincipals.

Cia object:

String name;

String type;

valid values for ‘type’ include:

{“INTEGER”, “STRING”, “BOOLEAN”, “DOUBLE”, “UNKNOWN”}

String value;

IncidentCorrelation object:

String name;

CorrelationType type;

Valid values for type include:

{ “APA”, “IMPACT”, “DEDUP”, “RATE”, “PAIRWISE”, “CUSTOM” }

String parent;

Date originOccurrenceTime;

12

int correlationResent;

String[] children;

Injection of Management Events

NNMi offers a web service endpoint that permits injection of management events into the NNMi event pipeline. Any management event that is configured with NNMi’s Incident Configuration (see console’s Configuration workspace) can be injected with the addIncident port on the Incident Service API shown above.

Incident Service Faults

Service Operation	Fault Message
getIncidents	Unable to retrieve incident CIAs: <id>
addIncidents	Invalid nature: <nature> Invalid priority: <priority> Cannot inject incident: <name>
updateLifecycleState	The internal NNMi support service or bean is unavailable or unresponsive.
updateLifecycleState	Unable to update incident lifecycleState: <id>
updatePriority	Unable to update incident priority: <id>
updateAssignedTo	Invalid AssignTo principal: <principal>
getAssignToPrincipals	Unable to identify assignTo principals
updateNotes	Unable to update incident notes: <id>
deleteIncident	Unable to locate incident: <id> Unable to delete incident: <id>
deleteIncidentByUuid	Unable to locate incident: <uuid> Unable to delete incident: <uuid>
getChildIncidents	Unable to retrieve child incidents
getChildCorrelations	Unable to retrieve child correlations
updateCias	Unable to update Cias: <id>

Incident Configuration

The Incident Configuration service permits a client to read Incident Configurations in the NNMi data store. In this version, the input Filter objects are ignored and each operation returns the full set of configurations for the type specified. The attributes of each configuration object correspond to the values shown in the NNMi console.

• RemoteNNMEventConfig[] getRemoteEventConfig(Filter filter)
• ManagementEventConfig[] getManagementEventConfig(Filter filter)
• SnmpTrapConfig[] getSnmpTrapConfig(Filter filter)
• PairwiseConfig[] getPairwiseConfig(Filter filter)

RemoteNNMEventConfig object:

String id;

String name;

String incidentConfigType;

String enable;

String description;

String messageFormat;

String category;

String author;

String severity;

String family;

DedupConfig dedupConfig;

RateConfig rateConfig;

ActionConfig actionConfig;

String oId;

ManagementEventConfig object:

String id;

String name;

String incidentConfigType;

String enable;

String description;

String messageFormat;

String category;

String author;

String severity;

String family;

DedupConfig dedupConfig;

RateConfig rateConfig;

ActionConfig actionConfig;

SnmpTrapConfig object:

String id;

String name;

String incidentConfigType;

String enable;

String description;

String messageFormat;

String category;

String author;

String severity;

String family;

DedupConfig dedupConfig;

RateConfig rateConfig;

ActionConfig actionConfig;

String oId;

PairwiseConfig object:

String id;

String name;

String incidentConfigType;

String enable;

String firstIncidentName;

String secondIncidentName;

PairItem[] pairItems;

DedupConfig object:

String enable;

String comparisonCriteria;

String correlationIncidentConfigName;

ComparisonParam[] comparisonParams;

ComparisonParam object:

String paramType;

String paramValue;

RateConfig object:

String enable;

int rateCount;

int hourInterval;

int minuteInterval;

int secondInterval;

String comparisonCriteria;

String correlationIncidentConfigName;

ComparisonParam[] comparisonParams;

ActionConfig

String enable;

LifecycleTransitionAction[] actions;

LifecycleTransitionAction

String commandType;

String command;

String lifeCycleState;

PairItem object;

String firstInPair;

String secondInPair;

Nodes

The Node service permits a client to read, update, and delete Nodes from the NNMi data store.

Node[] getNodes (Filter filter)

The filter must include a Constraint having includeCustomAttributes with a value of true in order to include node CustomAttributes and capabilities in the result. By default, the nodes do not include CustomAttributes and capabilities.

• Integer getNodeCount (Filter filter): Returns the count of objects that would be returned by getNodes() using the same input filter.
• NodeConclusion[] getConclusions (String id)

• addConclusion (String iD, String incidentId, Status status, String conclusion, String[] cancelledConclusions)

  • Can be used to influence ‘status’ on a node. Status will be recalculated (with the most severe being set on the node).
  • Conclusion strings can be any user meaningful description. As such, it is a recommended best practice to always prefix a conclusion string with either a namespace or a category to avoid collisions with other clients that might also be adding conclusion strings. For example, com.my_agent.ServiceUnavailable or OracleMonitorX_ServiceUnavailable are preferred to simply ServiceUnavailable.
  • The incidentId is optional (may be empty string) but if the conclusion is associated with an incidentId and another conclusion is later added that cancels the previous conclusion, the associated Incident will be closed. If it is not desired to associate a conclusion to an incident, provide an empty string (“”);
  • ‘cancelledConclusions’ are an optional list of conclusions that the added conclusion will cause to be canceled. If not used and no conclusions are intended to be canceled, pass an empty list.

  • It is strongly suggested that SDK clients do not add or cancel NNMi-defined conclusions.

    Conclusions might be deleted by supplying a blank ‘conclusion’ value along with the list of conclusions to be deleted as ‘cancelledConclusions’.

  • updateManagementMode(String id, String managementMode)
  • updateNotes(String id, String notes)
  • addSeeds(String[] hostnamesOrIPs)
  • addSeedsForTenant(String[] hostnamesOrIPs, String tenantName, String notes)
  • addHints(String[] hostnamesOrIPs)
  • removeSeeds(String[] hostnamesOrIPs)
  • rediscoverHosts(String[] hostnamesOrIPs)
  • addHints(String[] hostnamesOrIPs)
  • pollHosts(String[] hostnamesOrIPs)
  • addCapabilities(String id, Capability[] capabilities)

  • String[] addCapabilitiesBulk(String[] ids, Capability[] capabilities)

    Returns list of node IDs not successfully added.

  • removeCapabilities (String id, String[] capabilityKeys): The list of capabilityKeys is expected to correspond to the ‘key’ attribute of the desired Capabilities to remove.
  • String[] removeCapabilitiesBulk (String[] ids, String[] capabilityKeys): Returns list of node IDs not successfully removed.
  • updateCustomAttributes (String id, CustomAttribute[] customAttributes)
  • addCustomAttributes (String id, CustomAttribute[] customAttributes)
  • String[] addCustomAttributesBulk (String[] ids, CustomAttribute[] customAttributes)

  • removeCustomAttributes (String id,String[] customAttributes)

  • String[] removeCustomAttributesBulk (String[] nodeIds,String[] customAttributes): Returns list of node IDs not successfully removed.

  NodeConclusion object:

  String uuid;

  String status;

  String conclusion;

  Date timestamp;

  Capability object:

  String key;

  String label;

  CustomAttribute object:

  String name;

  String value;

Node Service Faults

Service Operation	Fault Message
updateManagementMode	Unable to update management mode: <id>
updateNotes	Unable to update notes: <id>
deleteNode	Unable to delete node: <id>
deleteNodeByUuid	Unable to delete node: <id>
addCapabilities	Unable to add capabilities: <id>
addCustomAttributes	Unable to add custom attributes: <id>
removeCustomAttributes	Unable to remove custom attributes: <id>
updateCustomAttributes	Unable to update custom attributes: <id>
addConclusion	Invalid incident id: <id> Unable to add conclusions: <id>
getNnmSystemName	Node not found: <id>
isLocal	Node not found: <id>
getForwardableNodes	Empty node list supplied

Interface

The Interface service permits a client to read and update existing Interface objects in the NNMi data store.

Interface[] getInterfaces (Filter filter): The filter must include a Constraint having includeCustomAttributes with a value of true in order to include interface CustomAttributes and Capabilities in the result. By default, the interfaces do not include CustomAttributes and Capabilities.

• Integer getInterfaceCount (Filter filter): Returns the count of objects that would be returned by getInterfaces() using the same input filter.
• InterfaceConclusion[] getConclusions (String id)
• updateManagementMode (String id, String managementMode)
• updateNotes (String id, String notes)
• addCapabilities (String id, Capability[] capabilities)
• String[] addCapabilitiesBulk (String[] ids,Capability[] capabilities): Returns list of interface IDs that were not successfully added.
• removeCapabilities (String id, String[] capabilityKeys): The list of capabilityKeys is expected to correspond to the ‘key’ attribute of the desired Capabilities to remove.
• String[] removeCapabilitiesBulk (String[] ids,String[] capabilityKeys): Returns list of interface IDs that were not successfully removed.
• updateCustomAttributes (String id, CustomAttribute[] customAttributes)
• addCustomAttributes(String id, CustomAttribute[] customAttributes)
• String[] addCustomAttributesBulk(String[] ifaceIds,CustomAttribute[] customAttributes): Returns list of interface IDs that were not successfully added.
• removeCustomAttributes(String id,String[] customAttributes)
• String[] removeCustomAttributesBulk(String[] ifaceIds,String[] customAttributes): Returns list of interface IDs that were not successfully removed
• Long[] getInputSpeedBulk(String[] ifaceIds)
• Long[] getOutputSpeedBulk(String[] ifaceIds): Integer addBulkCustomAttributes(String caName, String[] ids, String[] caValues): ‘caName’ is a single custom attribute name to be added or updated for each of the interfaces specified by ‘ifaceIds;' ‘caValues’ is an array of values that will be added or updated for the ‘caName’ custom attribute of each of the interfaces of the corresponding ‘ifaceIds’ array.

InterfaceConclusion object:

String uuid;

String status;

String conclusion;

Date timestamp;

Capability object:

String key;

String label;

CustomAttribute object:

String name;

String value;

Interface Service Faults

Service Operation	Fault Message
updateManagementMode	Unable to update management mode: <id>
updateNotes	Unable to update notes: <id>
addCapabilities	Unable to add capabilities: <id>
removeCapabilities	Unable to remove capabilities: <id>
addCustomAttributes	Unable to add custom attributes: <id>
removeCustomAttributes	Unable to remove custom attributes: <id>
updateCustomAttributes	Unable to update custom attributes: <id>

IPAddress

The IP Address service permits a client to read and update existing IPAddress objects in the NNMi data store. The IPAddress object is IP-version neutral, supporting either IPv4 or IPv6 addresses. Though the tenant is not returned as part of the IPAddress object for backwards compatibility reasons, 'tenant' and 'mappedAddress' will be supported as attributes that might be used in the getIPAddresses(Filter filter) operation. When used as conditions in filters, these values are expected to correspond to the tenant name and mapped IP address value as would be returned by the getTenantsByUuids() and getMappedAddressesByUuids() operations respectively.

• IPAddress[] getIPAddresses(Filter filter)

• IPAddressConclusion[] getConclusions(String id)

• updateManagementMode(String id, String managementMode)

• updateNotes(String id, String notes)

• addCapabilities(String id, Capability[] capabilities)

• String[] getTenantsByUuids(String[] uuids)

• String[] getMappedAddressesByUuids(String[] uuids)

IPAddressConclusion object:

String uuid;

String status;

String conclusion;

Date timestamp;

IPAddress Service Faults

Service Operation	Fault Message
getConclusions	Address id not found: <id> Unable to retrieve conclusions: <id>
updateManagementMode	Unable to update management mode: <id>
updateNotes	Unable to update notes: <id>
addCapabilities	Unable to add capabilities: <id>
removeCapabilities	Unable to remove capabilities: <id>
getTenantsByUuids	Empty address list supplied
getMappedAddressesByUuids	Empty address list supplied

IPSubnet

The IPSubnet service permits a client to read and update existing IPSubnet objects in the NNMi data store. The IPSubnet object is IP-version neutral, supporting either IPv4 or IPv6 subnets. Although the tenant is not returned as part of the IPSubnet object for backwards compatibility reasons, 'tenant' will be supported as a filterable attribute in the getIPSubnets(Filter filter) operation. When used in a filter condition, this value is expected to correspond to the tenant name as would be returned by the getTenantsByUuids().

• IPSubnet[] getIPSubnets(Filter filter)

• updateNotes(String id, String notes)

• String[] getTenantsByUuids(String [] uuids)

IPSubnet Service Faults

Service Operation	Fault Message
updateNotes get	Unable to update notes: <id>
TenantsByUuids	Empty subnet list supplied

API Reference

Incident

http://localhost/IncidentBeanService/IncidentBean?wsdl

• Incident[] getIncidents(Filter filter)
• Integer getIncidentCount(Filter filter)
• Incident[] getChildIncidents(String id)
• addIncident(IncidentMgmtEvent)
• deleteIncident(String id)
• deleteIncidentByUuid(String uuid)
• updateNotes(String id, String notes)
• updateLifecycleState(String id, String lifecycleState)
• updatePriority(String id, String priority)
• updateCias(String id, Cia[])
• IncidentCorrelation[] getChildCorrelations(String id)
• String[] getAssignToPrincipals()
• void updateAssignedTo(String id,String assignTo)

IncidentConfiguration

• http://localhost/IncidentConfigurationBeanService/IncidentConfigurationBean?wsdl
• RemoteNMEventConfig[] getRemoteEventConfig(Filter filter)
• ManagementEventConfig[] getManagementEventConfig(Filter filter)
• SnmpTrapConfig[] getSnmpTrapConfig(Filter filter)
• PairwiseConfig[] getPairwiseConfig(Filter filter)

Node

http://localhost/NodeBeanService/NodeBean?wsdl

• Node[] getNodes(Filter filter)
• Integer getNodeCount(Filter filter)
• NodeConclusion[] getConclusions(String id)
• addConclusion(String id, String incidentId, Status status, String conclusion, String[] cancelledConclusions)
• updateManagementMode(String id, String managementMode)
• updateNotes(String id, String notes)
• addSeeds(String[] hostnamesOrIPs)
• addSeedsForTenant(String[] hostnamesOrIPs, String tenantName, String notes)
• removeSeeds(String[] hostnamesOrIPs)
• addHints(String[] hostnamesOrIPs)
• rediscoverHosts(String[] hostnamesOrIPs)
• pollHosts(String[] hostnamesOrIPs)
• addCapabilities(String id, Capability[] capabilities)
• String[] addCapabilitiesBulk(String[] ids, Capability[] capabilities)
• removeCapabilities(String id, String[] capabilityKeys)
• String[] removeCapabilitiesBulk(String[] ids, String[] capabilityKeys)
• updateCustomAttributes(String id, CustomAttribute[] customAttributes)
• addCustomAttributes(String id, CustomAttribute[] customAttributes)
• String[] addCustomAttributesBulk(String[] ids, CustomAttribute[] customAttributes)
• removeCustomAttributes(String id,String[] customAttributes)
• String[] removeCustomAttributesBulk(String[] ids, String[] customAttributes)
• boolean deleteNode(String id)
• boolean deleteNodeByUuid(String uuid)
• getNnmSystemName(final String id)
• boolean isLocal(final String id)
• boolean isForwardable(final String id)
• String[] getForwardableNodes(final String[] ids)

Interface

http://localhost/InterfaceBeanService/InterfaceBean?wsdl

• Interface[] getInterfaces(Filter filter)
• Integer getInterfaceCount(Filter filter)
• InterfaceConclusion[] getConclusions(String id)
• updateManagementMode(String id, String managementMode)
• updateNotes(String id, String notes)
• addCapabilities(String id, Capability[] capabilities)
• String[] addCapabilitiesBulk(String[] ids,Capability[] capabilities)
• removeCapabilities(String id, String[] capabilityKeys)
• String[] removeCapabilitiesBulk(String[] ids,String[] capabilityKeys)
• updateCustomAttributes(String id, CustomAttribute[] customAttributes)
• addCustomAttributes(String id, CustomAttribute[] customAttributes)
• String[] addCustomAttributesBulk(String[] ids,CustomAttribute[] customAttributes)
• Integer addBulkCustomAttributes(String caName, String[] ids, String[] caValues)
• removeCustomAttributes(String id,String[] customAttributes)
• String[] removeCustomAttributesBulk(String[] ifaceIds,String[] customAttributes)
• Long[] getInputSpeedBulk(String[] ifaceIds)
• Long[] getOutputSpeedBulk(String[] ifaceIds)

IPAddress

http://localhost/IPAddressBeanService/IPAddressBean?wsdl

• IPAddress[] getIPAddresses(Filter filter)
• IPAddressConclusion[] getConclusions(String id)
• updateManagementMode(String id, String managementMode)
• updateNotes(String id, String notes)
• addCapabilities(String id, Capability[] capabilities)
• String[] getTenantsByUuids(String[] uuids)
• String[] getMappedAddressesByUuids(String[] uuids)

IPSubnet

http://localhost/IPSubnetBeanService/IPSubnetBean?wsdl

• IPSubnet[] getIPSubnets(Filter filter)
• updateNotes(String id, String notes)
• String[] getTenantsByUuids(String[] uuids)