This chapter provides information about the Oracle Communications Network Integrity Web service.
This chapter contains the following sections:
The Network Integrity Web service 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.
At a high-level the Network Integrity 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 operations that can be done in the Network Integrity UI can be done through the Web service. One operation that is currently not possible is to create or update the Import System configured in the Network Integrity UI. This is a one-time setup that must be done in the Network Integrity UI and cannot be done through the Web service.
The Network Integrity Web service is standards based using JAX-WS over HTTP.
The Network Integrity Web service uses the same security as the Network Integrity UI. Any user who is able to login into the Web UI can also use the Web service. This is assigned using NetworkIntegrityRole.
Note:
All Network Integrity Web service requests (Soap UI requests and automated Web service requests) must include a time stamp to access Network Integrity Web service.The Network Integrity Web service 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.
For Network Integrity entity, attribute and relationship names, see Network Integrity Information Model Reference.
For cartridge entity, parameter, and relationship names and descriptions, see your cartridge documentation.
Web service operations take immediate effect in the system and therefore there is scope for collisions with users working in the Network Integrity UI. If the Web service operation collides with an update that another user has done in the Network Integrity 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 Network Integrity UI, the user receives an error when that user attempt to save changes. If two clients (Web service client or Network Integrity UI user) are trying to update/delete the same entity, the last client to commit changes receives the error.
All Network Integrity Web service operations must include a time stamp to satisfy the Web service security policy. See "Security" for more information.
Table 10-1 describes the DisConfig operations. See Network Integrity Information Model Reference for more information on the DisConfig entity.
Table 10-1 DisConfig Operations
| Operation | Description |
|---|---|
|
createDisConfig |
This operation creates a new scan in the system (DisConfig is equivalent to scan in the Network Integrity 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 scan 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. 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 10-2 describes the DisScanRun operations. See Network Integrity Information Model Reference for more information on the DisScanRun entity.
Table 10-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 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 10-3 describes the DisBlackoutSchedule operations. See Network Integrity Information Model Reference for more information on the DisBlackoutSchedule entity.
Table 10-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 10-4 describes the DisTag operations. See Network Integrity Information Model Reference for more information on the DisTag entity.
| 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 10-5 describes the DisDiscrepancy operations. See Network Integrity Information Model Reference for more information on the DisDiscrepancy entity.
Table 10-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 operation is the same as the criteria available in the Network Integrity UI (DisScanRun is equivalent to scan results in the Network Integrity 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 DisDiscrepancy are required in the request, not just the values changing. The valid values of status are:
The operation value is equivalent to resolution action value in the Network Integrity UI and the valid values are dependent on what discrepancy resolution are currently installed in the system. A fault with a faultstring is returned if the update fails. |
Table 10-6 describes the DisPlugin operations. See Network Integrity Information Model Reference for more information on the DisPlugin entity.
Table 10-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 10-7 describes the DefaultDisInvetoryConfig operations.
Table 10-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 UI. The Import System cannot be created or updated through the Web service; it must be done using the Network Integrity UI. |
Table 10-8 describes the 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 set 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 set 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 UI). A fault with a faultstring is returned if the operation fails. |
Table 10-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 10-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. |
Most of the operations defined in the Network Integrity Web service follow the naming pattern of:
However, a few of the Web service operations do not follow this pattern. See "Network Integrity Web Service Special Function Operations" for more information.
Each 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 Network Integrity UI.
The request for each 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 from each create operation 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 a create operation fails, the response contains a fault with a faultCode, faultString, and extra CrudFault details.
<v1:createDisTagRequest>
<v1:disTag>
<v13:name>Sample Tag</v13:name>
<v13:description>Created through Web Service</v13:description>
</v1:disTag>
</v1:createDisTagRequest>
<ns118:createDisTagResponse>
<ns118:disTagRef>
<ns2:entityId>9584</ns2:entityId>
</ns118:disTagRef>
</ns118:createDisTagResponse>
Each get operation retrieves 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 each 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 from each get operation is named get<EntityType>Response and contains the details of the entity retrieved from the system.
If a get operation fails, the response contains a fault with a faultCode, faultString, and extra CrudFault details.
<v1:getDisTagRequest>
<v1:disTagRef>
<v11:entityId>9586</v11:entityId>
</v1:disTagRef>
</v1:getDisTagRequest>
<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 10-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>
Each get operation supports the following 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
Each get all operation retrieves 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.
These operations are only available for entities that would not typically have many entries in the system and that do not support a find operation.
The request for each get all operation is named getAll<EntityType>Request. The request does not support any request parameters.
The response from each get all operation is named getAll<EntityType>Response and contains the details of all the entities retrieved from the system.
If a get all operation fails, the response contains a fault with a faultCode, faultString, and extra CrudFault details. Since the get all operations do not take any input parameters, they should only fail due to environment or authentication issues.
<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>
Each delete operation removes an entity from the system. For example, the deleteDisBlackoutSchedule operation removes a particular blackout schedule from the system.
If successful, the result of a delete operation is immediately viewable in the Network Integrity UI.
The request for each 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 10-1, "DisConfig Operations" for more information.The response from each delete operation is named delete<EntityType>Response and contains the entityId of the entity deleted, which matches the id in the request.
If a delete operation fails, the response contains a fault with a faultCode, faultString, and extra CrudFault details.
<v1:deleteDisTagRequest>
<v1:disTagRef>
<v11:entityId>9579</v11:entityId>
</v1:disTagRef>
</v1:deleteDisTagRequest>
<ns118:deleteDisTagResponse>
<ns118:disTagRef>
<ns2:entityId>9579</ns2:entityId>
</ns118:disTagRef>
</ns118:deleteDisTagResponse>
Each 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 Network Integrity UI.
The request for each 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
Each response from the update operation is named update<EntityType>Response and contains the entityId of the updated entity if the operation was successful.
If the update operation fails, the response contains a fault with a faultCode, faultString, and extra CrudFault details.
<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>
<ns118:updateDisTagResponse>
<ns118:disTagRef>
<ns2:entityId>9586</ns2:entityId>
</ns118:disTagRef>
</ns118:updateDisTagResponse>
Each 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.
Each find operation is equivalent in capability to the Search screens in the Network Integrity UI.
The request for each 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, etc.)
Conjunction Criteria (AND/OR)
Each find operation supports the following entity types:
DisConfig
DisScanRun
DisDiscrepancy
The fromRange and toRange are used to limit the number of rows returned to a client. These fields support paging in UIs through the Web service. 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>
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>
The attribute criteria specifies 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, etc.).
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, etc.
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, see 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 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 ’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 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 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>
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.
Table 10-10 shows the allowed search operators for DisConfig attributes.
Table 10-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 |
Table 10-11, Table 10-12, and Table 10-13 show the allowed search operators for DisScanRun.
Table 10-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 10-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 10-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 |
Table 10-14 and Table 10-15 show the allowed search operators for DisDiscrepancy.
Table 10-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 10-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 |
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 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 scan runs that started after the August 11th, 2010 10:00 am. Because the AFTER operator is used, scans that match this start time exactly are not included in the response. If operator ON_OR_AFTER was used then exact match start time scans are 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>
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 scans 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>
Each 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>
.
.
.
<ns7:enabled>YES</ns7:enabled>
<ns7:dataSource>TRUE</ns7:dataSource>
<ns7:startScanReady>true</ns7:startScanReady>
</ns118:disConfigs>
</ns118:findDisConfigResponse>
There are a few Network Integrity Web service operations that do not follow the standard pattern and are designed for a special purpose.
The Network Integrity Web service special function operations are:
The startScan operation starts a scan for a given DisConfig entityId. This operation is identical to the start scan operation in the Network Integrity UI. The request expects a DisConfig entityId and the response contains the entityId of the DisScanRun that was created for the scan.
<v1:startScanRequest>
<v1:disConfigRef>
<v11:entityId>9612</v11:entityId>
</v1:disConfigRef>
</v1:startScanRequest>
The stopScan operation stops a scan for a given DisConfig entityId. This operation is identical to the stop scan operation in the Network Integrity UI. The request expects a DisConfig entityId and the response contains the entityId of the DisScanRun that was created for the scan.
<v1:stopScanRequest>
<v1:disConfigRef>
<v11:entityId>9612</v11:entityId>
</v1:disConfigRef>
</v1:stopScanRequest>
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. 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.
<v1:getLatestScanStatusRequest>
<v1:disConfigRef>
<v11:entityId>9612</v11:entityId>
</v1:disConfigRef>
</v1:getLatestScanStatusRequest
Example 10-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 10-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>
The submitDisDiscrepancyResolutionProcessing 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 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 UI to first add discrepancies to the queue, and then submit them. In the Web service 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.
<v1:submitDisDiscrepancyResolutionOperationsRequest>
<!--1 or more discrepancies: -->
<v1:disDiscrepancyRef>
<v11:entityId>15448</v11:entityId>
</v1:disDiscrepancyRef>
</v1:submitDisDiscrepancyResolutionOperationsRequest>
<ns118:submitDisDiscrepancyResolutionOperationsResponse>
<ns118:disDiscrepancyRef>
<ns2:entityId>15448</ns2:entityId>
</ns118:disDiscrepancyRef>
</ns118:submitDisDiscrepancyResolutionOperationsResponse>
The following sections describe how to use the Web service in an end-to-end fashion.
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, see 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.
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 from that you can use 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.
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.
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 includes example requests and responses of calling the Web service. Find these examples in the Network Integrity Web Service Samples ZIP file.
Table 10-16 describes the directories, files, and file contents for the Network Integrity Web Service Samples ZIP file.
Table 10-16 Network Integrity Web Service Samples ZIP File 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. |
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
A SoapUI project is provided in the Cartridge Developer package to give examples of all the Web service calls and examples of the responses. The SoapUI project tests various Web service call scenarios.
To install the Soap UI, use the following procedure:
Download and Install SoapUI 3.5.1 (newer versions of SoapUI may work with the bundled project file, but it has not been tested)
Start the SoapUI application.
From the File menu, select Import Project.
Select the IntegrityWebserviceSoapUIProject.xml file and click Open.
Also in the project is a NetworkIntegrityControlMockService that simulates the real Web service. 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 views examples of Web service responses for different scenarios. The mock service can also be started to respond to Web service calls with mock responses. See the SoapUI documentation for more information.
To submit a request to the server you must do the following:
Ensure the request is valid and all mandatory attributes are set.
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.
Add a new endpoint by clicking on the drop down at the top of the request and select add new endpoint.
Add a new endpoint with the following format:
https://Managed_Server:Port/NetworkIntegrityApp-NetworkIntegrityControlWebService-context-root/NetworkIntegrityControlServicePortType
Click Play to submit the request.
To add the user name and password to a request.
Click Aut tab at the bottom of the request.
Enter the user name and password that has access to login to the Network Integrity UI.
Right click the request and select Add WSS Username Token.
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>
Delete the Nonce and Created elements in the above example (highlighted in bold) to reduce errors on future calls.