3 Working with the Network Resource Management Web Service
This chapter provides information about the Oracle Communications Unified Inventory Management (UIM) Network Resource Management (NRM) Web Service.
Note:
If you use UIM cloud native deployment for updating configuration files, refer to "Customizing UIM Configuration Properties" in UIM Cloud Native Deployment Guide.
About the NRM Web Service
Note:
Before reading about the NRM Web Service, read UIM Concepts to have an understanding of UIM.
The NRM Web Service enables an external system to manage entities in UIM by supporting operations that enable you to:
-
Create, find, update, and delete entities in UIM
-
Reserve and unreserve resource entities in UIM
-
Find or create a reservation in UIM when reserving resource entities
-
Find or delete a reservation in UIM when unreserving resource entities
-
-
Update reservations in UIM
-
Associate and disassociate entities in UIM
-
Import and export entities into and from UIM
About the Web Service Packaging
The NRM Web Service is packaged in the inventory.ear file, within the InventoryWS.war file. When the installer deploys the inventory.ear file, the NRM Web Service is automatically deployed and ready to use.
Note:
The InventoryWS.war file includes all of the Service Fulfillment Web Service operations as well. See "Working with the Service Fulfillment Web Service" for information about these operations.
About the WSDL and Schema Files
The NRM Web Service is defined by the InventoryWS.wsdl file and is supported by several schema files. The WSDL file and supporting schema files are located in the UIM_SDK_Home/webservices/schema_inventory_webservice.zip file.
About the WSDL File
Within ZIP file, the WSDL file is located in the ora_uim_webservices/wsdl directory. The WSDL file defines several operations. Each web service operation defines a request, a response, and the possible faults that can be thrown. For example, the WSDL file defines the following for the CreateEntity operation:
-
createEntityRequest
-
createEntityResponse
-
createEntityFault
-
inventoryFault
-
validationFault
The request, response, and faults each define an XML structure that is defined in the supporting schema files. The following excerpts show how an XML structure defined in the WSDL correlates to the supporting schema files.
For example, the WSDL file defines and references the invnsrm namespace (bolded):
xmlns:invnsrm="http://xmlns.oracle.com/communications/inventory/webservice/nsrm" . . . targetNamespace . . . <xsd:import namespace="http://xmlns.oracle.com/communications/inventory/webservice/nsrm" schemaLocation="./schemas/NSRMMessages.xsd"/> . . . <wsdl:message name="CreateEntityRequest"> <wsdl:part name="CreateEntityRequest" element="invnsrm:createEntityRequest"> </wsdl:part> </wsdl:message>
This tells you that the createEntityRequest XML structure is defined in the schema file that defines the specified namespace as its target namespace. A search for the specified namespace reveals that NSRMMessages.xsd defines the referenced namespace as its target namespace.
After you determine which schema file defines the XML structure that the WSDL file references, you can navigate through the schema files to determine child XML structures and elements.
About the Schema Files
Several schema files support the NRM Web Service. These schemas are categorized as reference schemas, web service schemas, and business schemas.
Reference Schemas
Within the ZIP file, the reference schemas are located in the ora_uim_webservices/wsdl/referenceSchemas directory. The reference schemas define common elements used by more than one operation. So, the elements are defined in one place and then referenced.
The reference schemas are:
-
InventoryCommon.xsd
-
InventoryFaults.xsd
-
FaultRoot.xsd
Web Service Schemas
Within the ZIP file, the web service schemas are located in the ora_uim_webservices/wsdl/schemas directory. The web service schemas define elements specific to the web service, such as the request structures, the response structures, and any fault structures.
The web service schema is defined in the NRMMessages.xsd file.
Note:
The web service schema uses the type-mapping.xsdconfig file to map XML namespaces to Java packages.
Business Schemas
Within the ZIP file, the business schemas are located in the ora_uim_business/schemas directory. Each web service operation wraps a call (or multiple calls) to the UIM business layer, which is exposed through APIs. The wrapped APIs are the same APIs that the UIM UI calls in response to user input. The business layer APIs are based on functional area, as are the business schemas.
The business schemas are:
-
Activity.xsd
-
BusinessInteraction.xsd
-
Configuration.xsd
-
Connectivity.xsd
-
CustomNetworkAddress.xsd
-
CustomObject.xsd
-
Entity.xsd
-
InventoryGroup.xsd
-
IPAddress.xsd
-
LogicalDevice.xsd
-
MediaStream.xsd
-
Network.xsd
-
NetworkAddress.xsd
-
Number.xsd
-
Party.xsd
-
PhysicalDevice.xsd
-
Place.xsd
-
Property.xsd
-
PropertyLocation.xsd
-
Role.xsd
-
Service.xsd
-
Specification.xsd
-
Structure.xsd
-
TNBlockModelType.xsd
Note:
The API schemas use the xmlbeans-mapping.xsdconfig file to map XML namespaces to Java packages.
CreateEntity
The CreateEntity operation enables external systems to send a request to UIM to create certain entities in UIM.
createEntityRequest
You must specify the type of entity to create based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use to define the entity you are creating. Table 3-1 lists the valid entity types and the schema files in which they are defined.
Table 3-1 Entity Types for CreateEntity
Entity Type | Schema File |
---|---|
ActivityType |
Activity.xsd |
CustomNetworkAddressType |
CustomNetworkAddress.xsd |
CustomObjectType |
CustomObject.xsd |
EquipmentType |
PhysicalDevice.xsd |
FlowIdentifierType |
LogicalDevice.xsd |
InventoryGroupType |
InventoryGroup.xsd |
IPv4AddressType |
IPAddress.xsd |
IPv6AddressType |
IPAddress.xsd |
IPSubnetType |
IPAddress.xsd |
LogicalDeviceType |
LogicalDevice.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
PlaceType |
Place.xsd |
TelephoneNumberType |
Number.xsd |
Note:
PlaceType represents a GeographicLocation, which is a specialization of the abstract Place entity. See Oracle Communications Information Model Reference for more information.
Multiple Entities
You can create multiple entities per request by specifying one or more <entity> elements; however, all <entity> elements must specify the same entity type per request. For example, you can create multiple logical devices with a single request, and you can create multiple logical device accounts with a single request, but you cannot create multiple logical devices and multiple logical device accounts with a single request.
Optional Elements
You can specify an existing inventory group with which to associate the created entities. If you specify an inventory group that does not exist in UIM, an error is thrown.
You can specify parameters that define name/value pairs, which you can use with custom code to extend the operation. CreateEntity does not process specified parameters unless customized to do so. See "Customizing the Web Service Operations" for more information.
Example
Example 3-1 shows a request that specifies an entity type of TelephoneNumberType, which defines telephone number-specific elements such as <tn:rangeFrom> and <tn:rangeTo>.
This particular request:
-
Creates a range of telephone numbers based on the usTelephoneNumber specification
-
Adds the characteristics of tnCountryCode, winback, responsibleProvider, and tnType to each of the telephone numbers created, as specified by the property name element
-
Sets the characteristic values, as specified by the property value element
-
Associates the created telephone numbers with the MobileServingArea inventory group
Example 3-1 createEntityRequest
<nsrm:createEntityRequest> <nsrm:entity xsi:type="tn:TelephoneNumberType"> <tn:specification> <spec:name>usTelephoneNumber</spec:name> </tn:specification> <tn:rangeFrom>9729630001</tn:rangeFrom> <tn:rangeTo>9729630020</tn:rangeTo> <tn:description>Owned Number</tn:description> <tn:property> <prop:name>tnCountryCode</prop:name> <prop:value>1</prop:value> </tn:property> <tn:property> <prop:name>winback</prop:name> <prop:value>false</prop:value> </tn:property> <tn:property> <prop:name>responsibleProvider</prop:name> <prop:value>AT&T</prop:value> </tn:property> <tn:property> <prop:name>tnType</prop:name> <prop:value>OWNED</prop:value> </tn:property> </nsrm:entity> <nsrm:inventoryGroup> <ig:specification> <spec:name>MobileServingArea</spec:name> </ig:specification> <ig:name>North Dallas</ig:name> </nsrm:inventoryGroup> <nsrm:parameter> <bi:name></bi:name> <bi:value></bi:value> </nsrm:parameter> </nsrm:createEntityRequest>
createEntityResponse
createEntityResponse returns information about the created entities. The information returned in the response is dependent upon the entity types that were created, as specified in the request.
createEntityResponse returns an error message when:
-
The request specifies a specification that does not exist in UIM
-
The request specifies an inventory group that does not exist in UIM
-
The call to the UIM API fails
FindEntity
The FindEntity operation enables external systems to send a request to UIM to find and return certain entities in UIM, based on specified search criteria.
findEntityRequest
You must specify search criteria to find the entities to retrieve. You have the choice of specifying search criteria one of two ways. With either choice, you must specify the type of entity to find based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use as search criteria to find entities. Table 3-2 lists the valid entity types and the schema files in which they are defined.
Table 3-2 Entity Types for FindEntity
Entity Type | Schema File |
---|---|
ActivityType |
Activity.xsd |
CustomNetworkAddressType |
CustomNetworkAddress.xsd |
CustomObjectType |
CustomObject.xsd |
EquipmentType |
PhysicalDevice.xsd |
FlowIdentifierType |
LogicalDevice.xsd |
InventoryGroupType |
InventoryGroup.xsd |
IPv4AddressType |
IPAddress.xsd |
IPv6AddressType |
IPAddress.xsd |
IPSubnetType |
IPAddress.xsd |
LogicalDeviceType |
LogicalDevice.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
PlaceType |
Place.xsd |
TelephoneNumberType |
Number.xsd |
The choices are:
-
<entity>
In this search option, you specify the entity type and use the entity-specific elements to specify search criteria.
For each entity type, the <entity> structure varies. For example, TelephoneNumberType defines <rangeFrom> and <rangeTo>, but none of the other entity types define these elements.
Even though the <entity> structure varies per entity type, the following elements are common across most entity types:
-
specification
The search returns entities created from the specified specification.
-
id
The search returns the entity with the specified id. (InventoryGroupType is only entity type with no id; the inventory group name is the id.)
-
name
The search returns entities with the specified name.
-
description
The search returns entities with the specified description.
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
Note:
Within each EntityType structure, the property element defines name, value, and action. However, action is not used; rather, the NRM Web Service operations always assume an operand of EQUALS.
-
-
-
<criteria>
In this search option, you specify the entity type and use the following search criteria:
-
specification
The search returns entities created from the specified specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PORTED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="TRANSITIONAL"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
If searching for telephone number entities, you can specify the inventoryGroup geographicLocation and the search returns telephone number entities associated with inventory groups that are associated with the specified place. If searching for entities other than telephone numbers, the inventoryGroup geographicLocation is not used.
-
geographicLocation
The search returns inventory group entities associated with the specified place. If searching for entities other than inventory groups, geographicLocation is not used.
-
quantity
The search returns the specified quantity of entities. For example, if the search finds 1,000 entities and the criteria specifies a quantity of 50, the first 50 entities found are returned. If the quantity is not given, the default retrieved is 10. If you want more than 10 entities returned, then a quantity must be given. Also, this quantity must be less than the maximum query range provided in the system-config.properties file for the uim.ws.search.query.range property setting. This setting can be set for all entities or for specific entities. Refer to UIM System Administrator's Guide for more information on this property setting.
-
reservation
If you specify reservation information, FindEntity also reserves any found entities. See "ReserveEntity" for more information.
-
lock
Row locking is used to optimize concurrent resource allocation for consumable entities.
If you specify row-locking information, FindEntity does not release locked entities; you must manually release locked entities by calling the RowLockManager.releaseLock() method, or wait for the timer to release locked entities.
If you specify row-locking information for entities that are not consumable (Geographic Location and Inventory Group), an error is thrown.
See Optimizing Concurrent Resource Allocation in UIM Developer's Guide for more information about row locking, and see the Javadoc for information about the RowLockManager.releaseLock() method.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
-
Enumerated operand with which to evaluate the specified characteristic and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
Multiple Entities
You specify one entity type to search for per request. For example, you can search for logical devices with a single request, and you can search for logical device accounts with a single request, but you cannot search for logical devices and logical device accounts with a single request.
Examples
Example 3-2 shows a request that specifies an entity type of TelephoneNumberType, and uses the telephone number-specific element of <tn:id> to search for the 9729630012 telephone number created from the usTelephoneNumber specification.
Note:
Example 3-2 shows all of the telephone-number specific elements, even though they are not being used. Your requests do not need to include optional, unused elements; they are shown here as an example of entity-specific elements.
Example 3-2 findEntityRequest
<nsrm: findEntityRequest > <ent:entity xsi:type="tn:TelephoneNumberType"> <tn:specification> <spec:name>usTelephoneNumber</spec:name> </tn:specification> <tn:id>9729630012</tn:id> <tn:name/> <tn:rangeFrom/> <tn:rangeTo/> <tn:description/> <tn:state/> <tn:startDate/> <tn:endDate/> <tn:property/> <prop:name/> <prop:value/> </tn:property> </ent:entity> </nsrm: findEntityRequest >
Example 3-3 shows a request that specifies an entity type of TelephoneNumberType, but the telephone number-specific elements are not used to specify the search criteria (nor are they shown). Rather, this example specifies search criteria to find telephone numbers created from the usTelephoneNumber specification.
This request specifies row-locking information that indicates to lock and return four telephone numbers.
Note:
Example 3-3 shows all of the optional search criteria elements, even though they are not all being used. Your requests do not need to include optional, unused elements; they are shown here as an example of the possible search criteria elements.
Example 3-3 findEntityRequest
<nsrm:findEntityRequest> <nsrm:criteria> <ent:entityType xsi:type="tn:TelephoneNumberType"> <!-- tn-specific elements are not shown --> </ent:entityType> <ent:specification> <spec:name>usTelephoneNumber</spec:name> </ent:specification> <ent:adminState/> <ent:assignmentState/> <ent:inventoryGroup/> <ig:geographicPlace/> </ent:inventoryGroup> <ent:geographicPlace/> <ent:quantity/> <ent:reservation/> <ent:lock> <ent:lockAllOrNone>true</ent:lockAllOrNone> <ent:quantity>4</ent:quantity> </ent:lock> <ent:criteriaItem/> <ent:property/> </nsrm:criteria> </nsrm:findEntityRequest>
findEntityResponse
findEntityResponse returns the found entities, based on the search criteria specified in the request. The information returned in the response is dependent upon the entity types that were searched for and subsequently found.
If you specified reservation information in the request, reservation information is also returned.
findEntityResponse returns an error message when:
-
The request specifies a lock policy for the non-consumable entities of Geographic Location or Group Inventory
-
The request specifies a lock policy that specifies the number of resources to lock, and there are not enough resources available to lock
-
The call to the UIM API fails
FindTNBlock
The FindTNBlock operation enables external systems to send a request to UIM to find and return telephone number blocks in UIM, based on specified search criteria.
findTNBlockRequest
You must specify search criteria to find the telephone number blocks to retrieve. In the search criteria, you must specify the entity type of TelephoneNumberType, which is defined in the Number.xsd schema file.
In the <criteria> search option, you specify the entity type (TelephoneNumberType) and use the following search criteria:
-
specification
The search returns entities created from the specified Telephone Number specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="TRANSITIONAL"/> <xs:enumeration value="PORTED"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
If searching for telephone number entities, you can specify the inventoryGroup and the search returns telephone number entities associated with inventory groups.
-
(optional) quantity
The search returns the specified quantity of telephone number block. For example, if the search finds 300 telephone number blocks and the criteria specifies a quantity of 50, the first 50 telephone number blocks found are returned.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
Example
Example 3-4 shows a request that specifies an entity type of TelephoneNumberType to search for a telephone number block of size 10 for the BATTNSpec specification.
Example 3-4 findTNBlockRequest
<nsrm:findTNBlockRequest> <nsrm:criteria> <ent:entityType xsi:type="tn:TelephoneNumberType"></ent:entityType> <ent:specification> <spec:name>BATTNSpec</spec:name> </ent:specification> <ent:assignmentState>UNASSIGNED</ent:assignmentState> <ent:adminState>INSTALLED</ent:adminState> <ent:inventoryGroup> <gro:name>NORTH_AMERICA</gro:name> </ent:inventoryGroup> <ent:criteriaItem> <ent:name>serviceSpec</ent:name> <ent:value xsi:type="xs:string">BATServiceSpec</ent:value> <ent:operator>EQUALS</ent:operator> </ent:criteriaItem> <ent:serviceSpec>BATServiceSpec</ent:serviceSpec> <ent:criteriaItem> <ent:name>CONDITION_TYPE</ent:name> <ent:value xsi:type="xs:string">INFORMATIONAL</ent:value> <ent:operator>EQUALS</ent:operator> </ent:criteriaItem> <ent:criteriaItem> <ent:name>rangeFrom</ent:name> <ent:value xsi:type="xs:string">1</ent:value> <ent:operator>GREATER_THAN_EQUAL</ent:operator> </ent:criteriaItem> <ent:criteriaItem> <ent:name>rangeTo</ent:name> <ent:value xsi:type="xs:string">100000000</ent:value> <ent:operator>LESS_THAN_EQUAL</ent:operator> </ent:criteriaItem> <ent:criteriaItem> <ent:name>blockSize</ent:name> <ent:value xsi:type="xs:string">10</ent:value> <ent:operator>EQUALS</ent:operator> </ent:criteriaItem> <ent:quantity>50</ent:quantity> </nsrm:criteria> </nsrm:findTNBlockRequest>
findTNBlockResponse
findTNBlockResponse returns the found telephone number blocks, based on the search criteria specified in the request.
findTNBlockResponse returns an error message when:
-
The request does not find the specified Inventory Group. In this case, the following error message is displayed:
No InventoryGroups found with criteria.
-
The call to the UIM API fails
UpdateEntity
The UpdateEntity operation enables external systems to send a request to UIM to update certain entities in UIM.
updateEntityRequest
You must specify the type of entity to update based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use to specify what to update. Table 3-3 lists the valid entity types and the schema files in which they are defined.
Table 3-3 Entity Types for UpdateEntity
Entity Type | Schema File |
---|---|
ActivityType |
Activity.xsd |
CustomNetworkAddressType |
CustomNetworkAddress.xsd |
CustomObjectType |
CustomObject.xsd |
FlowIdentifierType |
LogicalDevice.xsd |
InventoryGroupType |
InventoryGroup.xsd |
IPv4AddressType |
IPAddress.xsd |
IPv6AddressType |
IPAddress.xsd |
IPSubnetType |
IPAddress.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
LogicalDeviceType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
PlaceType |
Place.xsd |
TelephoneNumberType |
Number.xsd |
You must specify the same entity type twice: First, within the <entityDetails> element to specify the data to update; and second, within the <entitySearchCriteria> element to find the entities to update.
<entitySearchCriteria> defines the following search criteria:
-
specification
The search returns entities created from the specified specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PORTED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="TRANSITIONAL"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
If searching for telephone number entities, you can specify the inventoryGroup geographicLocation and the search returns telephone number entities associated with inventory groups that are associated with the specified place. If searching for entities other than telephone numbers, the inventoryGroup geographicLocation is not used.
-
geographicLocation
The search returns inventory group entities associated with the specified place. If searching for entities other than inventory groups, geographicLocation is not used.
-
quantity
The search returns the specified quantity of entities. For example, if the search finds 1,000 entities and the criteria specifies a quantity of 50, the first 50 entities found are returned.
-
reservation
If you specify reservation information, UpdateEntity ignores it; FindEntity is the only operation that uses the reservation element. See "FindEntity" for more information.
-
lock
Row locking is used to optimize concurrent resource allocation for consumable entities.
If you specify row-locking information, UpdateEntity releases locked entities; you do not need to manually release locked entities by calling the RowLockManager.releaseLock() method, or wait for the timer to release locked entities.
If you specify row-locking information for entities that are not consumable (Geographic Location and Inventory Group), an error is thrown.
See Optimizing Concurrent Resource Allocation in UIM Developer's Guide for more information about row locking.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of characteristic
-
Value of specified characteristic
-
Enumerated operand with which to evaluate the specified characteristic and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
Multiple Entities
You specify one <entityDetails> element per request, and one <entitySeachCriteria> element per request. For example, if the search criteria that <entitySearchCriteria> specifies returns 50 records, all 50 records are updated with the same data that <entityDetails> specifies.
Optional Elements
You can specify parameters that define name/value pairs, which you can use with custom code to extend the operation. UpdateEntity does not process specified parameters unless customized to do so. See "Customizing the Web Service Operations" for more information.
Examples
Example 3-5 shows a request that specifies an entity type of TelephoneNumberType and that specifies to update the description to Update for Testing. The request then specifies an entity type of TelephoneNumberType a second time to specify the search criteria to find the entities to update. In this example, the search criteria is to find telephone numbers created from the usTelephoneNumber specification.
Example 3-5 updateEntityRequest and TelephoneNumberType
<nsrm:updateEntityRequest> <nsrm:entityDetails xsi:type="tn:TelephoneNumberType"> <tn:description>Update for Testing</tn:description> </nsrm:entityDetails> <ent:entitySearchCriteria> <ent:entityType xsi:type="tn:TelephoneNumberType" /> <ent:specification> <spec:name>usTelephoneNumber</spec:name> </ent:specification> </ent:entitySearchCriteria> <nsrm:parameter> <bi:name></bi:name> <bi:value></bi:value> </nsrm:parameter> </nsrm:updateEntityRequest>
Example 3-6 shows a request that specifies an entity type of ActivityType and that specifies the activity as complete. The request then specifies an entity type of ActivityType a second time to specify the search criteria to find the entities to update. In this example, the search criteria finds an activity by its name.
Example 3-6 updateEntityRequest and ActivityType
<nsrm:updateEntityRequest> <nsrm:entityDetails xsi:type="act:ActivityType"> <act:action>complete</act:action> </nsrm:entityDetails> <nsrm:entitySearchCriteria xsi:type="act:ActivitySearchCriteriaType"> <ent:entityType xsi:type="act:ActivityType" > <act:name>Acquire Property Location</act:name> <act:businessInteractionId>1</act:businessInteractionId> </ent:entityType> </nsrm:entitySearchCriteria> <nsrm:parameter> <bus:name></bus:name> <bus:value></bus:value> </nsrm:parameter> </nsrm:updateEntityRequest>
updateEntityResponse
updateEntityResponse returns information about the updated entities. The information returned in the response is dependent upon the entity types that were updated, as specified in the request.
updateEntityResponse returns an error message when:
-
The request specifies two different entity types in the request entity type and the criteria entity type
-
The request specifies a lock policy that specifies the number of resources to lock, and there are not enough resources available to lock
-
The call to the UIM API fails
DeleteEntity
The DeleteEntity operation enables external systems to send a request to UIM to delete certain entities in UIM.
deleteEntityRequest
You must specify search criteria to search for entities to delete. You have the choice of specifying search criteria one of two ways. With either choice, you must specify the type of entity to find based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use as search criteria to find entities to delete. Table 3-4 lists the valid entity types and the schema files in which they are defined.
Table 3-4 Entity Types for DeleteEntity
Entity Type | Schema File |
---|---|
ActivityType |
Activity.xsd |
CustomNetworkAddressType |
CustomNetworkAddress.xsd |
CustomObjectType |
CustomObject.xsd |
EquipmentType |
PhysicalDevice.xsd |
FlowIdentifierType |
LogicalDevice.xsd |
InventoryGroupType |
InventoryGroup.xsd |
IPv4AddressType |
IPAddress.xsd |
IPv6AddressType |
IPAddress.xsd |
IPSubnetType |
IPAddress.xsd |
LogicalDeviceType |
LogicalDevice.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
PlaceType |
Place.xsd |
TelephoneNumberType |
Number.xsd |
The choices are:
-
<entity>
In this search option, you specify the entity type and use the entity-specific elements to specify search criteria.
For each entity type, the <entity> structure varies. For example, TelephoneNumberType defines <rangeFrom> and <rangeTo>, but none of the other entity types define these elements.
Even though the <entity> structure varies per entity type, the following elements are common across most entity types:
-
specification
The search returns entities created from the specified specification.
-
id
The search returns the entity with the specified id. (InventoryGroupType is only entity type with no id; the inventory group name is the id.)
-
name
The search returns entities with the specified name.
-
description
The search returns entities with the specified description.
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
Note:
Within each EntityType structure, the property element defines name, value, and action. However, action is not used; rather, the NRM Web Service operations always assume an operand of EQUALS.
-
-
-
<criteria>
In this search option, you specify the entity type and use the following search criteria:
-
specification
The search returns entities created from the specified specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PORTED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="TRANSITIONAL"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
If searching for telephone number entities, you can specify the inventoryGroup geographicLocation and the search returns telephone number entities associated with inventory groups that are associated with the specified place. If searching for entities other than telephone numbers, the inventoryGroup geographicLocation is not used.
-
geographicLocation
The search returns inventory group entities associated with the specified place. If searching for entities other than inventory groups, geographicLocation is not used.
-
quantity
The search returns the specified quantity of entities. For example, if the search finds 1,000 entities and the criteria specifies a quantity of 50, the first 50 entities found are returned.
-
reservation
If you specify reservation information, DeleteEntity ignores it; FindEntity is the only operation that uses the reservation element. See "FindEntity" for more information.
-
lock
Row locking is used to optimize concurrent resource allocation for consumable entities; however, DeleteEntity does not use row locking.
If you specify row-locking information, DeleteEntity ignores it.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
-
Enumerated operand with which to evaluate the specified characteristic and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
Multiple Entities
You specify one entity type to delete per request, and one entity search criteria to find the entities to delete per request. For example, you can search for logical devices to delete with a single request, and you can search for logical device accounts to delete with a single request, but you cannot search for logical devices and logical device accounts to delete with a single request.
Optional Elements
You can specify parameters that define name/value pairs, which you can use with custom code to extend the operation. DeleteEntity does not process specified parameters unless customized to do so. See "Customizing the Web Service Operations" for more information.
Examples
Example 3-7 shows a request that specifies an entity type of TelephoneNumberType, and uses entity-specific elements to find a particular telephone number to delete, 9729630014, created from the usTelephoneNumber specification.
Example 3-7 deleteEntityRequest
<nsrm:deleteEntityRequest> <ent:entity xsi:type="tn:TelephoneNumberType"> <tn:specification> <spec:name>usTelephoneNumber</spec:name> </tn:specification> <tn:id>9729630014</tn:id> </ent:entity> <nsrm:parameter> <bi:name></bi:name> <bi:value></bi:value> </nsrm:parameter> </nsrm:deleteEntityRequest>
Example 3-8 shows a request that specifies an entity type of TelephoneNumberType, and specifies search criteria to find telephone numbers to delete created from the usTelephoneNumber specification that are installed and unassigned.
Example 3-8 deleteEntityRequest
<nsrm:deleteEntityRequest> <ent:criteria> <ent:entityType xsi:type="tn:TelephoneNumberType"/> <ent:specification> <spec:name>usTelephoneNumber</spec:name> </ent:specification> <ent:adminState>INSTALLED</ent:adminState> <ent:assignmentState>UNASSIGNED</ent:assignmentState> </ent:criteria> <nsrm:parameter> <bi:name></bi:name> <bi:value></bi:value> </nsrm:parameter> </nsrm:deleteEntityRequest>
ReserveEntity
The ReserveEntity operation enables external systems to send a request to UIM to find an existing reservation or new create a reservation, and to add certain resource entities to the existing or newly created reservation.
reserveEntityRequest
The request structure defines the ResourceReservationType entity type; you do not specify the entity type for the reservation.
Within the reservation-specific elements, you specify one or both of the following:
-
An existing reservation number
-
Reservation information with which to create a reservation, which at a minimum must include:
-
reservedFor
-
reservedForType
-
reservationType
-
If you specify an existing reservation number, the operation attempts to find the reservation based on the specified reservation number. If the reservation is found, additional resources are added to it. If the reservation is not found, an error is thrown.
If you specify reservation information with which to create a reservation, the operation generates a reservation number and creates a reservation using the specified information.
If you specify both a reservation number and reservation information with which to create a reservation, the operation attempts to find the reservation based on the specified reservation number. If the reservation is found, additional resources are added to it, but the reservation is not updated with the specified reservation information. If the reservation is not found, the operation creates a reservation using the specified reservation number and reservation information.
If you specify neither a reservation number nor reservation information, an error is thrown.
Resource Entity Search Criteria
You must specify search criteria to find existing resource entities to add to the reservation. You have the choice of specifying search criteria one of two ways. With either choice, you must specify the type of resource entity to find based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use as search criteria to find entities. Table 3-5 lists the valid entity types and the schema files in which they are defined.
Table 3-5 Entity Types for ReserveEntity
Entity Type | Schema File |
---|---|
CustomNetworkAddressType |
CustomNetworkAddress.xsd |
CustomObjectType |
CustomObject.xsd |
FlowIdentifierType |
LogicalDevice.xsd |
IPv4AddressType |
IPAddress.xsd |
IPv6AddressType |
IPAddress.xsd |
IPSubnetType |
IPAddress.xsd |
LogicalDeviceType |
LogicalDevice.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
TelephoneNumberType |
Number.xsd |
The choices are:
-
<resourceEntities>
In this search option, you specify the entity type and use the entity-specific elements to specify search criteria.
For each entity type, the <entity> structure varies. For example, TelephoneNumberType defines <rangeFrom> and <rangeTo>, but none of the other entity types define these elements.
Even though the <entity> structure varies per entity type, the following elements are common across most entity types:
-
specification
The search returns entities created from the specified specification.
-
id
The search returns the entity with the specified id. (InventoryGroupType is only entity type with no id; the inventory group name is the id.)
-
name
The search returns entities with the specified name.
-
description
The search returns entities with the specified description.
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
Note:
Within each EntityType structure, the property element defines name, value, and action. However, action is not used; rather, the NRM Web Service operations always assume an operand of EQUALS.
-
-
-
<resourceCriteria>
In this search option, you specify the entity type and use the following search criteria:
-
specification
The search returns entities created from the specified specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PORTED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="TRANSITIONAL"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
If searching for telephone number entities, you can specify the inventoryGroup geographicLocation and the search returns telephone number entities associated with inventory groups that are associated with the specified place. If searching for entities other than telephone numbers, the inventoryGroup geographicLocation is not used.
-
geographicLocation
The search returns inventory group entities associated with the specified place. If searching for entities other than inventory groups, geographicLocation is not used. (You cannot reserve inventory groups, so geographicLocation is not used for ReserveEntity.)
-
quantity
The search returns the specified quantity of entities. For example, if the search finds 1,000 entities and the criteria specifies a quantity of 50, the first 50 entities found are returned.
-
reservation
If you specify reservation information, ReserveEntity ignores it; FindEntity is the only operation that uses the reservation element. See "FindEntity" for more information.
-
lock
Row locking is used to optimize concurrent resource allocation for consumable entities.
ReserveEntity always uses row locking, regardless of whether or not you specify the number of rows to lock. ReserveEntity releases locked entities; you do not need to manually release locked entities by calling the RowLockManager.releaseLock() method, or wait for the timer to release locked entities.
See Optimizing Concurrent Resource Allocation in UIM Developer's Guide for more information about row locking.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
-
Enumerated operand with which to evaluate the specified characteristic and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
Multiple Entities
You specify one reservation per request, and one search criteria per request. For example, if the search criteria returns 50 resources, all 50 resources are added to the specified reservation.
Optional Elements
You can specify parameters that define name/value pairs, which you can use with custom code to extend the operation. ReserveEntity does not process specified parameters unless customized to do so. See "Customizing the Web Service Operations" for more information.
Example
Example 3-9 shows a request that specifies reservation information with which to create a reservation, and specifies search criteria to find two logical device resources based on their specification name and ID. Based on this request, a new reservation is created, and the two logical device resources are added to the reservation.
Example 3-9 reserveEntityRequest
<nsrm:reserveEntityRequest> <nsrm:reservation> <config:state/> <config:reservationNumber/> <config:reservationType>SHORTTERM</config:reservationType> <config:expiry/> <config:reservedForType>ORDER</config:reservedForType> <config:reservedFor>Customer XYZ</config:reservedFor> <config:reason/> </nsrm:reservation> <nsrm:entityType xsi:type="ld:LogicalDeviceType"/> <nsrm:resources> <ent:entity xsi:type="ld:LogicalDeviceType"> <ld:specification> <spec:name>SIMCard</spec:name> </ld:specification> <ld:id>3101500000000009901</ld:id> </ent:entity> <ent:entity xsi:type="ld:LogicalDeviceType"> <ld:specification> <spec:name>SIMCard</spec:name> </ld:specification> <ld:id>3101500000000009902</ld:id> </ent:entity> </nsrm:resources> <nsrm:parameter> <bi:name></bi:name> <bi:value></bi:value> </nsrm:parameter> </nsrm:reserveEntityRequest>
reserveEntityResponse
reserveEntityResponse returns information about the reservation and the reserved resource entities. The resource entity information returned in the response is dependent upon the resource entity types that were reserved, as specified in the request.
reserveEntityResponse returns an error message when:
-
The request specifies a reservation that does not exist
-
The request specifies no reservation number and no reservation information with which to create a reservation
-
The request specifies a resource that does not exist
-
The call to the UIM API fails
ReserveTNBlock
The ReserveTNBlock operation enables external systems to send a request to UIM to find an existing reservation or create a new reservation, and to add telephone number blocks to the existing or newly created reservation.
reserveTNBlockRequest
The request structure defines the ResourceReservationType entity type; you do not specify the entity type for the reservation.
Within the reservation-specific elements, you specify one or both of the following:
-
An existing reservation number
-
Reservation information with which to create a reservation, which at a minimum must include:
-
reservedFor
-
reservedForType
-
reservationType
-
If you specify an existing reservation number, the operation attempts to find the reservation based on the specified reservation number. If the reservation is found, the telephone number block is added to it. If the reservation is not found, an error is thrown.
If you specify reservation information with which to create a reservation, the operation generates a reservation number and creates a reservation using the specified information.
If you specify both a reservation number and reservation information with which to create a reservation, the operation attempts to find the reservation based on the specified reservation number. If the reservation is found, the telephone number block is added to it, but the reservation is not updated with the specified reservation information. If the reservation is not found, the operation creates a reservation using the specified reservation number and reservation information.
If you specify neither a reservation number nor reservation information, an error is thrown.
Telephone Number Block Search Criteria
You must specify search criteria to find an existing telephone number block to add to an existing reservation or to a new reservation. The reserveTNBlockRequest XML structure is defined in the TNBlockModelType.xsd schema file.
You can specify the following in the request criteria:
-
<reservation>
If this request option, specify the reservation information by using the following search criteria:
-
reservationNumber
The reservation number after the reservation has been created.
-
reservationType
The type of reservation; for example, Shortterm or Longterm.
-
startDate
The date on which the reservation becomes effective.
-
(Optional) expiryDate
The date on which the reservation expires.
-
reservedForType
The type of entity or process for which the reservation is made.
-
reservedFor
Identifies who is making the reservation.
-
reason
The reason for the reservation.
-
-
<tnBlockCriteria>
In this request option, you can specify the following criteria:
-
startNumber
The starting number of a range of numbers that you want to reserve.
-
endNumber
The ending number of a range of numbers that you want to reserve.
-
blockSize
The telephone number block size that you want to reserve.
-
Example
Example 3-10 shows a request that specifies an existing reservation number of 1125010, and specifies the criteria to reserve a telephone number block size of 10 within a telephone number range between 295 and 395.
Example 3-10 reserveTNBlockRequest
<nsrm:reserveTNBlockRequest> <nsrm:reservation> <con:reservationNumber>1125010</con:reservationNumber> <con:reservationType>SHORTTERM</con:reservationType> <con:startDate>2018-07-19T20:47:12.380+05:30</con:startDate> <con:expiryDate>2018-08-31T21:47:12.380+05:30</con:expiryDate> <con:reservedForType>CUSTOMER</con:reservedForType> <con:reservedFor>CUSTOMER_NAME</con:reservedFor> <con:reason>REASON_FOR_RESERVATION</con:reason> </nsrm:reservation> <nsrm:tnBlockCriteria> <tnb:startNumber>295</tnb:startNumber> <tnb:endNumber>395</tnb:endNumber> <tnb:blockSize>10</tnb:blockSize> </nsrm:tnBlockCriteria> </nsrm:reserveTNBlockRequest>
reserveTNBlockResponse
reserveTNBlockResponse returns information about the reservation and the reserved telephone number block.
reserveTNBlockResponse returns an error message when:
-
The request specifies a reservation that does not exist
-
The request specifies no reservation number and no reservation information with which to create a reservation
-
The request specifies a telephone number block that does not exist
-
The call to the UIM API fails
UnreserveEntity
The UnreserveEntity operation enables external systems to send a request to UIM to unreserve certain resource entities from an existing reservation in UIM. If no resources remain for the reservation after the specified resource entities are unreserved, the reservation is deleted.
unreserveEntityRequest
The request structure defines the ResourceReservationType entity type; you do not specify the entity type.
Within the reservation-specific elements, you specify an existing reservation number. If the reservation is not found, an error is thrown.
Resource Entity Search Criteria
You must specify search criteria to find existing resource entities to unreserve. You have the choice of specifying search criteria one of two ways. With either choice, you must specify the type of resource entity to find based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use as search criteria to find entities. Table 3-6 lists the valid entity types and the schema files in which they are defined.
Table 3-6 Entity Types for UnreserveEntity
Entity Types | Schema File |
---|---|
CustomNetworkAddressType |
CustomNetworkAddress.xsd |
CustomObjectType |
CustomObject.xsd |
FlowIdentifierType |
LogicalDevice.xsd |
IPv4AddressType |
IPAddress.xsd |
IPv6AddressType |
IPAddress.xsd |
IPSubnetType |
IPAddress.xsd |
LogicalDeviceType |
LogicalDevice.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
TelephoneNumberType |
Number.xsd |
The choices are:
-
<resourceEntities>
In this search option, you specify the entity type and use the entity-specific elements to specify search criteria.
For each entity type, the <entity> structure varies. For example, TelephoneNumberType defines <rangeFrom> and <rangeTo>, but none of the other entity types define these elements.
Even though the <entity> structure varies per entity type, the following elements are common across most entity types:
-
specification
The search returns entities created from the specified specification.
-
id
The search returns the entity with the specified id. (InventoryGroupType is only entity type with no id; the inventory group name is the id.)
-
name
The search returns entities with the specified name.
-
description
The search returns entities with the specified description.
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
Note:
Within each EntityType structure, the property element defines name, value, and action. However, action is not used; rather, the NRM Web Service operations always assume an operand of EQUALS.
-
-
-
<resourceCriteria>
In this search option, you specify the entity type and use the following search criteria:
-
specification
The search returns entities created from the specified specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PORTED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="TRANSITIONAL"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
If searching for telephone number entities, you can specify the inventoryGroup geographicLocation and the search returns telephone number entities associated with inventory groups that are associated with the specified place. If searching for entities other than telephone numbers, the inventoryGroup geographicLocation is not used.
-
geographicLocation
The search returns inventory group entities associated with the specified place. If searching for entities other than inventory groups, geographicLocation is not used. (You cannot unreserve inventory groups, so geographicLocation is not used for UnreserveEntity.)
-
quantity
The search returns the specified quantity of entities. For example, if the search finds 1,000 entities and the criteria specifies a quantity of 50, the first 50 entities found are returned.
-
reservation
If you specify reservation information, UnreserveEntity ignores it; FindEntity is the only operation that uses the reservation element. See "FindEntity" for more information.
-
lock
Row locking is used to optimize concurrent resource allocation for consumable entities; however, UnreserveEntity does not use row locking.
If you specify row-locking information, UnreserveEntity ignores it.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
-
Enumerated operand with which to evaluate the specified characteristic and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
Multiple Entities
You specify one reservation per request, and one search criteria per request. For example, if the search criteria returns 50 resources, all 50 resources are unreserved for the specified reservation. If no resource entities remain on the reservation, the reservation is deleted.
Optional Elements
You can specify parameters that define name/value pairs, which you can use with custom code to extend the operation. UnreserveEntity does not process specified parameters unless customized to do so. See "Customizing the Web Service Operations" for more information.
Examples
Example 3-11 shows a request that specifies an existing reservation number of 12345678, and specifies search criteria to find a particular telephone number range based on its specification name. Based on this request, the telephone numbers 8588880081 through 8588880083 are unreserved for reservation 12345678.
Example 3-11 unreserveEntityRequest with a Telephone Number Range
<nsrm:unreserveEntityRequest> <nsrm:reservation> <config:reservationNumber>12345678</config:reservationNumber> </nsrm:reservation> <nsrm:resourceCriteria> <ent:entityType xsi:type="tn:TelephoneNumberType"/> <ent:specification> <spec:name>BATTNSpec</spec:name> </ent:specification> <ent:criteriaItem> <ent:name>rangeFrom</ent:name> <ent:value xsi:type="xs:string">8588880081</ent:value> <ent:operator>EQUALS</ent:operator> </ent:criteriaItem> <ent:criteriaItem> <ent:name>rangeTo</ent:name> <ent:value xsi:type="xs:string">8588880083</ent:value> <ent:operator>EQUALS</ent:operator> </ent:criteriaItem> </nsrm:resourceCriteria> </nsrm:unreserveEntityRequest>
Example 3-12 shows a request that specifies an existing reservation number of 123456789, and specifies search criteria to find a particular telephone number resource based on its specification name and resource ID. Based on this request, the 9729630012 telephone number resource is unreserved. The 9729630012 telephone number is the only resource on the reservation, and the reservation is deleted.
Note:
If this type of request is used for a reservation of a range of numbers the entire range is unreserved. Therefore, this type of request is only valid to unreserve a single reserved telephone number.
Example 3-12 unreserveEntityRequest for a Single Telephone Number
<nsrm:unreserveEntityRequest> <nsrm:reservation> <config:reservationNumber>123456789</config:reservationNumber> </nsrm:reservation> <nsrm:entityType xsi:type="tn:TelephoneNumberType"/> <nsrm:resources> <ent:entity xsi:type="tn:TelephoneNumberType"> <tn:specification> <spec:name>usTelephoneNumber</spec:name> </tn:specification> <tn:id>9729630012</tn:id> </ent:entity> </nsrm:resources> <nsrm:parameter> <bi:name></bi:name> <bi:value></bi:value> </nsrm:parameter> </nsrm:unreserveEntityRequest>
unreserveEntityResponse
unreserveEntityResponse returns information about the reservation and the unreserved resources (entities). The information returned in the response is dependent upon the resource entity types that were unreserved.
unreserveEntityResponse returns an error message when:
-
The specified reservation number is not found
-
The request specifies search criteria that retrieves resources not related to the specified reservation number
-
The call to the UIM API fails
UpdateReservation
The UpdateReservation operation enables external systems to send a request to UIM to update a reservation in UIM. This operation updates only reservation information; it does not update resources on the reservation, and it does not reserve or unreserve resources on the reservation. See "ReserveEntity" for information about reserving resources for a reservation, and see "UnreserveEntity" for information about unreserving resources for a reservation.
updateReservationRequest
The request structure defines the ResourceReservationType entity type; you do not specify the entity type.
Within the reservation-specific elements, you specify an existing reservation number and for whom the reservation is reserved, as well as any reservation information to update. If the reservation is not found, an error is thrown.
Optional Elements
You can specify parameters that define name/value pairs, which you can use with custom code to extend the operation. UpdateReservation does not process specified parameters unless customized to do so. See "Customizing the Web Service Operations" for more information.
Example
Example 3-13 shows a request that specifies an existing reservation number of 12345678 for Clark Kent, and specifies reservation information with which to update the reservation. <reservationNumber> and <reservedFor> are required elements used to retrieve the reservation. The remaining elements are optional and are used to specify the data with which to update the reservation.
Example 3-13 updateReservationRequest
<nsrm:updateReservationRequest> <nsrm:reservation> <config:reservationNumber>12345678</config:reservationNumber> <config:reservationType>LONGTERM</config:reservationType> <config:expiry>2018-12-31T00:00:00.000-06:00</config:expiry> <config:reservedForType>CSR</config:reservedForType> <config:reservedFor>Clark Kent</config:reservedFor> <config:reason>Testing</config:reason> </nsrm:reservation> <nsrm:parameter> <bi:name></bi:name> <bi:value></bi:value> </nsrm:parameter> </nsrm:updateReservationRequest>
AssociateEntity
The AssociateEntity operation enables external systems to send a request to UIM to associate certain entities in UIM.
associateEntityRequest
You must specify an association type of ASSOCIATE or PAIR, which are enumeration values defined in the entity.xsd file.
An association of type ASSOCIATE indicates a one-to-many association between a single specified source entity and multiple specified target entities. An association type of PAIR indicates a one-to-one association between a source entity and a target entity; in this type of association, multiple source entities and multiple target entities can be specified, but the number of each specified must be the same.
You must specify search criteria to find existing source entities to associate; and you must specify search criteria to find existing target entities to associate. You have the choice of specifying search criteria one of two ways. With either choice, you must specify the type of source/target entity to find based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use as search criteria to find entities. Table 3-7 lists the valid entity types and the schema files in which they are defined.
Table 3-7 Entity Types for AssociateEntity
Entity Type | Schema File |
---|---|
ActivityType |
Activity.xsd |
CustomNetworkAddressType |
CustomNetworkAddress.xsd |
CustomObjectType |
CustomObject.xsd |
EquipmentType |
PhysicalDevice.xsd |
InventoryGroupType |
InventoryGroup.xsd |
LogicalDeviceType |
LogicalDevice.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
PlaceType |
Place.xsd |
TelephoneNumberType |
Number.xsd |
The choices are:
-
<entity>
In this search option, you specify the entity type and use the entity-specific elements to specify search criteria.
For each entity type, the <entity> structure varies. For example, TelephoneNumberType defines <rangeFrom> and <rangeTo>, but none of the other entity types define these elements.
Even though the <entity> structure varies per entity type, the following elements are common across most entity types:
-
specification
The search returns entities created from the specified specification.
-
id
The search returns the entity with the specified id. (InventoryGroupType is only entity type with no id; the inventory group name is the id.)
-
name
The search returns entities with the specified name.
-
description
The search returns entities with the specified description.
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
Note:
Within each EntityType structure, the property element defines name, value, and action. However, action is not used; rather, the NRM Web Service operations always assume an operand of EQUALS.
-
-
-
<criteria>
In this search option, you specify the entity type and use the following search criteria:
-
specification
The search returns entities created from the specified specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PORTED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="TRANSITIONAL"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
If searching for telephone number entities, you can specify the inventoryGroup geographicLocation and the search returns telephone number entities associated with inventory groups that are associated with the specified place. If searching for entities other than telephone numbers, the inventoryGroup geographicLocation is not used.
-
geographicLocation
The search returns inventory group entities associated with the specified place. If searching for entities other than inventory groups, geographicLocation is not used.
-
quantity
The search returns the specified quantity of entities. For example, if the search finds 1,000 entities and the criteria specifies a quantity of 50, the first 50 entities found are returned.
-
reservation
If you specify reservation information, AssociateEntity ignores it; FindEntity is the only operation that uses the reservation element. See "FindEntity" for more information.
-
lock
Row locking is used to optimize concurrent resource allocation for consumable entities.
If you specify row-locking information, AssociateEntity releases locked entities; you do not need to manually release locked entities by calling the RowLockManager.releaseLock() method, or wait for the timer to release locked entities.
If you specify row-locking information for entities that are not consumable (Geographic Location and Inventory Group), an error is thrown.
See Optimizing Concurrent Resource Allocation in UIM Developer's Guide for more information about row locking.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
-
Enumerated operand with which to evaluate the specified characteristic and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
Multiple Entities
You specify one association type per request, and two sets of search criteria per request; one to find the source entities to associate, and one to find the target entities to associate.
Example
Example 3-14 shows a request that associates the specified source and target entities with an association type of ASSOCIATE. The source entity (only one source entity is specified in this example) is the MobileServingArea inventory group. The target entities are all logical devices created from the SIMCard specification that are installed and unassigned.
Example 3-14 associateEntityRequest
<nsrm:associateEntityRequest> <nsrm:associationType>ASSOCIATE</nsrm:associationType> <nsrm:sourceEntities> <nsrm:entityType xsi:type="ig:InventoryGroupType" /> <ent:criteria> <ent:entityType xsi:type="ig:InventoryGroupType" /> <ent:specification> <spec:name>MobileServingArea</spec:name> </ent:specification> </ent:criteria> </nsrm:sourceEntities> <nsrm:targetEntities> <nsrm:entityType xsi:type="ld:LogicalDeviceType" /> <ent:criteria> <ent:entityType xsi:type="ld:LogicalDeviceType" /> <ent:specification> <spec:name>SIMCard</spec:name> </ent:specification> <ent:adminState>INSTALLED</ent:adminState> <ent:assignmentState>UNASSIGNED</ent:assignmentState> </ent:criteria> </nsrm:targetEntities> </nsrm:associateEntityRequest>
associateEntityResponse
associateEntityResponse returns information about the associated entities. The information returned in the response is dependent upon the entity types that were associated, as specified in the request.
associateEntityResponse returns an error message when:
-
The request specifies search criteria that results in no entities found to associate
-
The request specifies an association type of PAIR and the number of sources and targets found is the not the same
-
The call to the UIM API fails
DisassociateEntity
The DisassociateEntity operation enables external systems to send a request to UIM to disassociate certain existing associated entities in UIM.
disassociateEntityRequest
You must specify an association type of ASSOCIATE or PAIR, which are enumeration values defined in the entity.xsd file.
An association of type ASSOCIATE indicates a one-to-many association between a single specified source entity and multiple specified target entities. An association type of PAIR indicates a one-to-one association between a source entity and a target entity.
You must specify search criteria to find existing source entities to disassociate; and you must specify search criteria to find existing target entities to disassociate. You have the choice of specifying search criteria one of two ways. With either choice, you must specify the type of source/target entity to find based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use as search criteria to find entities. Table 3-8 lists the valid entity types and the schema files in which they are defined.
Table 3-8 Entity Types for DisassociateEntity
Entity Type | Schema File |
---|---|
ActivityType |
Activity.xsd |
CustomNetworkAddressType |
CustomNetworkAddress.xsd |
CustomObjectType |
CustomObject.xsd |
EquipmentType |
PhysicalDevice.xsd |
InventoryGroupType |
InventoryGroup.xsd |
LogicalDeviceType |
LogicalDevice.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
PlaceType |
Place.xsd |
TelephoneNumberType |
Number.xsd |
The choices are:
-
<entity>
In this search option, you specify the entity type and use the entity-specific elements to specify search criteria.
For each entity type, the <entity> structure varies. For example, TelephoneNumberType defines <rangeFrom> and <rangeTo>, but none of the other entity types define these elements.
Even though the <entity> structure varies per entity type, the following elements are common across most entity types:
-
specification
The search returns entities created from the specified specification.
-
id
The search returns the entity with the specified id. (InventoryGroupType is only entity type with no id; the inventory group name is the id.)
-
name
The search returns entities with the specified name.
-
description
The search returns entities with the specified description.
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
Note:
Within each EntityType structure, the property element defines name, value, and action. However, action is not used; rather, the NRM Web Service operations always assume an operand of EQUALS.
-
-
-
<criteria>
In this search option, you specify the entity type and use the following search criteria:
-
specification
The search returns entities created from the specified specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PORTED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="TRANSITIONAL"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
If searching for telephone number entities, you can specify the inventoryGroup geographicLocation and the search returns telephone number entities associated with inventory groups that are associated with the specified place. If searching for entities other than telephone numbers, the inventoryGroup geographicLocation is not used.
-
geographicLocation
The search returns inventory group entities associated with the specified place. If searching for entities other than inventory groups, geographicLocation is not used.
-
quantity
The search returns the specified quantity of entities. For example, if the search finds 1,000 entities and the criteria specifies a quantity of 50, the first 50 entities found are returned.
-
reservation
If you specify reservation information, DisassociateEntity ignores it; FindEntity is the only operation that uses the reservation element. See "FindEntity" for more information.
-
lock
Row locking is used to optimize concurrent resource allocation for consumable entities; however, DisassociateEntity does not use row locking.
If you specify row-locking information, DisassociateEntity ignores it.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of a characteristic
-
Value of specified characteristic
-
Enumerated operand with which to evaluate the specified characteristic and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
Multiple Entities
You specify one association type per request, and two sets of search criteria per request; one to find the source entities to associate, and one to find the target entities to associate.
Example
Example 3-15 shows a request that disassociates the specified source and target entities. The source entity (only one source entity is specified in this example) is the MobileServingArea inventory group. The target entities are all logical devices created from the SIMCard specification that are installed and unassigned.
Example 3-15 disassociateEntityRequest
<nsrm:disassociateEntityRequest> <nsrm:sourceEntities> <nsrm:entityType xsi:type="ig:InventoryGroupType" /> <ent:criteria> <ent:entityType xsi:type="ig:InventoryGroupType" /> <ent:specification> <spec:name>MobileServingArea</spec:name> </ent:specification> </ent:criteria> </nsrm:sourceEntities> <nsrm:targetEntities> <nsrm:entityType xsi:type="ld:LogicalDeviceType" /> <ent:criteria> <ent:entityType xsi:type="ld:LogicalDeviceType" /> <ent:specification> <spec:name>SIMCard</spec:name> </ent:specification> <ent:adminState>INSTALLED</ent:adminState> <ent:assignmentState>UNASSIGNED</ent:assignmentState> </ent:criteria> </nsrm:targetEntities> </nsrm:disassociateEntityRequest>
disassociateEntityResponse
disassociateEntityResponse returns information about the disassociated entities. The information returned in the response is dependent upon the entity types that were disassociated, as specified in the request.
disassociateEntityResponse returns an error message when:
-
The call to the UIM API fails
ImportEntity
The ImportEntity operation enables external systems to send a request to import certain entities into UIM.
importEntityRequest
You specify a SOAP attachment that is a spreadsheet containing the entities for import. The spreadsheet must be a specific format: see "Spreadsheet Format".
For information about SOAP attachments, see the SoapUI website at:
http://www.soapui.org/SOAP-and-WSDL/adding-headers-and-attachments.html#2
Multiple Entities
You can import multiple entities of varying entity types per request. For example, a spreadsheet may define fifteen rows that result in the import of five telephone number entities, five logical device entities, and five physical device entities.
Example
Example 3-16 shows importEntityRequest, which uses of a SOAP attachment.
Example 3-16 importEntityRequest
<soapEnv:Envelope xmls:soapenv="http://schemas.xmlsoap.org/soap/envelope/".......> <soapEnv:Header/> <soapEnv:Body> <nsrm:importEntityRequest> <octet/> </nsrm:importEntityRequest> <soapEnv:Body/> </soapEnv:Envelope/>
Spreadsheet Format
Example 3-17 shows an excerpt from the UIM_CONFIG_PATH/config/importExport.properties file, which defines the column names for the ImportEntity spreadsheet. You can change the name of existing column names defined in this file, but you cannot add new columns to the spreadsheet by defining additional column names in this file.
Example 3-17 importExport.properties: Column Names
#Use import properties to customize column names for excel of ImportEntity import.rowNumber=rowNumber import.action=action import.entityType=entityType import.id=id import.rangeFromID=rangeFromID import.rangeToID=rangeToID import.quantity=quantity import.name=name import.rangeFromName=rangeFromName import.rangeToName=rangeToName import.specification=specification import.description=description import.attribute=attribute import.characteristic=characteristic import.relatedRow=relatedRow
Table 3-9 describes the columns defined in the importExport.properties file.
Table 3-9 Spreadsheet Column Names
Name | Description |
---|---|
rowNumber |
rowNumber is required and must be unique; it is a numeric value that you assign to each row in the spreadsheet. UIM uses rowNumber for referencing other rows in the spreadsheet for creating relationships. |
action |
action is required and must be one of the following values:
|
entityType |
entityType is required and must be one of the following values:
|
id |
When the action is create and the specification requires a user-provided ID, id is required. When the action is create and the specification automatically generates an ID, do not specify id. When the action is associate or information, id can optionally specify search criteria. The value can be numeric or alphanumeric. |
rangeFromID |
rangeFromID populates the same database table and column as id, but it is used when creating entities in bulk. When the action is create, and you are creating LogicalDevice, LogicalDeviceAccount, or PhysicalDevice entities in bulk, and the specification requires a user-provided ID, rangeFromID is required and specifies the starting ID. When rangeFromID is specified, you must also specify quantity. See "quantity". When the action is create, and you are creating TelephoneNumber entities, rangeFromID is not valid. For TelephoneNumber entities, you specify rangeFromName and rangeToName. See "rangeFromName" and "rangeToName". When the action is associate or information, rangeFromID, along with rangeToID, can optionally specify search criteria. The value must be numeric. |
rangeToID |
When the action is associate or information, rangeToID, along with rangeFromID, can optionally specify search criteria. The value must be numeric. |
quantity |
When the action is create, and you are creating LogicalDevice, LogicalDeviceAccount, or PhysicalDevice entities in bulk, quantity specifies the number of entities to create. When the action is create, and you are creating TelephoneNumber entities, quantity is not valid. For TelephoneNumber entities, you specify rangeFromName and rangeToName. See "rangeFromName" and "rangeToName". The value must be numeric. |
name |
When the action is create, name specifies the name of the entity or entities you are creating. When creating entities in bulk, all entities are created with the same name. When the action is associate or information, name can optionally specify search criteria. The value can be alphanumeric or numeric. |
rangeFromName |
(rangeFromName populates the same database table and column as name.) When the action is create, and you are creating TelephoneNumber entities, rangeFromID is specified along with rangeToName. See "rangeToName". When the action is create, and you are creating LogicalDevice, LogicalDeviceAccount, or PhysicalDevice entities in bulk, rangeFromName specifies the starting name of the entities to create. When rangeFromName is specified in this scenario, you must also specify quantity. See "quantity". When the action is associate or information, rangeFromName, along with rangeToName, can optionally specify search criteria. The value must be numeric. |
rangeToName |
When the action is create, and you are creating TelephoneNumber entities, rangeToID is specified along with rangeFromName. See "rangeFromName". When the action is associate or information, rangeToName, along with rangeFromName, can optionally specify search criteria. The value must be numeric. |
specification |
When the action is create, specification is required to specify the specification used to create the entity. When the action is associate or information, specification can optionally specify search criteria. The value must represent an existing specification in UIM. |
description |
When the action is create, description specifies the name of the entity or entities you are creating. When creating entities in bulk, all entities are created with the same name. Specifying a description is optional. The value must be alphanumeric. |
attribute |
When the action is create, attribute specifies the attribute name/value pair per cell for the entity or entities you are creating. The name/value pair is specified as attributeName=attributeValue. For example, or myAttribute=123. The number of attribute columns depends on the number of attributes defined for the entity you are creating. For example, when creating a PhysicalDevice entity, your spreadsheet may specify four attribute columns containing the name/value pair for the following attributes:
When creating entities in bulk, specifying attributeName=attributeValue creates all entities with same attribute and same attribute value. For example, if you specify myAttr=123, all entities are created with the myAttr attribute and all myAttr attribute values are m123. When the action is associate or information, attribute can specify search criteria. For example, attributeName=attributeValue searches for entities with the specified attribute and attribute value. For example, if you specify myAttr=123, the search looks for entities with the myAttr attribute that has an attribute value of 123. The value for any given attribute must match the data type defined for the attribute. |
characteristic |
When the action is create, characteristic specifies the characteristic name/value pair per cell for the entity or entities you are creating. The name/value pair is specified as characteristicName=characteristicValue. For example, myChar=123. The number of characteristic columns depends on the number of characteristics defined for the entity you are creating. The characteristic column works similarly to the attribute column. See "attribute" for an example. When creating entities in bulk, you can specify:
When the action is associate or information, characteristic can specify search criteria as follows:
The value for any given characteristic must match the data type defined for the characteristic. |
relatedRow |
relatedRow specifies rowNumber from the row with which the current row entity will get paired (associated with a type of PAIR). When the action is create for the source row and target row, both rows must point to each other (the source row's pair value must reflect the target row's rowNumber, and the target row's pair value must reflect the source row's rowNumber). The value must be numeric. The following list shows all valid relations. (In the list, LD is LogicalDevice, LDA is LogicalDeviceAccount, PD is PhysicalDevice, TN is TelephoneNumber, and IG is InventoryGroup):
|
Note:
The following columns from Table 3-9 do not support the IPAM-specific entities of IPv4Address, IPv6Address or IPSubnet:
-
rangeFromID, rangeToID
-
quantity
-
rangeFromName, rangeToName
-
relatedRow
Table 3-10 shows an example input spreadsheet for the request. The table shows various values for the id, rangeFromID, rangeToID, quantity, name, rangeFromName, and rangeToName columns when using the ImportEntity operation. In this example, all rows specify the create action and the LogicalDevice entityType and a dash represents no data for a cell.
Note:
The following columns were omitted from the spreadsheet example for clarity:
-
action (required column)
-
entityType (required column)
-
description
-
attribute
-
characteristic
-
relatedRow
Table 3-11 shows the results of processing each row in Table 3-10.
Table 3-10 Example Spreadsheet
row Number | id | range FromID | range ToID | quantity | name | range FromName | range ToName | specification |
---|---|---|---|---|---|---|---|---|
1 |
- |
- |
- |
- |
testLD1 |
- |
- |
LDSpec |
2 |
- |
- |
- |
- |
testLD2 |
- |
- |
LDSpec |
3 |
- |
- |
- |
2 |
testLD3 |
- |
- |
LDSpec |
4 |
- |
- |
- |
2 |
- |
11001 |
- |
LDSpec |
5 |
- |
- |
- |
2 |
testLD5 |
- |
- |
LDSpec |
6 |
- |
- |
- |
2 |
- |
12001 |
- |
LDSpec |
7 |
1000 |
- |
- |
- |
testLD7 |
- |
- |
LDSpec_ManualID |
8 |
1001 |
- |
- |
- |
testLD8 |
- |
- |
LDSpec_ManualID |
9 |
- |
1002 |
- |
2 |
testLD9 |
- |
- |
LDSpec_ManualID |
10 |
- |
1004 |
- |
2 |
- |
13001 |
- |
LDSpec_ManualID |
11 |
- |
1006 |
- |
2 |
testLD11 |
- |
- |
LDSpec_ManualID |
12 |
- |
1008 |
- |
2 |
- |
14001 |
- |
LDSpec_ManualID |
Table 3-11 Example Spreadsheet Results
row Number | Result |
---|---|
1 |
One LogicalDevice entity is created from the LDSpec specification. Then entity is named testLD1. The entity id is generated. |
2 |
One LogicalDevice entity is created from the LDSpec specification. Then entity is named testLD2. The entity id is generated. |
3 |
Two LogicalDevice entities are created from the LDSpec specification. Both entities are named testLD3. The entity ids are generated. |
4 |
Two LogicalDevice entities are created from the LDSpec specification. The first entity is named 11001, and the second entity is named 11002. The entity ids are generated. |
5 |
Two LogicalDevice entities are created from the LDSpec specification. Both entities are named testLD5. The entity ids are generated. |
6 |
Two LogicalDevice entities are created from the LDSpec specification. The first entity is named 12001, and the second entity is named 12002. The entity ids are generated. |
7 |
One LogicalDevice entity are created from the LDSpec_ManualID specification. The entity is named testLD7. The entity id is 1000. |
8 |
One LogicalDevice entity are created from the LDSpec_ManualID specification. The entity is named testLD8. The entity id is 1001. |
9 |
Two LogicalDevice entities are created from the LDSpec_ManualID specification. Both entities are named testLD9. The first entity id is 1002 and the second entity id is 1003. |
10 |
Two LogicalDevice entities are created from the LDSpec_ManualID specification. The first entity is named 13001, and the second entity is named 13002. The first entity id is 1004 and the second entity id is 1005. |
11 |
Two LogicalDevice entities are created from the LDSpec_ManualID specification. Both entities are named testLD11. The first entity id is 1006 and the second entity id is 1007. |
12 |
Two LogicalDevice entities are created from the LDSpec_ManualID specification. The first entity is named 14001, and the second entity is named 14002. The first entity id is 1008 and the second entity id is 1009. |
Spreadsheet Row Order
The rows in the spreadsheet must be provided to ImportEntity in a specific order. The order is based on a combination of the action, relatedRow, and entityType column values.
The spreadsheet row order must be:
-
create-create paired rows
First, provide the rows of entities to create that are to be paired with another entity; that is, both rows specify the create action and both rows specify a relatedRow value that indicates each other.
If you are creating entities of varying entity type, specify your create-create paired rows in the following entityType order:
-
TelephoneNumber
-
LogicalDevice
-
LogicalDeviceAccount
-
PhysicalDevice
-
InventoryGroup
-
-
create rows
Next, provide the rows of entities to create that are not to be paired with another entity; that is, rows that specify the create action and specify no relatedRow value.
If you are creating entities of varying entity type, specify your create rows in the following entityType order:
-
TelephoneNumber
-
LogicalDevice
-
LogicalDeviceAccount
-
PhysicalDevice
-
InventoryGroup
-
-
create-information paired rows
Next, provide the rows of entities to create for which additional information is provided in a corresponding row; that is, one row specifies the create action, one row specifies the information action, and both rows specify a relatedRow value that indicates each other.
If you are creating entities of varying entity type, specify your create-information paired rows in the following entityType order:
-
TelephoneNumber
-
LogicalDevice
-
LogicalDeviceAccount
-
PhysicalDevice
-
InventoryGroup
-
-
associate-information paired rows
Last, provide the rows of entities to associate for which additional information is provided in a corresponding information row; that is, one row specifies the associate action, one row specifies the information action, and both rows specify a relatedRow value that indicates each other.
If you are associating entities of varying entity type, specify your associate-information paired rows in the following entityType order:
-
TelephoneNumber
-
LogicalDevice
-
LogicalDeviceAccount
-
PhysicalDevice
-
InventoryGroup
-
importEntityResponse
importEntityResponse returns information about the imported entities. The information returned in the response is dependent upon the entity types that were imported, as specified in the request.
importEntityResponse returns an error message when the request specifies the following. (In the list, LD is LogicalDevice, LDA is LogicalDeviceAccount, PD is PhysicalDevice, and TN is TelephoneNumber):
-
A rowNumber less than zero, or duplicate row numbers
-
More than 10,000 rows
-
A column name that is not defined in the properties file
-
No action
-
The create action with no specification
-
The create action with a specification that does not exist
-
A quantity of zero or less than zero
-
The create action for an LD, LDA, or PD, and specifies a rangeToID or rangeToName (which is used only for TN)
-
No id or rangeToID for Manual ID specifications of LD, LDA, or PD
-
No quantity with rangeFromID for Manual ID specifications of LD, LDA, or PD
-
A rangeFromID that is not numeric for LD, LDA, or PD
-
Both id and quantity LD, LDA, or PD
-
Both id and rangeFromID LD, LDA, or PD
-
Both id and rangeFromID for auto-generated ID specifications of LD, LDA, or PD
-
Both Name and rangeFromName for LD, LDA, PD, or TN
-
No name and no rangeFromName for LD, LDA, PD, or TN
-
A rangeFromName that is not numeric LD, LDA, PD, or TN
-
An incorrect attribute for any entity
-
No rangeFromName and no rangeToName for TN
-
id, rangeFromID, rangeToID, quantity, rangeFromName, or rangeToName for InventoryGroup
-
More than one LD for LD-LDA association
-
More than one LD for LD-PD association
-
Pairing information for association when action is create in both rows does not match
-
Invalid association types (For example, LD-LD, PD-LDA, and so forth)
-
An unequal number of entities for LD-TN or PD-TN
-
Incorrect relatedRow information (For example, relatedRow does not specify the information action)
-
An InventoryGroup that does not exist
-
The call to the UIM API fails
ExportEntity
The ExportEntity operation enables external systems to send a request to export certain existing entities from UIM. The entities found for export are returned in a spreadsheet through a SOAP attachment in the response.
exportEntityRequest
You must specify search criteria to find existing entities to export. Search criteria is specified using the <criteria> element, which includes entity type.
You specify the type of entity to export based on the entity types defined in the schema files. Each entity type defines different elements that pertain specifically to the entity type, which you use to specify what to update. Table 3-12 lists the valid entity types and the schema files in which they are defined.
Table 3-12 Entity Types for ExportEntity
Entity Type | Schema File |
---|---|
LogicalDeviceType |
LogicalDevice.xsd |
LogicalDeviceAccountType |
LogicalDevice.xsd |
PhysicalDeviceType |
PhysicalDevice.xsd |
TelephoneNumberType |
Number.xsd |
<criteria> defines the following search criteria:
-
specification
The search returns entities created from the specified specification.
-
adminState
The search returns entities in the specified administrative state, which is defined by the following enumeration values:
<xs:enumeration value="END_OF_LIFE"/> <xs:enumeration value="INSTALLED"/> <xs:enumeration value="PENDING_INSTALL"/> <xs:enumeration value="PENDING_REMOVE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PLANNED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="PENDING_DISCONNECT"/> <xs:enumeration value="DISCONNECTED"/>
-
assignmentState
The search returns entities in the specified assignment state, which is defined by the following enumeration values:
<xs:enumeration value="PENDING_ASSIGN"/> <xs:enumeration value="ASSIGNED"/> <xs:enumeration value="PENDING_UNASSIGN"/> <xs:enumeration value="UNASSIGNED"/> <xs:enumeration value="DISCONNECTED"/> <xs:enumeration value="PENDING_AVAILABLE"/> <xs:enumeration value="PENDING_UNAVAILABLE"/> <xs:enumeration value="PORTED"/> <xs:enumeration value="UNAVAILABLE"/> <xs:enumeration value="TRANSITIONAL"/>
-
inventoryGroup
The search returns entities associated with the specified inventory group.
-
quantity
The search returns the specified quantity of entities. For example, if the search finds 1,000 entities and the criteria specifies a quantity of 50, the first 50 entities found are returned.
-
reservation
If you specify reservation information, ExportEntity ignores it; FindEntity is the only operation that uses the reservation element. See "FindEntity" for more information.
-
lock
Row locking is used to optimize concurrent resource allocation for consumable entities; however, ExportEntity does not use row locking.
If you specify row-locking information, ExportEntity ignores it.
-
criteriaItem
The search returns entities based on data specified by criteriaItem, which is an unbounded structure that provides the ability to specify the following:
-
Name of a criteria item as defined by the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth (see "Determining Criteria Item Names")
-
Value of specified criteria item
-
Enumerated operand with which to evaluate the specified criteria item and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
-
property
The search returns entities with the data specified by property, which is an unbounded structure that provides the ability to specify the following:
-
Name of characteristic
-
Value of specified characteristic
-
Enumerated operand with which to evaluate the specified characteristic and corresponding specified value:
<xs:enumeration value="EQUALS" /> <xs:enumeration value="NOT_EQUALS" /> <xs:enumeration value="BEGINS_WITH" /> <xs:enumeration value="ENDS_WITH" /> <xs:enumeration value="CONTAINS" />
-
Multiple Entities
You can export multiple entities of varying entity types per request. For example, the request search criteria may return telephone number entities, logical device entities, and physical device entities, and the varying types of entities are exported.
Example
Example 3-18 shows search criteria to find LogicalDevice entities created from the SIMCard specification that are installed and unassigned.
Example 3-18 exportEntityRequest
<nsrm:exportEntityRequest> <ent:criteria> <ent:entityType xsi:type="ld:LogicalDeviceType" /> <ent:specification> <spec:name>SIMCard</spec:name> </ent:specification> <ent:adminState>INSTALLED</ent:adminState> <ent:assignmentState>UNASSIGNED</ent:assignmentState> </ent:criteria> </nsrm:exportEntityRequest>
exportEntityResponse
exportEntityResponse returns a spreadsheet containing the exported entities as a SOAP attachment in the response. The entities returned in the response are dependent upon the entity types that were exported, as specified in the request.
Example 3-19 shows an excerpt from the UIM_CONFIG_PATH/config/importExport.properties file, which defines the column names for the ExportEntity spreadsheet. These column names are common across all ExportEntity-supported entity types. You can change the name of existing column names defined in this file, but you cannot add new columns to the spreadsheet by defining additional column names in this file.
Example 3-19 importExport.properties: Column Names
#Use export properties to customize column names for excel of ExportEntity export.slNo=serialNumber export.entityType=entityType export.id=ID export.name=name export.specification=specification export.description=description export.attribute=attribute export.characteristic=characteristic
Exported entities are grouped by entity type per sheet. Example 3-20 shows an excerpt from the UIM_CONFIG_PATH/config/importExport.properties file, which defines the sheet names. You can change the name of existing sheets, but you cannot add new sheets to the spreadsheet by defining additional sheets in this file.
Example 3-20 importExport.properties: Sheet Names
#Use export properties to customize name sheets for different entities export.sheet.telephoneNumber=TelephoneNumber export.sheet.logicalDevice=LogicalDevice export.sheet.logicalDeviceAccount=LogicalDeviceAccount export.sheet.physicalDevice=PhysicalDevice
The sheets are created when entities are found for export. So, all sheets are not always returned. For example, if the specified search criteria finds only logical devices to export, only the LogicalDevice sheet is returned.
If no entities are found for export, no sheets are created, and no attachment is returned in the response.
TelephoneNumber Sheet
If telephone number entities are found for export based on the specified search criteria, the TelephoneNumber sheet is created. This sheet contains the column names that are common across all ExportEntity-supported entity types (shown in Example 3-19), as well as column names that represent telephone number attributes.
Example 3-21 shows an excerpt from the UIM_CONFIG_PATH/config/importExport.properties file, which defines the available telephone number attribute column names you can add to the sheet by setting to true, or omit from the sheet by setting to false.
You can change the name of existing column names defined in this file, but you cannot add new columns to the TelephoneNumber sheet by defining additional column names in this file.
Example 3-21 importExport.properties: TN-Specific Column Names
#Use TelephoneNumber export properties for exporting attributes tn.export.partition=true tn.export.owner=true tn.export.permissions=tue
LogicalDevice Sheet
If logical device entities are found for export based on the specified search criteria, the LogicalDevice sheet is created. This sheet contains the column names that are common across all ExportEntity-supported entity types (shown in Example 3-19), as well as column names that represent logical device attributes.
Example 3-22 shows an excerpt from the UIM_CONFIG_PATH/config/importExport.properties file, which defines the available logical device attribute column names you can add to the sheet by setting to true, or omit from the sheet by setting to false.
You can change the name of existing column names defined in this file, but you cannot add new columns to the LogicalDevice sheet by defining additional column names in this file.
Example 3-22 importExport.properties: LD-Specific Column Names
#Use LogicalDevice export properties for exporting attributes ld.export.partition=true ld.export.owner=true ld.export.permissions=true ld.export.networkLocationEntityCode=true ld.export.deviceIdentitfier=true
LogicalDeviceAccount Sheet
If logical device account entities are found for export based on the specified search criteria, the LogicalDeviceAccount sheet is created. This sheet contains the column names that are common across all ExportEntity-supported entity types (shown in Example 3-19), as well as column names that represent logical device account attributes.
Example 3-23 shows an excerpt from the UIM_CONFIG_PATH/config/importExport.properties file, which defines the available logical device account attribute column names you can add to the sheet by setting to true, or omit from the sheet by setting to false.
You can change the name of existing column names defined in this file, but you cannot add new columns to the LogicalDeviceAccount sheet by defining additional column names in this file.
Example 3-23 importExport.properties: LDA-Specific Column Names
#Use LogicalDeviceAccount export properties for exporting attributes lda.export.partition=true lda.export.owner=true lda.export.permissions=true
PhysicalDevice Sheet
If physical device entities are found for export based on the specified search criteria, the PhysicalDevice sheet is created. This sheet contains the column names that are common across all ExportEntity-supported entity types (shown in Example 3-19), as well as column names that represent physical device attributes.
Example 3-24 shows an excerpt from the UIM_CONFIG_PATH/config/importExport.properties file, which defines the available physical device attribute column names you can add to the sheet by setting to true, or omit from the sheet by setting to false.
You can change the name of existing column names defined in this file, but you cannot add new columns to the PhysicalDevice sheet by defining additional column names in this file.
Example 3-24 importExport.properties: PD-Specific Column Names
#Use PhysicalDevice export properties for exporting attributes pd.export.partition=true pd.export.owner=true pd.export.permissions=true pd.export.networkLocation=true pd.export.physicalLocation=true pd.export.physicalAddress=true pd.export.serialNumber=true
Determining Criteria Item Names
This section provides detailed information regarding determining criteria item names, as referenced from "FindEntity", "FindTNBlock", "UpdateEntity", "DeleteEntity", "ReserveEntity", "UnreserveEntity", "AssociateEntity", "DisassociateEntity", and "ExportEntity".
When using the criteriaItem structure, the search returns entities based on specified criteria item name/value pairs.
To determine the valid criteria item names you can specify, you must look in the Javadoc for the EntitySearchCriteria class, where Entity is the name of a specific entity such as TelephoneNumber, LogicalDevice, and so forth. For each EntitySearchCriteria class, you can only specify criteria items that are native to the class. For example, Figure 3-1 shows an excerpt of the TelephoneNumberSearchCriteria Javadoc.
In this example, the following are valid criteria item names you can specify:
-
adminState
-
assignmentState
-
conditionType
-
customerId
-
id
-
inventoryGroupName
-
name
-
rangeFrom
-
rangeTo
-
blockSize
Criteria items that are native to the class are listed as type CriteriaItem in the Javadoc method summary Modifier and Type column. You cannot specify criteria items that are type boolean, java.util.List, or another UIM entity class, such as InventoryGroup as shown in the example.
Note:
Be mindful that getter and setter method names alter the criteria item name.
For example, the getAdminState() method spells AdminState with an uppercase “A", but the criteria item name is actually adminState with a lowercase “a".
For information about accessing the UIM Javadoc, see UIM Developer's Guide.
Customizing the Web Service Operations
You can customize any of the web service operations by creating a custom Java class that extends an existing UIM class. In the custom Java class, you can define methods that override and modify the methods defined in the parent class you are extending.
To customize web service operations:
-
Open the UIM_CONFIG_PATH/config/nsrm-ws.properties file.
The file lists the delegate web service classes and the delegate API classes. All of the delegate classes listed in the nsrm-ws.properties file are described in the Javadoc.
-
Use the Javadoc to determine which delegate class you want to customize.
To access the Javadoc, enter the following in your Web browser:
http://server:port/ora_uim_javadoc
where server is the specific server on which the application is deployed and port is the port on which the application listens.
For detailed instructions on accessing the Javadoc, see UIM Developer's Guide.
-
Create a custom Java class that extends a delegate class.
-
In the custom Java class, you can customize any of the methods defined in the parent class by defining the same methods in the child class, and modifying the methods as needed for your business requirements.
Your custom code can also execute a ruleset. For example, you may want to utilize existing functionality provided in the base rulesets. See UIM Developer's Guide for more information about rulesets, including how to execute a ruleset from within custom code.
-
In the nsrm-ws.properties file:
-
Copy and paste the property that defines the delegate class you extended.
-
Comment out the original property that defines the delegate class you extended.
-
Update the copied property to reflect the name of your custom class.
For example:
#ws.delegate.TelephoneNumberType=oracle.communications.inventory. #webservice.delegate.TelephoneNumberDelegate ws.delegate.TelephoneNumberType=oracle.communications.inventory. webservice.delegate.MyCustomTNDelegate
-
-
Deploy the custom code.
For traditional UIM:
-
If your custom code resides within an Inventory cartridge project, you deploy the cartridge through Design Studio. See UIM Developer's Guide for more information.
-
If your custom code resides within a WAR file in the custom.ear file, you deploy the custom.ear file through the WebLogic Administration Console. See "Developing Custom Web Services" for more information.
For cloud native UIM:
-
Deploy the custom code into UIM cloud native by rebuilding the customized image and creating the instance with generated image. For more information, see "Customizing Images" in UIM Cloud Native Deployment Guide.
-
Extending Web Service Requests and Responses
You can extend web service requests and responses by extending GenericHandler.class, which supports the use of SOAP handlers and which is used by the UIM Network Resource Management Web Service.
Extending Network Resource Management Web Service requests and responses is done the same way as extending Service Fulfillment Web Service requests and responses. Both web services are packaged together in the InventoryWS.war file, so all of the steps are the same. See "Extending Web Service Requests and Responses" in the Service Fulfillment Web Service chapter for detailed instructions about extending web service requests and responses.
Deploying, Testing, and Securing the Web Service
Information about deploying, testing, and securing the web service is described in "Deploying, Testing, and Securing UIM Web Services".