Skip Headers
Oracle® Communications Network Integrity Developer's Guide
Release 7.1

E23701-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

26 Web Service API

This chapter provides information about the Web Service API Oracle Communications Network Integrity.

Web Service Overview

The Network Integrity Web Services API enables Oracle Communications products and third party applications to interact with Network Integrity and reduces integration complexity by providing a standards-based interface. With the API, clients can externally manage Network Integrity through Web Services APIs.

At a high-level the web service supports:

  • Configuring all types of Scans

  • Running Discovery and Reconciliation Scans

  • Retrieving scan results including any found discrepancies

  • Initiating corrective actions such as reconciling discrepancies in Inventory systems.

Most all operations that can be done in the Web UI are possible using the Web Service API. One operation that is currently not possible is to create or update the Import System configured in the Web UI. This is a one-time setup that must be done in the Web UI and cannot be done using the Web Service API.

The Web Service API is standards based using JAX-WS over HTTP.

Security

The Network Integrity Web Service API uses the same security as the Network Integrity Web User Interface. So any user able to login into the web UI can also use the Web Service API. This is assigned using the NetworkIntegrityRole.

Model Based

The Network Integrity Web Service API operates on the Network Integrity Model. Knowledge of the entities, attributes and relationships in the Network Integrity model is essential for using the Web Service API.

For Network Integrity entity, attribute and relationship names, refer to Network Integrity Information Model Reference.

For cartridge entity, parameter, and relationship names and descriptions, refer to your cartridge documentation.

Concurrency With UI and other Web Service Clients

Web Service API operations take immediate effect in the system and therefore there is potential for collisions with users working in the Web UI. If the Web Service API operation collides with an update that another user has done in the Web UI or another Web Service client, then an error is returned to a client. For example, if a Web Service client deletes a DisConfig (Scan) while a user is editing the same scan in the Web UI, the Web UI user receives an error when that user attempt to save changes. If two clients (Web Service client or Web UI user) are trying to update/delete the same entity, the last client to commit changes receives the error.

All Operations

Table 26-1 describes the DisConfig operations. See Network Integrity Information Model Reference for further information on this entity.

Table 26-1 DisConfig Operations

Operation Description

createDisConfig

This operation creates a new Scan in the system (DisConfig is equivalent to Scan in the Network Integrity Web UI).

deleteDisConfig

This operation deletes a Scan from the system. All results and discrepancies produced by this scan are deleted as well. A Fault is returned if the delete fails.

This delete operation returns a Fault if the scan to be deleted has discrepancies in the Received or the Submitted state. Add <v1:forceDelete>YES</v1:forceDelete> to the delete request to force the scan to delete and bypass this particular Fault.

findDisConfig

This operation finds Scans in the system based on search criteria provided in the request. Full Scan data is returned but client applications can limit the amount of data returned, or support paging, by providing a fromRange and toRange in the request. A Fault with a faultstring is returned if the find fails.

getDisConfig

This operation gets the details about a Scan. It requires the DisConfig entity ID to be passed in the request, and returns the full details of the Scan including UI Parameters, Scope Addresses, and Schedule information in the response, if found. If not found, a Fault is the response.

updateDisConfig

This operation updates a Scan in the system. All the values for the Scan are required in the request, not just the values changing, therefore the client application should perform a 'get' operation and update the required values for the update operation. A Fault with a faultstring is returned if the update fails.


Table 26-2 describes the DisScanRun operations. See Network Integrity Information Model Reference for further information on this entity.

Table 26-2 DisScanRun Operations

Operation Description

findDisScanRun

This operation finds Scan Results in the system based on search criteria provided in the request (DisScanRun is equivalent to Scan Results in the Network Integrity Web UI). Full Scan Result data is returned but client applications can limit the amount of data returned, or support paging, by providing a fromRange and toRange in the request. A Fault with a faultstring is returned if the find fails.

deleteDisScanRun

This operation deletes Scan Results from the system. All results and discrepancies attached to the scan results are deleted as well. A Fault with a faultstring is returned if the delete fails.

getDisScanRun

This operation gets all the details about an instance of Scan Results. The operation requires the Discrepancy entity id to be passed in the request, and returns the full details of the Discrepancy including references to the compare and reference Oracle Communications Information Model entities which the discrepancy was found on. If not found, a Fault is the response.


Table 26-3 describes the DisBlackoutSchedule operations. See Network Integrity Information Model Reference for further information on this entity.

Table 26-3 DisBlackoutSchedule Operations

Operation Description

createDisBlackoutSchedule

This operation creates a new Blackout Schedule in the system. A recurrence rule, duration, and start time are required in the request. The Blackout Schedule can be assigned to Scan Configurations on creation, or they can be associated later with an update operation.

deleteDisBlackoutSchedule

This operation deletes a Blackout Schedule in the system. If any Scans are associated with the Blackout Schedule then the associations are removed as well. A Fault with a faultstring is returned if the delete fails.

getAllDisBlackoutSchedule

This operation returns the full details of all the Blackout Schedules in the system. An empty response is returned if no Blackout Schedules exist in the system.

getDisBlackoutSchedule

This operation requires the Blackout Schedule entity id to be passed in the request, and returns the full details of the Blackout Schedule in the response if found. If not found, a Fault is the response.

updateDisBlackoutSchedule

This operation updates a Blackout Schedule in the system. All the values for the Blackout Schedule are required in the request, not just the values changing. A Fault with a faultstring is returned if the update fails.


Table 26-4 describes the DisTag operations. See Network Integrity Information Model Reference for further information on this entity.

Table 26-4 DisTag Operations

Operation Description

createDisTag

This operation creates a new Tag, a name for the tag is required. The parent tag entity id can be provided in the creation or can be add after in an update request. A Fault with a faultstring is returned if the delete fails.

deleteDisTag

This operation deletes the specified Tag and all child Tags. The entity id of the Tag to be deleted is required. If any Scans are associated with the Tag then the associations are removed as well. A Fault with a faultstring is returned if the delete fails.

getDisTag

This operation requires the Tag entity id to be passed in the request, and returns the full details of the Tag including all child tags in the response, if found. If not found, a Fault is the response.

getAllRootDisTags

This operation returns the full details of all the Tags configured in the system. The root Tags returned also include the details of children Tag entities. A Fault with a faultstring is returned if an error occurs.

updateDisTag

This operation updates a Tag, an entity id and name for the tag is required. All the values for the Blackout Schedule are required in the request, not just the values that are changing. Modifications to the hierarchy must be performed on the child Tag, for example, to make a child Tag a root Tag call the update operation with no parent Tags specified. A Fault with a faultstring is returned if the update fails.


Table 26-5 describes the DisDiscrepancy operations. See Network Integrity Information Model Reference for further information on this entity.

Table 26-5 DisDiscrepancy Operations

Operation Description

findDisDiscrepancy

This operation finds Discrepancies in the system based on search criteria provided in the request. The search criteria available in the Web Service API operation is the same as the criteria available in the Network Integrity UI (DisScanRun is equivalent to Scan Results in the Network Integrity Web UI). Full Discrepancy data is returned but client applications can limit the amount of data returned, or support paging, by providing a fromRange and toRange in the request. A Fault with a faultstring is returned if the find fails.

getDisDiscrepancy

This operation gets all the details about a Discrepancy. The operation requires the Discrepancy entity id to be passed in the request, and returns the full details of the Discrepancy including references to the compare and reference Information Model entities which the discrepancy was found on. If not found, a Fault is the response.

updateDisDiscrepancy

This operation updates a Discrepancy in the system. All the values for the DisDiscrepancy are required in the request, not just the values changing. The valid values of Status are

  • DISCREPANCY_OPENED

  • DISCREPANCY_IGNORED

  • OPERATION_IDENTIFIED

  • OPERATION_SUBMITTED

  • OPERATION_RECEIVED

  • OPERATION_NOT_IMPLEMENTED

  • OPERATION_PROCESSED

  • OPERATION_FAILED

The operation value is equivalent to Resolution Action value in the Network Integrity UI and the valid values is dependent on what Discrepancy Resolution are currently installed in the system. A Fault with a faultstring is returned if the update fails.


Table 26-6 describes the DisPlugin operations. See Network Integrity Information Model Reference for further information on this entity.

Table 26-6 DisPlugin Operation

Operation Description

getAllDisAssimilationPlugin

This operation returns details about all Assimilation Plugins deployed in the system (AssimilationPlugin is equivalent to Assimilation/Scan Action in the Network Integrity UI).

getAllDisInventoryImportPlugin

This operation returns details about all Import Plugins deployed in the system (InventoryImportPlugin is equivalent to Import/Scan Action in the Network Integrity UI).

getAllDisNetworkDiscoveryPlugin

This operation returns details about all Discovery Plugins deployed in the system (NetworkDiscoveryPlugin is equivalent to Discovery/Scan Action in the Network Integrity UI).

getAllDisDiscrepancyDetectionPlugin

This operation returns details about all Discrepancy Detection Plugins deployed in the system (Discrepancy Detection Plugin is equivalent to a Discrepancy Detection Action)

getAllDisDiscrepancyResolutionPlugin

This operation returns details about all Discrepancy Resolution Plugins deployed in the system (Discrepancy Resolution Plugin is equivalent to a Discrepancy Resolution Action)

getDisAssimilationPlugin

This operation returns details about an Assimilation Plugin deployed in the system (AssimilationPlugin is equivalent to Assimilation/Scan Action in the Network Integrity UI). The request requires an Assimilation Plugin entity id to be passed, and returns the full details of the Assimilation Plugin in the response if found. If not found, a Fault is the response.

getDisInventoryImportPlugin

This operation returns details about an Import Plugin deployed in the system (InventoryImportPlugin is equivalent to Import/Scan Action in the Network Integrity UI). The request requires an Import Plugin entity id to be passed, and returns the full details of the Import Plugin in the response if found. If not found, a Fault is the response.

getDisNetworkDiscoveryPlugin

This operation returns details about a Discovery Plugin deployed in the system (NetworkDiscoveryPlugin is equivalent to Discovery/Scan Action in the Network Integrity UI). The request requires a Discovery Plugin entity id to be passed, and returns the full details of the Discovery Plugin in the response if found. If not found, a Fault is the response.

getDisDiscrepancyDetectionPlugin

This operation returns details about an Discrepancy Detection Plugin deployed in the system (Discrepancy Detection Plugin is equivalent to a Discrepancy Detection Action). The request requires an Discrepancy Detection Plugin entity id to be passed, and returns the full details of the Discrepancy Detection Plugin in the response if found. If not found, a Fault is the response.

getDisDiscrepancyResolutionPlugin

This operation returns details about an Discrepancy Resolution Plugin deployed in the system (Discrepancy Resolution Plugin is equivalent to a Discrepancy Resolution Action). The request requires an Discrepancy Resolution Plugin entity id to be passed, and returns the full details of the Discrepancy Resolution Plugin in the response if found. If not found, a Fault is the response.


Table 26-7 describes the DefaultDisInvetoryConfig operations.

Table 26-7 DefaultDisInventoryConfig

Operation Description

getDefaultDisInventoryConfig

This operation returns the inventory system configured in the Network Integrity system. This is the inventory system configuration that is entered in the ”Manage Import System” task of the Network Integrity Web UI. The Import System cannot be created or updated using the Web Service API, it must be done using the Network Integrity Web UI.


Table 26-8 describes the Special operations.

Table 26-8 Special Operations

Operation Description

startScan

This operation starts a scan. The response returns a reference to the Scan Result entity so that the client application can monitor the progress of the scan. (DisScanRun is equivalent to the Scan Results in the Network Integrity UI). If the Scan is already running or in the process of stopping then the startScan operation fails. If the scan could not be started, a Fault with a reason is the response.

stopScan

This operation stops a scan that is running. The scan is transitioned to a STOPPING state immediately and then transition to STOPPED when actually ended. If the Scan is not currently running, this call is a no-op. If the scan could not be transitioned to Stopping, a Fault with a reason is the response.

submitDisDiscrepancyResolutionOperations

This operation submits the list of discrepancies provided in the request for resolution processing. The status of the discrepancies must be 'OPERATION_IDENTIFIED' to submit them, otherwise a Fault is returned. A Fault with a faultstring is returned if the operation fails.

getLatestScanStatus

This operation returns the scan status for the most recent execution of a scan. This operation is more efficient than getDisScanRun and therefore is more appropriate for client applications that are monitoring the status of a scan (DisConfig is equivalent to Scan in the Network Integrity Web UI). A Fault with a faultstring is returned if the operation fails.


Table 26-9 describes the Information Model entity operations. Information Model entities are described in Oracle Communications Information Model Reference and Network Integrity Information Model Reference.

Table 26-9 Information Model Entity Operations

Operation Description

getRootEntity

This operation gets all the details about a discovered, imported, or assimilated root Information Model entity. The root entity id for the request is obtained from either a getDisScanRun operation response or findDisScanRun operation response. The id is found in the 'rootEntityRefsRef' element in the result groups. Multiple ids can be passed in the request. The response entity can be many different types depending on what the cartridge persisted in the result group. An example root entity type is Physical Device or Logical Device, but other Information Model types are possible. If not found, a Fault is the response.

getResultEntity

A generic operation to get any type of Information Model entity given an entityId and the entity type. Multiple entities can be retrieved in a single request. If not found, a Fault is the response.

getSpecification

This operation gets all the details about specification deployed in the system. Most Information Model entities support specifications which is blueprint for what characteristics are supported, among other things. All the characteristics defined in this specification are returned. Specifications are deployed to the system when cartridges containing them are deployed. If not found, a Fault is the response.

getLogicalDevice

This operation requires the LogicalDevice entity id to be passed in the request, and returns the full details of the LogicalDevice if found. If not found, a Fault is the response.

getDeviceInterface

This operation requires the DeviceInterface entity id to be passed in the request, and returns the full details of the DeviceInterface if found. If not found, a Fault is the response.

getMediaInterface

This operation requires the MediaInterface entity id to be passed in the request, and returns the full details of the MediaInterface if found. If not found, a Fault is the response.

getLogicalDeviceAccount

This operation requires the LogicalDeviceAccount entity id to be passed in the request, and returns the full details of the LogicalDeviceAccount if found. If not found, a Fault is the response.

getPhysicalDevice

This operation requires the PhysicalDevice entity id to be passed in the request, and returns the full details of the PhysicalDevice if found. If not found, a Fault is the response.

getEquipment

This operation requires the Equipment entity id to be passed in the request, and returns the full details of the Equipment if found. If not found, a Fault is the response.

getEquipmentHolder

This operation requires the EquipmentHolder entity id to be passed in the request, and returns the full details of the EquipmentHolder if found. If not found, a Fault is the response.

getPhysicalPort

This operation requires the PhysicalPort entity id to be passed in the request, and returns the full details of the PhysicalPort if found. If not found, a Fault is the response.

getPhysicalConnector

This operation requires the PhysicalConnector entity id to be passed in the request, and returns the full details of the PhysicalConnector if found. If not found, a Fault is the response.

getCustomObject

This operation requires the CustomObject entity id to be passed in the request, and returns the full details of the CustomObject if found. If not found, a Fault is the response.

getCustomNetworkAddress

This operation requires the CustomNetworkAddress entity id to be passed in the request, and returns the full details of the CustomNetworkAddress if found. If not found, a Fault is the response.

getTelephoneNumber

This operation requires the TelephoneNumber entity id to be passed in the request, and returns the full details of the TelephoneNumber if found. If not found, a Fault is the response.

getInventoryGroup

This operation requires the InventoryGroup entity id to be passed in the request, and returns the full details of the InventoryGroup if found. If not found, a Fault is the response.

getService

This operation requires the Service entity id to be passed in the request, and returns the full details of the Service if found. If not found, a Fault is the response.

getNetwork

This operation requires the Network entity id to be passed in the request, and returns the full details of the Network if found. If not found, a Fault is the response.

getNetworkNode

This operation requires the NetworkNode entity id to be passed in the request, and returns the full details of the NetworkNode if found. If not found, a Fault is the response.

getNetworkEdge

This operation requires the NetworkEdge entity id to be passed in the request, and returns the full details of the NetworkEdge if found. If not found, a Fault is the response.

getPipe

This operation requires the Pipe entity id to be passed in the request, and returns the full details of the Pipe if found. If not found, a Fault is the response.

getPipeTerminationPoint

This operation requires the PipeTerminationPoint entity id to be passed in the request, and returns the full details of the PipeTerminationPoint if found. If not found, a Fault is the response.

getPipeDirectionality

This operation requires the PipeDirectionality entity id to be passed in the request, and returns the full details of the PipeDirectionality if found. If not found, a Fault is the response.

getTrailPath

This operation requires the TrailPath entity id to be passed in the request, and returns the full details of the TrailPath if found. If not found, a Fault is the response.

getGeographicPlace

This operation requires the GeographicPlace entity id to be passed in the request, and returns the full details of the GeographicPlace if found. If not found, a Fault is the response.

getGeographicAddress

This operation requires the GeographicAddress entity id to be passed in the request, and returns the full details of the GeographicAddress if found. If not found, a Fault is the response.

getGeographicAddressRange

This operation requires the GeographicAddressRange entity id to be passed in the request, and returns the full details of the GeographicAddressRange if found. If not found, a Fault is the response.

getGeographicLocation

This operation requires the GeographicLocation entity id to be passed in the request, and returns the full details of the GeographicLocation if found. If not found, a Fault is the response.

getGeographicSite

This operation requires the GeographicSite entity id to be passed in the request, and returns the full details of the GeographicSite if found. If not found, a Fault is the response.

getNetworkNodeRole

This operation requires the NetworkNodeRole entity id to be passed in the request, and returns the full details of the NetworkNodeRole if found. If not found, a Fault is the response.

getPhysicalConnectorRole

This operation requires the PhysicalConnectorRole entity id to be passed in the request, and returns the full details of the PhysicalConnectorRole if found. If not found, a Fault is the response.

getPipeRole

This operation requires the PipeRole entity id to be passed in the request, and returns the full details of the PipeRole if found. If not found, a Fault is the response.

getPhysicalPortRole

This operation requires the PhysicalPortRole entity id to be passed in the request, and returns the full details of the PhysicalPortRole if found. If not found, a Fault is the response.

getDeviceInterfaceRole

This operation requires the DeviceInterfaceRole entity id to be passed in the request, and returns the full details of the DeviceInterfaceRole if found. If not found, a Fault is the response.

getLogicalDeviceRole

This operation requires the LogicalDeviceRole entity id to be passed in the request, and returns the full details of the LogicalDeviceRole if found. If not found, a Fault is the response.

getCustomObjectRole

This operation requires the CustomObjectRole entity id to be passed in the request, and returns the full details of the CustomObjectRole if found. If not found, a Fault is the response.

getPhysicalDeviceRole

This operation requires the PhysicalDeviceRole entity id to be passed in the request, and returns the full details of the PhysicalDeviceRole if found. If not found, a Fault is the response.

getEquipmentRole

This operation requires the EquipmentRole entity id to be passed in the request, and returns the full details of the EquipmentRole if found. If not found, a Fault is the response.

getNetworkEdgeRole

This operation requires the NetworkEdgeRole entity id to be passed in the request, and returns the full details of the DeviNetworkEdgeRole ceInterface if found. If not found, a Fault is the response.

getPlaceRole

This operation requires the PlaceRole entity id to be passed in the request, and returns the full details of the PlaceRole if found. If not found, a Fault is the response.

getNetworkRole

This operation requires the NetworkRole entity id to be passed in the request, and returns the full details of the NetworkRole if found. If not found, a Fault is the response.


Create, Read, Update, Delete Pattern

Most of the operations defined in the Network Integrity Web Service API follow a pattern.

The operation patterns are:

  • Create

  • Get

  • Get All

  • Delete

  • Update

  • Find

The following sections describe each pattern and the common attributes to each. An example request and response is given for each pattern.

There are a few Web Service API operations that do not follow the pattern. There are dedicated sections with examples for each of these.

Create Operation

The create operation inserts a new entity into the system. For example, the createDisBlackoutSchedule operation creates a new Blackout Schedule in the system.

If successful, the changes are immediately available in the system and can be viewed in the Web UI.

The request for the Create operation is named create<EntityType>Request. The request contains the full details of the new entity to be created. Multiple entities cannot be created in a single request, only a single entity is supported.

The following fields should not be supplied in the create request as they are populated automatically by the system.

  • entityId

  • entityVersion

  • lastModifiedDate

  • lastModifiedUser

  • createdDate

  • createdUser

The response is named create<EntityType>Response and contains the entityId of the created entity if the operation was successful. The entityId returned is used in subsequent get and delete operations.

If the create operation fails, the response contains a Fault with a faultCode, faultString, and extra CrudFault details.

Example 26-1 Create Request

<v1:createDisTagRequest>
  <v1:disTag>
    <v13:name>Sample Tag</v13:name>
    <v13:description>Created through Web Service</v13:description>
  </v1:disTag>
</v1:createDisTagRequest>

Example 26-2 Create Response

<ns118:createDisTagResponse>
   <ns118:disTagRef>
      <ns2:entityId>9584</ns2:entityId>
   </ns118:disTagRef>
</ns118:createDisTagResponse>

Example 26-3 Create Failure (a name was not specified for the tag)

<ns2:Fault>
   <faultcode>ns2:Server</faultcode>
   <faultstring>ILLEGAL_NAME</faultstring>
   <detail>
      <ns158:crudFault>
         <ns152:rootStackTrace/>
      </ns158:crudFault>
   </detail>
</ns2:Fault>

Entity Type Support

Supported on Entity Types

  • DisBlackoutSchedule

  • DisTag

  • DisConfig

Get Operation

The get operation is used to retrieve an entity from the system. The get request requires a unique entity id and the entity details are returned in the response. For example, the getDisBlackoutSchedule operation returns all the details of a specific Blackout Schedule in the system.

The request for the Get operation is named get<EntityType>Request. The request contains a single entityId of the entity to be retrieved. Only one entityId can be specified in the request, multiples are ignored. The exception to this is the getRootEntity and getResultEntity operations; these operations accept multiple entity id values.

If the entityId provided is not found in the system a fault is returned, not an empty response.

The response is named get<EntityType>Response and contains the details of the entity retrieved from the system.

If the get operation fails, the response contains a Fault with a faultCode, faultString, and extra CrudFault details.

Example 26-4 Get Request

<v1:getDisTagRequest>
   <v1:disTagRef>
      <v11:entityId>9586</v11:entityId>
   </v1:disTagRef>
</v1:getDisTagRequest>

Example 26-5 Get Response

<ns118:getDisTagResponse>
 <ns118:disTag>
    <ns2:entityId>9586</ns2:entityId>
    <ns2:entityVersion>1</ns2:entityVersion>
    <ns12:parentRef>
       <ns2:entityId>9584</ns2:entityId>
    </ns12:parentRef>
    <ns12:name>Sample Child Tag</ns12:name>
    <ns12:description>Child Created through WS</ns12:description>
 </ns118:disTag>
</ns118:getDisTagResponse>

Example 26-6 Get Failure (entity id was not found)

<ns2:Fault>
   <faultcode>ns2:Server</faultcode>
   <faultstring>Cannot find Tag with entity Id 9586</faultstring>
   <detail>
      <ns158:crudFault>
         <ns151:rootStackTrace/>
      </ns158:crudFault>
   </detail>
</ns2:Fault>

Entity Type Support

Supported on Entity Types

  • DisBlackoutSchedule

  • DisTag

  • DisConfig

  • DisDiscrepancy

  • DisInventoryImportPlugin

  • DisNetworkDiscoveryPlugin

  • DisAssimilationPlugin

  • DisDiscrepancyResolutionPlugin

  • DisDiscrepancyDetectionPlugin

  • DisScanRun

  • RootEntity

  • ResultEntity

  • Specification

  • DefaultDisInventoryConfig

  • DeviceInterface

  • PhysicalDevice

  • EquipmentHolder

  • MediaInterface

  • Equipment

  • LogicalDevice

  • PhysicalPort

  • PhysicalConnector

  • CustomObject

Get All Operation

The get all operation is used to retrieve all entities of a certain type from the system. For example, the getAllDisBlackoutSchedule operation returns all the details of all the Blackout Schedules currently in the system.

This operation is only available for entities would not typically have many entries in the system and that do not support a Find operation.

The request for the Get All operation is named getAll<EntityType>Request. The request does not support any request parameters.

The response is named getAll<EntityType>Response and contains the details of all the entities retrieved from the system.

If the get operation fails, the response contains a Fault with a faultCode, faultString, and extra CrudFault details. Since this operation does not take any input parameters it should only fail due to environment or authentication issues.

Example 26-7 Get All Request

<v1:getAllRootDisTagsRequest/>

Example 26-8 Get All Response

<ns118:getAllRootDisTagsResponse>
  <ns118:rootDisTags>
     <ns2:entityId>9584</ns2:entityId>
     <ns2:entityVersion>3</ns2:entityVersion>
     …etc
  </ns118:rootDisTags>
  <ns118:rootDisTags>
     <ns2:entityId>9585</ns2:entityId>
     <ns2:entityVersion>3</ns2:entityVersion>
     …etc
  </ns118:rootDisTags>
</ns118:getAllRootDisTagsResponse>

Supported on Entity Types:

  • DisBlackoutSchedule

  • RootDisTag

  • DisInventoryImportPlugin

  • DisNetworkDiscoveryPlugin

  • DisAssimilationPlugin

  • DisDiscrepancyResolutionPlugin

  • DisDiscrepancyDetectionPlugin

Delete Operation

The delete operation is used to remove an entity from the system. For example, the deleteDisBlackoutSchedule operation removes a particular Blackout Schedule from the system.

If successful, the result of the delete operation is immediately viewable in the Web UI.

The request for the Delete operation is named delete<EntityType>Request. The request contains a single entityId of the entity to be deleted. Only one entityId can be specified in the request, multiples are ignored.

If the entityId provided is not found in the system, or if the entity cannot be deleted, a fault is returned.

Note:

The deleteDisConfig operation has an additional optional parameter you can enter in the delete request to force a scan to be deleted, even if it has associated discrepancies in the Running or Submitted state. See Table 26-1, "DisConfig Operations" for more information.

The response is named delete<EntityType>Response and contains the entityId of the entity deleted, which matches the id in the request.

If the delete operation fails, the response contains a Fault with a faultCode, faultString, and extra CrudFault details.

Example 26-9 Delete Request

<v1:deleteDisTagRequest>
    <v1:disTagRef>
        <v11:entityId>9579</v11:entityId>
    </v1:disTagRef>
</v1:deleteDisTagRequest>

Example 26-10 Delete Response

<ns118:deleteDisTagResponse>
    <ns118:disTagRef>
       <ns2:entityId>9579</ns2:entityId>
    </ns118:disTagRef>
</ns118:deleteDisTagResponse>

Example 26-11 Delete Failure (entity id was not found)

<ns2:Fault>
   <faultcode>ns2:Server</faultcode>
   <faultstring>Cannot find Tag with Entity Id9579</faultstring>
   <detail>
      <ns158:crudFault>
         <ns151:rootStackTrace/>
      </ns158:crudFault>
   </detail>
</ns2:Fault>

Entity Type Support

Supported on Entity Types:

  • DisBlackoutSchedule

  • DisTag

  • DisConfig

  • DisScanRun

Update Operation

The update operation modifies an existing entity in the system. For example, the updateDisBlackoutSchedule operation updates a Blackout Schedule currently in the system.

If successful, the update is immediately available in the system and can be viewed in the Web UI.

The request for the Update operation is named update<EntityType>Request. The request must contain the full details of the new entity to be created, not just the fields that have changed. Multiple entities cannot be updated in a single request, only a single entity is supported. Unlike the create operation, the entityId must be supplied in the update operation to uniquely identity which entity to modify.

The entity version passed in the request must match the version that is held on the server. The entity version is incremented by the system every time the entity is modified. The entity version ensures that the entity has not been changed by some other user between when the entity was last retrieved and when updated. If the entity has been changed by some other user a Fault is returned as follows: Entity Version Mismatch: Input Version=1::Latest Version=2

Because the full details of the entity are required in the update request, the recommended steps are to do a get, get all, or find operation to get the details of the entity, and then copy these details into the update request, and modify the desired fields.

The following fields should not be supplied in the update request as they are populated automatically by the system or are not currently used.

  • lastModifiedDate

  • lastModifiedUser

  • createdDate

  • createdUser

The response is named update<EntityType>Response and contains the entityId of the updated entity if the operation was successful.

If the create operation fails, the response contains a Fault with a faultCode, faultString, and extra CrudFault details.

Example 26-12 Update Request

<v1:updateDisTagRequest>
  <v1:disTag>
     <v11:entityId>9586</v11:entityId>
     <v11:entityVersion>1</v11:entityVersion>
     <v12:parentRef>
        <v2:entityId>9584</v2:entityId>
     </v12:parentRef>
     <v11:name>Sample Child Tag</v11:name>
     <v11:description>Modified through WS</v11:description>
  </v1:disTag>
</v1:updateDisTagRequest>

Example 26-13 Update Response

<ns118:updateDisTagResponse>
    <ns118:disTagRef>
       <ns2:entityId>9586</ns2:entityId>
    </ns118:disTagRef>
</ns118:updateDisTagResponse>

Example 26-14 Update Failure (wrong entity version supplied)

<ns2:Fault>
   <faultcode>ns2:Server</faultcode>
   <faultstring>Entity Version Mismatch: Input Version=2::Latest Version=3</faultstring>
   <detail>
      <ns158:crudFault>
         <ns151:rootStackTrace/>
      </ns158:crudFault>
   </detail>
</ns2:Fault>

Entity Type Support

Supported on Entity Types

  • DisBlackoutSchedule

  • DisTag

  • DisConfig

  • DisDiscrepancy

Find Operation

The find operation retrieves a list of entities that match filter search criteria. For example, the findDisConfig operation retrieves a list DisConfig entities currently in the system that match a given set of search criteria.

The find operation in the Network Integrity API is equivalent in capability to the Search screens in the Network Integrity Web UI.

The request for the Find operation is named find<EntityType>Request. The find request can contain:

  • From and To Ranges

  • Sorting Fields (Ascending and Descending)

  • Attribute Criteria

  • Extended Attribute Criteria

  • Criteria Operator (Equals, Contains, and so on)

  • Conjunction Criteria (AND/OR)

Supported on Entity Types

  • DisConfig

  • DisScanRun

  • DisDiscrepancy

From and To Range

The fromRange and toRange are used to limit the number of rows returned to a client. This is used to support paging in user interfaces using the Web Service API. It is also useful to improve performance and memory usage by retrieving many rows in smaller, more manageable chunks.

If the fromRange is not provided the default value is 0 which means the find returns the first row on. If the toRange is not provided in the request then the find operation is unbounded and returns all rows to the end.

<v1:findDisConfigRequest>
   <v1:disConfigSearchCriteria>
      <fromRange>0</fromRange>
      <toRange>20</toRange>
      <descending>name</descending>
      <disConfigConjunctionCriteriaItem>
         <nameAttributeCriteria>
            <value>Cisco</value>
            <operator> EQUALS</operator>
         </nameAttributeCriteria>
         <conjunction>AND</conjunction>
      </disConfigConjunctionCriteriaItem>
   </v1:disConfigSearchCriteria>
</v1:findDisConfigRequest>

Ascending & Descending

The ascending and descending fields control how the entity results are sorted in the response. The ascending and descending fields hold the name of the attribute to be sorted on. Multiple ascending and descending fields can be specified to add more than one level of sorting. If both an ascending and descending sort field are not provided in the request then the order of the entities returned is not sorted, and returned in the order they are persisted.

<v1:findDisConfigRequest>
   <v1:disConfigSearchCriteria>
      <fromRange>0</fromRange>
      <toRange>20</toRange>
      <descending>name</descending>
      <disConfigConjunctionCriteriaItem>
         <nameAttributeCriteria>
            <value>Cisco</value>
            <operator>EQUALS</operator>
         </nameAttributeCriteria>
         <conjunction>AND</conjunction>
      </disConfigConjunctionCriteriaItem>
   </v1:disConfigSearchCriteria>
</v1:findDisConfigRequest>

Attribute Criteria

The attribute criteria is used to specify the field and value to match when performing the find operation. In addition, an operator needs to be specified in the attribute criteria to determine how the match is done (for example, EQUALS, NOT_EQUALS, and so on).

Zero or more attribute criteria are contained within an entity's ConjunctionCriteriaItem.

The <EntityType>ConjunctionCriteriaItem element defines a list of valid <attributeName>AttributeCriteria child elements. For example, the disConfigConjunctionCriteriaItem has an attributeCriteria for every attribute that is searchable, namely the nameAttributeCriteria, descriptionAttributeCriteria, enabledAttributeCriteria, and so on.

For each attribute criteria the value to match and the operator to use to perform the match. The operators that are valid depend on the attribute type. For a list of valid operators refer to the operator section below.

You can use wildcards in the value field for attributes that are text types. The supported wildcard characters are ”*'”, ”%”, and ”_”. ”*” and ”%” both represent a match of zero or more characters. ”_”represents a match of any single character. Wildcard characters can be escaped with a backslash ”\”. To insert a backslash in the query, insert two backslashes ”\\”.

<v1:findDisConfigRequest>
   <v1:disConfigSearchCriteria>
      <fromRange>0</fromRange>
      <toRange>20</toRange>
      <descending>name</descending>
      <disConfigConjunctionCriteriaItem>
         <nameAttributeCriteria>
            <value>Cisco</value>
            <operator>EQUALS</operator>
         </nameAttributeCriteria>
         <conjunction>AND</conjunction>
      </disConfigConjunctionCriteriaItem>
   </v1:disConfigSearchCriteria>
</v1:findDisConfigRequest>

Multiple Attribute Criteria

Multiple criteria for the same attribute can be passed in a single find operation. In the example below the find request is looking for Scans that start with the name Cisco or Juniper. It is necessary to specify the &rsquor;OR' conjunction in this scenario or no rows is returned.

<v1:findDisConfigRequest>
   <v1:disConfigSearchCriteria>
      <fromRange>0</fromRange>
      <toRange>20</toRange>
      <descending>name</descending>
      <disConfigConjunctionCriteriaItem>
         <nameAttributeCriteria>
            <value>Cisco*</value>
            <operator>EQUALS</operator>
         </nameAttributeCriteria>
         <nameAttributeCriteria>
            <value>Juniper*</value>
            <operator> EQUALS </operator>
         </nameAttributeCriteria>
         <conjunction>OR</conjunction>
      </disConfigConjunctionCriteriaItem>
   </v1:disConfigSearchCriteria>
</v1:findDisConfigRequest>

Extended Attribute Criteria

Extended Attribute Criteria allow the client application to find entities based on the attribute values on related entities. For example, to find all scans with a certain Scope Address would not be possible without extended criteria because the scope address is not defined on the DisConfig entity. Multiple criteria for the same attribute can be passed in a single find operation.

In the example below, the scope relationship on the DisConfig entity is followed, and then the addresses relationship if followed on the DisScope, to specify the addresses to match against. This search finds DisConfig entities that have either the address 10.156.68.136 or 10.156.68.140 in the scope. The schemas for the Web Service API define all the relationships and attributes that can be specified in the find operation.

<v1:findDisConfigRequest>
   <v1:disConfigSearchCriteria>
      <fromRange>0</fromRange>
      <toRange>20</toRange>
      <disConfigConjunctionCriteriaItem>
         <disConfigExtendedCriteriaItem>
            <scope>
               <disScopeConjunctionCriteriaItem>
                  <disScopeExtendedCriteriaItem>
                     <addresses>
                        <disAddressConjunctionCriteriaItem>
                           <addressAttributeCriteria>
                              <value>10.156.68.136</value>
                              <operator>EQUALS</operator>
                           </addressAttributeCriteria>
                           <addressAttributeCriteria>
                              <value>10.156.68.140</value>
                              <operator>EQUALS</operator>
                           </addressAttributeCriteria>
                           <conjunction>OR</conjunction>
                        </disAddressConjunctionCriteriaItem>
                     </addresses>
                  </disScopeExtendedCriteriaItem>
               </disScopeConjunctionCriteriaItem>
            </scope>
         </disConfigExtendedCriteriaItem>
         <conjunction>OR</conjunction>
      </disConfigConjunctionCriteriaItem>
   </v1:disConfigSearchCriteria>
</v1:findDisConfigRequest>

Criteria Operators

The following are the allowed search operators for each entity and attribute. If the web service clients sends the wrong operator for a search criteria the web service search request fails and the client gets a message, which shows the allowed operators for that search criteria.

DisConfig

Table 26-10 shows the allowed search operators for DisConfig attributes.

Table 26-10 Allowed Search Operators for DisConfig Attributes

Attribute Name EQUALS NOT_EQUAL STARTS_WITH FALSE TRUE

Tag

Y

Y

Y

N/A

N/A

Name

Y

Y

N/A

N/A

N/A

ScanAction

Y

Y

N/A

N/A

N/A

ScanType

Y

Y

N/A

N/A

N/A

Description

Y

Y

N/A

N/A

N/A

Source

Y

Y

N/A

N/A

N/A

NetworkAddress

Y

N/A

N/A

N/A

N/A

Enabled

N/A

N/A

N/A

Y

Y

Run Reconciliation

N/A

N/A

N/A

Y

Y


DisScanRun

Table 26-11, Table 26-12, and Table 26-13 shows the allowed search operators for DisScanRun.

Table 26-11 Allowed Search Operators for DisScanRun Attributes

Attribute Name EQUALS NOT_EQUAL STARTS_WITH

Tag

Y

Y

Y

Name

Y

Y

N/A

Status

Y

Y

N/A

ScanType

Y

Y

N/A

Source

Y

Y

N/A

ScanAction

Y

Y

N/A


Table 26-12 Allowed Search Operators for DisScanRun Attributes

Attribute Name BEFORE AFTER ON_OR_AFTER ON_OR_BEFORE BETWEEN NOT_BETWEEN

ScanStartTime

Y

Y

Y

Y

Y

Y

ScanEndTime

Y

Y

Y

Y

Y

Y

DiscrepancyDetectionStartTime

Y

Y

Y

Y

Y

Y

DiscrepancyDetectionEndTime

Y

Y

Y

Y

Y

Y


Table 26-13 Allowed Search Operators for DisScanRun Attributes

Attribute Name EQUALS NOT_EQUAL GREATER_THAN LESS_THAN BETWEEN NOT_BETWEEN

MinorDiscrepancies

Y

Y

Y

Y

Y

Y

MajorDiscrepancies

Y

Y

Y

Y

Y

Y

CriticalDiscrepancies

Y

Y

Y

Y

Y

Y

WarningDiscrepancies

Y

Y

Y

Y

Y

Y


DisDiscrepancy

Table 26-14 and Table 26-15 shows the allowed search operators for DisDiscrepancy.

Table 26-14 Allowed Search Operators for DisDiscrepancy Attributes

Attribute Name EQUALS NOT_EQUAL STARTS_WITH IS_BLANK IS_NOT_BLANK

Tag

Y

Y

Y

N/A

N/A

Severity

Y

Y

N/A

N/A

N/A

Status

Y

Y

N/A

N/A

N/A

ResolutionAction

Y

Y

N/A

Y

Y

Owner

Y

Y

N/A

Y

Y

Priority

Y

Y

N/A

Y

Y

EntityName

Y

Y

N/A

N/A

N/A

ScanResultDetailName

Y

Y

N/A

N/A

N/A

ScanType

Y

Y

N/A

N/A

N/A

EntityName

Y

Y

N/A

N/A

N/A

ScanResultDetailName

Y

Y

N/A

N/A

N/A

ScanName

Y

Y

N/A

N/A

N/A

EntityType

Y

Y

N/A

N/A

N/A

CorrectedBy

Y

Y

N/A

N/A

N/A

SubmittedBy

Y

Y

N/A

N/A

N/A

ParentEntityNamw

Y

Y

N/A

N/A

N/A

ParentEntityType

Y

Y

N/A

N/A

N/A

Discovery/ImportValue

Y

Y

N/A

N/A

N/A

Discovery/ImportSource

Y

Y

N/A

N/A

N/A

ScanResultDetailCategory

Y

Y

N/A

N/A

N/A

Type

Y

Y

N/A

N/A

N/A

ScanType

Y

Y

N/A

N/A

N/A


Table 26-15 Allowed Search Operators for DisDiscrepancy Attributes

Attribute Name BEFORE AFTER ON_OR_AFTER ON_OR_BEFORE BETWEEN NOT_BETWEEN

ScanStartTime

Y

Y

Y

Y

Y

Y

ScanEndTime

Y

Y

Y

Y

Y

Y

DiscrepancyDetectionStartTime

Y

Y

Y

Y

Y

Y

DiscrepancyDetectionEndTime

Y

Y

Y

Y

Y

Y

SubmittedTime

Y

Y

Y

Y

Y

Y

LastStatusChangeTime

Y

Y

Y

Y

Y

Y


Between/Not Between Operator

When specifying the BETWEEN and NO_BETWEEN operators, two attribute criteria must be supplied or a fault is returned. The error message returned is Incorrect number of values or incorrect format specified for attribute criteria: numberWarning.

The following example searches for Scan Results that found between 10 and 100 discrepancy warnings.

<v1:findDisScanRunRequest>
   <v1:disScanRunSearchCriteria>
      <v11:fromRange>0</v11:fromRange>
      <v11:toRange>20</v11:toRange>
      <v11:disScanRunConjunctionCriteriaItem>
         <v12:disScanRunExtendedCriteriaItem>
            <v14:counts>
               <v119:disDiscrepancyCountsConjunctionCriteriaItem>
                  <v120:warningAttributeCriteria>
                     <v121:value>10</v121:value>
                     <v121:value>100</v121:value>
                     <v121:operator>BETWEEN</v121:operator>
                  </v120:warningAttributeCriteria>
               </v119:disDiscrepancyCountsConjunctionCriteriaItem>
            </v14:counts>
         </v12:disScanRunExtendedCriteriaItem>
         <v12:conjunction>AND</v12:conjunction>
      </v11:disScanRunConjunctionCriteriaItem>
   </v1:disScanRunSearchCriteria>
</v1:findDisScanRunRequest>

Date Criteria

Date fields must be in the format mm/dd/yyyy mm:dd:ss AM/PM. The server time is always used for dates in Network Integrity. The following example searches for Scans Runs that started after the August 11th, 2010 10:00 am. Because the AFTER operator is used, scan runs that match this start time exactly are not included in the response. If operator ON_OR_AFTER was used then exact match start time scan runs would be included in the response.

<v1:findDisScanRunRequest>
   <v1:disScanRunSearchCriteria>
      <v11:fromRange>0</v11:fromRange>
      <v11:toRange>20</v11:toRange>
      <v11:disScanRunConjunctionCriteriaItem>
         <v12:discoveryBeginTimeAttributeCriteria>
            <v13:value>08/11/2010 10:00:00 AM</v13:value>
            <v13:operator>AFTER</v13:operator>
         </v12:discoveryBeginTimeAttributeCriteria>
         <v12:conjunction>AND</v12:conjunction>
      </v11:disScanRunConjunctionCriteriaItem>
   </v1:disScanRunSearchCriteria>
</v1:findDisScanRunRequest>

Conjunction Criteria

The conjunction must be either AND or OR. Only the top level conjunction is used, conjunctions on lower level elements are ignored.

<v1:findDisConfigRequest>
   <v1:disConfigSearchCriteria>
      <fromRange>0</fromRange>
      <toRange>20</toRange>
      <descending>name</descending>
      <disConfigConjunctionCriteriaItem>
         <nameAttributeCriteria>
            <value>Cisco*</value>
            <operator>EQUALS</operator>
         </nameAttributeCriteria>
         <nameAttributeCriteria>
            <value>Juniper*</value>
            <operator>EQUALS</operator>
         </nameAttributeCriteria>
         <conjunction>OR</conjunction>
      </disConfigConjunctionCriteriaItem>
   </v1:disConfigSearchCriteria>
</v1:findDisConfigRequest>

The conjunction appears at many levels in the find hierarchy. The conjunction at lower levels controls how the criteria at lower levels are evaluated logically.

In the following example the inner conjunction is OR because this request is designed to find any ScanRun that has discrepancy, regardless of severity. Notice the outer conjunction that has the value AND, this has no effect on the extended attribute criteria.

To change this find so it only finds scan runs that have a discrepancy of every severity, the inner conjunction on the disDiscrepancyCountsConjunctionCriteriaItem element would be changed to AND.

<v1:findDisScanRunRequest>
   <v1:disScanRunSearchCriteria>
      <v11:disScanRunConjunctionCriteriaItem>
         <v12:disScanRunExtendedCriteriaItem>
            <v14:counts>
               <v119:disDiscrepancyCountsConjunctionCriteriaItem>
                  <v120:criticalAttributeCriteria>
                     <v121:value>0</v121:value>
                     <v121:operator>GREATER_THAN</v121:operator>
                  </v120:criticalAttributeCriteria>
                  <v120:majorAttributeCriteria>
                     <v121:value>0</v121:value>
                     <v121:operator>GREATER_THAN</v121:operator>
                  </v120:majorAttributeCriteria>
                  <v120:minorAttributeCriteria>
                     <v121:value>0</v121:value>
                     <v121:operator>GREATER_THAN</v121:operator>
                  </v120:minorAttributeCriteria>
                  <v120:warningAttributeCriteria>
                     <v121:value>0</v121:value>
                     <v121:operator>GREATER_THAN</v121:operator>
                  </v120:warningAttributeCriteria>
                  <v120:conjunction>OR</v120:conjunction>
               </v119:disDiscrepancyCountsConjunctionCriteriaItem>
            </v14:counts>
         </v12:disScanRunExtendedCriteriaItem>
         <v12:conjunction>AND</v12:conjunction>
      </v11:disScanRunConjunctionCriteriaItem>
   </v1:disScanRunSearchCriteria>

Find Response

The Find response contains all the details of the entities that matched the attribute criteria. The response only contains the number of entities defined by the from an to range. Subsequent find operations may be called to get all the entities depending on the number of rows matching the search criteria and the from and to range specified.

<ns118:findDisConfigResponse>
   <ns118:disConfigs>
      <ns2:entityId>9612</ns2:entityId>
      <ns2:entityVersion>1</ns2:entityVersion>
      <ns4:tagsRef>
         <ns2:entityId>9584</ns2:entityId>
      </ns4:tagsRef>
      <ns4:tagsRef>
         <ns2:entityId>9586</ns2:entityId>
      </ns4:tagsRef>
      <ns7:parameterGroups>
         <ns2:entityId>9606</ns2:entityId>
         

…and so on.

 
      <ns7:enabled>YES</ns7:enabled>
      <ns7:dataSource>TRUE</ns7:dataSource>
      <ns7:startScanReady>true</ns7:startScanReady>
   </ns118:disConfigs>
</ns118:findDisConfigResponse>

Special Function Operations

There are a few Web Service API operations that do not follow the standard pattern and are designed for a special purpose. The special function operations are:

  • startScan

  • stopScan

  • getLatestScanStatus

  • submitDisDiscrepancyResolutionOperations

These operations are described in the following sections.

Start Scan

The startScan operation starts a scan for a given DisConfig entityId. This operation is identical to the Start Scan operation in the Network Integrity Web UI. The request expects a DisConfig entityId and the response contains the entityId of the DisScanRun that was created for the scan.

Example 26-15 Request:

<v1:startScanRequest>
   <v1:disConfigRef>
      <v11:entityId>9612</v11:entityId>
   </v1:disConfigRef>
</v1:startScanRequest>

Example 26-16 Response:

<ns118:startScanResponse>
   <ns118:disScanRunRef>
      <ns2:entityId>14721</ns2:entityId>
   </ns118:disScanRunRef>
</ns118:startScanResponse>

Stop Scan

The stopScan operation stops a scan for a given DisConfig entityId. This operation is identical to the Stop Scan operation in the Network Integrity Web UI. The request expects a DisConfig entityId and the response contains the entityId of the DisScanRun that was created for the scan.

Example 26-17 Request:

<v1:stopScanRequest>
   <v1:disConfigRef>
      <v11:entityId>9612</v11:entityId>
   </v1:disConfigRef>
</v1:stopScanRequest>

Example 26-18 Response:

<ns118:stopScanResponse>
   <ns118:disScanRunRef>
      <ns2:entityId>13846</ns2:entityId>
   </ns118:disScanRunRef>
</ns118:stopScanResponse>

Get Latest Scan Status

The getLatestScanStatus returns the status of the latest run of a scan. The operation is equivalent to the information displayed in the Status section of the Manage Scans page of the Network Integrity UI. Information In addition to the status of the scan the operation returns information about the number of addresses being discovered, the number of discrepancies found, and the start time and duration of the scan.

This method is more efficient to call to monitor the running of a scan rather than call findDisScanRun many times.

Example 26-19 Request:

<v1:getLatestScanStatusRequest>
   <v1:disConfigRef>
      <v11:entityId>9612</v11:entityId>
   </v1:disConfigRef>
</v1:getLatestScanStatusRequest

Example 26-20 Response (Running Scan)

<ns118:getLatestScanStatusResponse>
   <ns118:scanStatus>
      <ns120:discrepancySeverityCounts>
         <ns2:entityId>0</ns2:entityId>
         <ns2:entityVersion>0</ns2:entityVersion>
         <ns56:numberWarning>0</ns56:numberWarning>
         <ns56:numberMinor>0</ns56:numberMinor>
         <ns56:numberMajor>0</ns56:numberMajor>
         <ns56:numberCritical>0</ns56:numberCritical>
      </ns120:discrepancySeverityCounts>
      <ns120:discoveryWorkCounts>
         <ns121:totalNoOfWorkItems>2</ns121:totalNoOfWorkItems>
         <ns121:noOfCompletedWorkItems>0</ns121:noOfCompletedWorkItems>
         <ns121:noOfFailedWorkItems>0</ns121:noOfFailedWorkItems>
         <ns121:noOfInProgressWorkItems>2</ns121:noOfInProgressWorkItems>
         <ns121:startTime>07/16/2010 11:17:05</ns121:startTime>
         <ns121:duration/>
      </ns120:discoveryWorkCounts>
      <ns120:discrepancyWorkCounts>
         <ns121:totalNoOfWorkItems>0</ns121:totalNoOfWorkItems>
         <ns121:noOfCompletedWorkItems>0</ns121:noOfCompletedWorkItems>
         <ns121:noOfFailedWorkItems>0</ns121:noOfFailedWorkItems>
         <ns121:noOfInProgressWorkItems>0</ns121:noOfInProgressWorkItems>
         <ns121:duration/>
      </ns120:discrepancyWorkCounts>
      <ns120:jobStateString>Running</ns120:jobStateString>
      <ns120:discrepancyDetectionEnabled>true</ns120:discrepancyDetectionEnabled>
   </ns118:scanStatus>
</ns118:getLatestScanStatusResponse>

Example 26-21 Response (Completed Scan)

<ns118:getLatestScanStatusResponse>
         <ns118:scanStatus>
            <ns120:discrepancySeverityCounts>
               <ns2:entityId>15456</ns2:entityId>
               <ns2:entityVersion>1</ns2:entityVersion>
               <ns55:numberWarning>1</ns55:numberWarning>
               <ns55:numberMinor>0</ns55:numberMinor>
               <ns55:numberMajor>0</ns55:numberMajor>
               <ns55:numberCritical>0</ns55:numberCritical>
            </ns120:discrepancySeverityCounts>
            <ns120:discoveryWorkCounts>
               <ns121:totalNoOfWorkItems>2</ns121:totalNoOfWorkItems>
               <ns121:noOfCompletedWorkItems>2</ns121:noOfCompletedWorkItems>
               <ns121:noOfFailedWorkItems>0</ns121:noOfFailedWorkItems>
               <ns121:noOfInProgressWorkItems>0</ns121:noOfInProgressWorkItems>
               <ns121:startTime>07/16/2010 11:59:26</ns121:startTime>
               <ns121:endTime>07/16/2010 11:59:52</ns121:endTime>
               <ns121:duration>26s</ns121:duration>
            </ns120:discoveryWorkCounts>
            <ns120:discrepancyWorkCounts>
               <ns121:totalNoOfWorkItems>2</ns121:totalNoOfWorkItems>
               <ns121:noOfCompletedWorkItems>2</ns121:noOfCompletedWorkItems>
               <ns121:noOfFailedWorkItems>0</ns121:noOfFailedWorkItems>
               <ns121:noOfInProgressWorkItems>0</ns121:noOfInProgressWorkItems>
               <ns121:startTime>07/16/2010 11:59:52</ns121:startTime>
               <ns121:endTime>07/16/2010 11:59:55</ns121:endTime>
               <ns121:duration>3s</ns121:duration>
            </ns120:discrepancyWorkCounts>
            <ns120:jobStateString>Completed</ns120:jobStateString>
            <ns120:discrepancyDetectionEnabled>true</ns120:discrepancyDetectionEnabled>
         </ns118:scanStatus>
      </ns118:getLatestScanStatusResponse>

Submit Discrepancies For Resolution Processing

The submitDisDiscrepancyResolutionOperations operation takes a list of discrepancy entityIds and submits these discrepancies to be processed by a resolution action. This is the same as the Submit discrepancies operation in the Network Integrity Web UI.

The discrepancies submitted must have a discrepancy status of IDENTIFIED and have an Operation populated or else a fault is returned. The status and operation of the discrepancy can be updated using the updateDisDiscrepancy operation.

This operation is a two step operation in the Network Integrity Web UI to first add discrepancies to the queue, and then submit them. In the Web Service API this is a single operation.

If the operation is successful, the entityIds of the discrepancies submitted is returned in the response.

After submitting the discrepancies the status of the discrepancies is set to SUBMITTED.

Example 26-22 Request

<v1:submitDisDiscrepancyResolutionOperationsRequest>
   <!--1 or more discrepancies: -->
   <v1:disDiscrepancyRef>
      <v11:entityId>15448</v11:entityId>
   </v1:disDiscrepancyRef> 
</v1:submitDisDiscrepancyResolutionOperationsRequest>

Example 26-23 Response

<ns118:submitDisDiscrepancyResolutionOperationsResponse>
   <ns118:disDiscrepancyRef>
      <ns2:entityId>15448</ns2:entityId>
   </ns118:disDiscrepancyRef>
</ns118:submitDisDiscrepancyResolutionOperationsResponse>

Example 26-24 Failure (one or more discrepancies not in IDENTIFIED status)

<ns2:Fault>
   <faultcode>ns2:Server</faultcode>
   <faultstring>DISCREPANCY_RESOLUTION_INVALID_STATUS</faultstring>
   <detail>
      <ns127:crudFault>
         <ns119:rootStackTrace/>
      </ns127:crudFault>
   </detail>
</ns2:Fault>

High Level Scenarios

The following sections describe how to use the Web Service API in an end-to-end fashion.

Creating a Scan

A scan is created using the createDisConfig operation, but there may be data and entities to be created or retrieved before calling the createDisConfig operation.

Prerequisites:

  • A plugin entity id is required to create a scan. The list of discovery, import, and assimilation plugins that are deployed in the system can be determined by calling getAllDisInventoryImportPlugin, getAllDisNetworkDiscoveryPlugin, and getAllDisAssimilationPlugin.

  • The plug-in entity may define one or more plug-in parameters (for example, SnmpParameters) that it expects to be passed. If it does then the plug-in returned in the previous step has one or more specificationsRef elements in the response. The expected plug-in parameters can be determined by calling getSpecification to determine the available plug-in parameters. Some plug-in parameters are optional and some are mandatory.

    For more information about the parameters returned by getSpecification, refer to your plug-in or cartridge documentation.

  • If the Scan is to be tagged on creation then the Tag entity ids must be retrieved using one of getAllRootDisTags, getDisTag, createDisTag

  • If the Scan is to have Blackout schedules on creation then the Blackout entity ids must be retrieved using one of getAllDisBlackoutSchedule, getDisBlackoutSchedule, createDisBlackoutSchedule

The response from the createDisConfig operation, if successful, is an entity id for the scan. The entity id is used for deleting, retrieving, starting, and stopping the scan.

Starting, Stopping, and Monitoring a Scan

The Scan can be started using startScan operation and the DisConfig entity id that was returned when it was created. (It is also possible to do a findDisConfig operation to get the entity id).

The start scan operation returns the Scan run entity id that is used to get in the getDisScanRun operation to monitor the status and results of the scan.

It is also possible to monitor the scan progress using the DisConfig entity id and the getLatestScanStatus. This operation is more efficient and reports the current status of the scan along with other details.

An in-progress scan can be stopped using the stopScan operation and the DisConfig entity id. When the operation returns the scan is transitioned to STOPPING state, and asynchronously transitions to STOPPED when all scan processes have ended.

Retrieving Scan Results/Data

The starting point for retrieving scan results is the DisScanRun entity. The entity id of the DisScanRun is returned when the scan was started, or can be determined by performing the findDisScanRun operation.

If the scan successfully discovers data the DisScanRun has one or more resultGroups that contain one or more rootEntityRefsRef. These ids are used in the getRootEntity call to retrieve the root of the discovered data. The getRootEntity operation, unlike other get calls, accepts multiple entity ids for retrieving all root entities in a single call.

The getRootEntity operation does not retrieve the complete tree of results for performance reasons and to limit scope of entity traversal. The response from getRootEntity often contains references to other entities. These entities can be retrieved using the generic getResultEntity operation, or by type-specific get operations (getLogicalDevice, getEquipment, getPhysicalDevice, getLogicalDevice, getEquipmentHolder, and so on)

Most result data entities have specifications. To get details about the specification the entity is using, the getSpecification operation can be called using the specificationRef on the entity.

Working with Discrepancies

The starting point for working with discrepancies is the DisScanRun entity. The entity id of the DisScanRun is returned when the scan was started, or can be determined by performing the findDisScanRun operation.

The list of discrepancies created in discrepancy detection is in the DisScanRun entity as discrepanciesRef ids. The DisDiscrepancy entity can be retrieved using the getDisDiscrepancy operation passing the discrepanciesRef from the DisScanRun entity. The discrepancies can also be found using the findDisDiscrepancy operation with search criteria.

Several fields on the discrepancy, including the status, operation (Resolution Action), owner, priority, reasonForFailure, and notes can be updated using the updateDisDiscrepancy operation.

Discrepancies can be submitted for resolution by calling the submitDisDiscrepancyResolutionOperations operation. The operation takes a list of discrepancies to be submitted in the request. Discrepancies must be in the status of IDENTIFIED and have an operation populated to be submitted.

Network Integrity Web Service Samples

Network Integrity includes example requests and responses of calling the web service API. Find these examples in the Network Integrity Web Service Samples ZIP file.

Contents of the Network Integrity Web Service Samples ZIP File

Table 26-16 describes the directories, files, and file contents for the Network Integrity Web Service Samples ZIP file.

Table 26-16 Contents

Directory/File Description

build.xml

An example ANT build script that shows how to run the client with an SSL keystore as a VM argument.

WSDL-Documentation.html

Generated WSDL documentation that shows all the available operations. A short description of each operation is provided. Full WSDL source is included for reference.

IntegrityWebserviceSoapUIProject.xml

SoapUI Project File

integrity-schema\wsdl\ NetworkIntegrityControlService.wsdl

Web Service Definition (WSDL)

integrity-schema\referenceSchema

Supporting XML Schema files

integrity-schema\schema

Supporting XML Schema files

integrity-ws-client.jar

Jar file containing Java Client type generated from the WSDL

jaxb-bindings.xml

JAXB Binding file to adjust generated package names when generating client classes from WSDL. These bindings are required if not using the provided integrity-ws-client.jar and generating client class files using a web service client generation tool.

src\oracle\integrity\ws\client\NetworkIntegrityControlService.java

This is a client side proxy class to get port types. This is the class where policy files and other authentication details are set.

src\oracle\integrity\ws\test\SampleNIClient.java

An example client java class that makes a web service call.


Sample Java Client

Included in the Web Service Samples ZIP file is a sample java client. The sample java code is included in the src directory and contains:

  • a sample client side proxy for getting a port type and setting the required policies and authentication.

  • a client class that calls the getAllDisNetworkDiscoveryPlugin operation and prints the result to standard out.

To compile the sample JAVA code, the following JAR files are necessary:

  • weblogic.jar: available in WL_Home/server/lib/

  • wseeclient.jar: available in WL_Home/server/lib/

  • jrf.jar: available in MW_Home/oracle_common/modules/oracle.jrf_11.1.1/

  • integrity-ws-client.jar: included the Network Integrity Web Service Samples ZIP file.

Note:

The required web service policy, Wssp1.2-2007-Https-UsernameToken-Plain.xml is included in the wseeclient.jar.

To run the sample JAVA code, you must run it with a full installation of WebLogic Server and ADF, because the JAR files referenced during compile require other JAR files. Set your classpath to point to the above JAR files in their installed location on your system. This can be done by installing WebLogic and ADF on your development system or run the client on your Network Integrity server.

If you plan on running a Web service client to communicate with a Network Integrity server that does not have a valid SSL certificate, you must download your server certificate and save it to a file to be used by your client. Then use the following VM argument when running your client. In this example, a file called jssecacerts has the SSL key that was downloaded.

 -Djavax.net.ssl.trustStore=jssecacerts

Sample Soap UI Project

A SoapUI project is provided in the Cartridge Developer package to give examples of all the Web Service API calls and examples of the responses. The SoapUI project is used to test various Web Service API call scenarios.

To install the Soap UI, use the following procedure:

  1. Download and Install SoapUI 3.5.1 (newer versions of SoapUI may work with the bundled project file, but it has not been tested)

  2. Launch SoapUI and select the menu option File -> Import Project

  3. Select the file IntegrityWebserviceSoapUIProject.xml and click Open

Also in the project is a NetworkIntegrityControlMockService that simulates the real Web Service API. For each operation there is one or more example responses provided in the mock service. The number of example requests in the binding does not always match the number of responses because the responses would be the same structure with a different id returned (for example, Create Blackout Response).

You can use the provided example requests or create new requests right-clicking the operation and selecting ”New Request”. This creates a new request with all fields populated with a question mark. Many of the example requests in the project require modification to execute successfully because the entityIds in the example does not match other systems.

The NetworkIntegrityControlMockService is used to view examples of Web Service API responses for different scenarios. The mock service can also be started to respond to Web Service API calls with mock responses. Refer to SoapUI documentation for more details if this is desired.

Submitting Request to the Server

To submit a request to the server you must do the following:

  1. Ensure the request is valid and all mandatory attributes are set.

  2. Ensure the username and password are set in the request. See the next section on how to add the username and password to the request for how this is done.

  3. Add a new endpoint by clicking on the drop down at the top of the request and select add new endpoint.

  4. Add a new endpoint with the following format:

    https://<Managed_Server>:<Port>/NetworkIntegrityApp-NetworkIntegrityControlWebService-context-root/NetworkIntegrityControlServicePortType
    
  5. Click Play to submit the request.

Specifying User Name and Password in Request

To add the user name and password to a request.

  1. Click Aut tab at the bottom of the request.

  2. Enter the Username and Password that has access to login to the Network Integrity Web UI.

  3. Right click the request and select Add WSS Username Token.

  4. Accept the default PasswordText and select OK.

    The following structure is added to the request.

    <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">                            
       <wsse:UsernameToken wsu:Id="UsernameToken-4" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">                      
          <wsse:Username>niuser</wsse:Username>                                                                                                                          
          <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">niuser123</wsse:Password>                
          <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">ZS2K4yCoqOoQg6KL9DetBw==</wsse:Nonce>
          <wsu:Created>2010-09-13T01:21:17.578Z</wsu:Created>                                                                                                            
       </wsse:UsernameToken>                                                                                                                                             
    </wsse:Security>
     
    
  5. Delete the Nonce and Created elements in the above example (highlighted in bold) to reduce errors on future calls.