3 Implementing a Generic Service Fulfillment Scenario
This chapter describes implementing a generic service fulfillment scenario using various Oracle Communications Unified Inventory Management (UIM) application program interfaces (APIs). You can use this information to gain a better understanding of how the UIM APIs can be used to implement any service scenario.
About the Generic Service Fulfillment Scenario
The generic service fulfillment scenario is a Service entity with a single Custom Object resource assignment. The example Service entity is simplified, but the API descriptions are applicable and extensible to other types of services with various types of resource assignments.
Figure 3-1 shows the process flow for a generic service fulfillment scenario:
Figure 3-1 Process Flow of Generic Service Fulfillment Scenario
![Description of Figure 3-1 follows Description of Figure 3-1 follows](img/api_sf_gen_process_flow.gif)
Description of "Figure 3-1 Process Flow of Generic Service Fulfillment Scenario"
The process flow begins with querying for the service specification, which is used in subsequent steps in the process flow, such as creating the Service and searching for resources.
The process flow continues with creating the service, based upon the retrieved service specification.
Next is creating the service configuration, which involves querying for the service configuration specification, creating the service configuration based upon the retrieved service configuration specification, and any creating default service configuration items.
The process flow continues with the optional steps of creating additional entities, such as Party and Geographic Address (a concrete Geographic Place entity representing a Service Address). These entities are created and associated to the Service with specific inventory roles.
Next in the process flow is configuring the resources for the service (resource management), which involves querying for resources based on specific criteria using core API searches or using custom searches. For example, you can call an API directly to search for a Custom Object by ID, or you can call a custom API to search for a Custom Object by its association to an Inventory Group or association to another Custom Object. You can also create resources for immediate assignment to the service. The main goal of resource management is to retrieve and validate the correct resources for assignment to the service. However, you can also manage the resources with alternate flows, such as creating reservations and conditions. Assignments, references, reservations, and conditions are the main consumption concepts for a given resource.
In addition to resource assignments and references, the service and service configuration also have characteristic values. These values are used to setup and configure the service instance.
After the service has been configured through resource and characteristic value assignments, the process flow continues with transitioning the lifecycle status of various entities. APIs are presented to show the transition of the statuses, and how the statuses are managed within the core API functionality.
The process flow shown in Figure 3-1 shows the initial creation of the service, and also shows other scenarios, such as changing the service configuration and disconnecting the service. These additional scenarios are also described.
Now that you have a high-level understanding of the generic service fulfillment process flow, each part of the process flow is further described in the following sections. Each section includes information about the specific UIM APIs used to perform each step and possible alternate flows of each step. Example code is also included for each step.
Querying for the Specification
This section describes the UIM API method used to query for the service specification. The retrieved service specification will later be used to create the service.
Table 3-1 and example code provide information about using the API method.
Table 3-1 Querying for the Specification
Topic | Information |
---|---|
Name |
SpecManager.findSpecifications |
Description |
This method retrieves specifications based on input criteria. |
Pre-Condition |
The service specification already exists. |
Internal Logic |
The database is queried for specifications meeting the input criteria. Specifications matching the criteria are returned. |
Post-Condition |
The desired service specification has been retrieved. |
Extensions |
Not applicable |
Tips |
If a list of specifications is returned, the list will need to be iterated to select the desired specification to be used to create the service. Set the SpecSearchCriteria.setValidSpecsOnly (true) to instruct the find method to only return active specifications. Set the SpecSearchCriteria.setSpecClass (ServiceSpecification.class) to instruct the find method to only return service specifications. Additional criteria, such as name, may also be set to further constrain the list of service specifications returned by the find method. This method is applicable for retrieving other types of specifications by supplying the correct Specification class as the query parameter. For example, it can be used to retrieve a CustomObject specification to be used later for resource query or creation. |
Example 3-1 Querying for the Specification
Specification spec = null; SpecManager specMgr = PersistenceHelper.makeSpecManager(); SpecSearchCriteria criteria = specMgr.makeSpecSearchCriteria(); CriteriaItem critSpecName = criteria.makeCriteriaItem(); critSpecName.setValue(specName); critSpecName.setOperator(CriteriaOperator.EQUALS_IGNORE_CASE); criteria.setName(critSpecName); criteria.setSpecClass(ServiceSpecification.class); List<Specification> specs = specMgr.findSpecifications(criteria); if (Utils.isEmpty(specs)) { /* log error */ } spec = specs.get(0);
Querying for the Specification Using Finder API
This section describes the UIM API method used to query for a service specification using a generic Finder.findByName API.
Table 3-2 and example code provide information about using this API method.
Table 3-2 Querying for the Specification Using Finder API
Topic | Information |
---|---|
Name |
Finder.findByName |
Description |
This method retrieves entity objects based on input criteria. |
Pre-Condition |
The service specification already exists. |
Internal Logic |
The database is queried for specifications meeting the input criteria. Specifications matching the criteria are returned. |
Post-Condition |
The desired service specification has been retrieved. |
Extensions |
Not applicable |
Tips |
If a list of specifications is returned, the list will need to be iterated to select the desired specification to be used to create the service. If the specification is not found, the Find method returns empty collection <ServiceSpecification>. Note: The specification name is not a unique field, but it is recommended to have unique specification names. This method is applicable for retrieving other types of specifications by supplying the correct Specification class as the query parameter. For example, it can be used to retrieve a CustomObject specification or any UIM entity to be used later for resource query or creation. |
Example 3-2 Querying for the Service Specification Using Finder API
Specification spec = null; Finder f = null; try{ f = PersistenceHelper.makeFinder(); Collection<ServiceSpecification> specs = f.findByName(ServiceSpecification.class, “Service_Spec_name"); if (Utils.isEmpty(specs)) { /* log error */ } spec = specs.iterator().next(); } catch(Exception e){ /* log exception */ } finally{ if(f!=null){ f.close(); } }
Creating the Service and Service Configuration
This section describes the UIM API methods used to create the service and service configuration, and to create default configuration items on the service configuration. The API methods are listed in the order in which they must be called.
Figure 3-2 shows the generic service configuration specification used in the generic service fulfillment scenario:
Figure 3-2 Generic Service Configuration Specification Example
![Description of Figure 3-2 follows Description of Figure 3-2 follows](img/api_sf_gen_svc_config_spec.gif)
Description of "Figure 3-2 Generic Service Configuration Specification Example"
Creating the Service
This section describes the UIM API method used to create the service, based upon the retrieved service specification.
Table 3-3 and example code provide information about using the API method.
Table 3-3 Creating the Service
Topic | Information |
---|---|
Name |
ServiceManager.createService |
Description |
This method creates a service instance built from the input service specification. The service will be populated with the hard facts and characteristics supplied by the caller. |
Pre-Condition |
A service specification has been selected. |
Internal Logic |
The service is created using the input service specification. |
Post-Condition |
The service has been created and is in Pending status. |
Extensions |
Not applicable |
Tips |
The Service.startDate and Service.name are required attributes. The Service.characteristics can be populated with the desired characteristics. If the service specification is defined with any required characteristics that do not have default values specified, then those characteristic must be set on the service in order for it to be created successfully. |
Example 3-3 Creating the Service with Characteristics
ServiceManager smgr = null; Finder f = null; try{ smgr = PersistenceHelper.makeServiceManager(); f = PersistenceHelper.makeFinder(); Collection<ServiceSpecification> serviceSpecCollection = f.findByName(ServiceSpecification.class,"service_spec"); ServiceSpecification serviceSpec = (ServiceSpecification) serviceSpecCollection.iterator().next(); Service serviceModel = smgr.makeService(Service.class); serviceModel.setName("Service_test22"); serviceModel.setDescription("Service_test22_desc"); serviceModel.setId("Service_test22"); serviceModel.setSpecification(serviceSpec); HashSet<CharacteristicSpecification> charSpecs = new HashSet<CharacteristicSpecification>(); charSpecs = CharacteristicHelper.getCharacteristicSpecifications(serviceSpec); /*charSpecs is populated with the characteristics specifications of the serviceSpec. Now, we are ready to set the value for each characteristic based on its name. Below code has if-else condition for the same. */ if (!charSpecs.isEmpty()) { Set<ServiceCharacteristic> servChars = new HashSet<ServiceCharacteristic>(); ServiceCharacteristic servChar = null; for (CharacteristicSpecification charSpec : charSpecs) { servChar = sd.makeServiceCharacteristic(); servChar.setName(charSpec.getName()); if (charSpec.getName().equals ("test_CharSpec_text")) { servChar.setValue("service testing char"); } else if (charSpec.getName().equals("test_CharSpec_TF_Numeric")) { servChar.setValue("500"); } servChar.setCharacteristicSpecification(charSpec); servChars.add(servChar); } serviceModel.setCharacteristics(servChars); } Collection<Service> services = new ArrayList<Service>(); services.add(serviceModel); List<Service> createdServices = smgr.createService(services); service = createdServices.get(0); } catch(Exception e){ /* log exception */ } finally{ if(f!=null){ f.close(); } }
Retrieving the Service Configuration Specification
This section describes the UIM API method used to retrieve the service configuration specification. The retrieved service configuration specification will later be used to create the service configuration.
Table 3-4 and example code provide information about using the API method.
Table 3-4 Retrieving the Service Configuration Specification
Topic | Information |
---|---|
Name |
ConfigurationManager.getConfigSpecTypeConfig |
Description |
This method retrieves the configuration specifications related to the input service specification. |
Pre-Condition |
The service specification is associated to one or more configuration specifications. |
Internal Logic |
The configuration specifications related to the service specification are retrieved and returned. |
Post-Condition |
A configuration specification has been selected. |
Extensions |
Not applicable |
Tips |
If a list of specifications is returned, the list will need to be iterated to select the desired specification to be used to create the service configuration. |
Example 3-4 Retrieving the Service Configuration Specification
ConfigurationManager configurationManager = PersistenceHelper.makeConfigurationManager(); List< InventoryConfigurationSpec > configSpecs = configurationManager.getConfigSpecTypeConfig( serviceSpec, true ); return configSpecs;
Retrieving the Service Configuration Specification Using Finder API
You can retrieve the service configuration specification using the finder.findByName API. See Table 3-2 for more information.
Example 3-5 Querying for the Service Configuration Specification Using Finder API
InventoryConfigurationSpec spec = null; Finder f = null; try{ f = PersistenceHelper.makeFinder(); Collection< InventoryConfigurationSpec > specs = f.findByName(InventoryConfigurationSpec.class, “Service_Configuration_Spec_name"); if (Utils.isEmpty(specs)) { /* log error */ } spec = specs.iterator().next(); } catch(Exception e){ /* log exception */ } finally{ if(f!=null){ f.close(); } }
Creating the Service Configuration
This section describes the UIM API method used to create the service configuration, based upon the retrieved service configuration specification.
Table 3-5 and example code provide information about using the API method:
Table 3-5 Creating the Service Configuration
Topic | Information |
---|---|
Name |
BaseConfigurationManager.createConfigurationVersion(Configurable configurable, InventoryConfigurationVersion configuration, InventoryConfigurationSpec configSpec) |
Description |
This method creates a service configuration version and associates it to the service. |
Pre-Condition |
The service exists with no service configuration versions. |
Internal Logic |
Not applicable |
Post-Condition |
The first configuration version is created and associated to the service. This method will default the configuration items based on the input configSpec. |
Extensions |
Not applicable |
Tips |
The service, configuration and configSpec parameters are required. |
Example 3-6 Creating the Service Configuration
Finder f = null; try{ f = PersistenceHelper.makeFinder(); Collection<Service> serviceCollection = f.findById(Service.class, servId); Service serv = serviceCollection.iterator().next(); f.reset(); Collection<InventoryConfigurationSpec> invSpecCollection = f.findByName(InventoryConfigurationSpec.class,"Serv_Config"); InventoryConfigurationSpec invSpec = invSpecCollection.iterator().next(); BaseConfigurationManager bcd = PersistenceHelper.makeConfigurationManager (ServiceConfigurationVersion.class); InventoryConfigurationVersion scv = bcd.makeConfigurationVersion(serv); scv.setDescription(configId); scv.setId(configId); scv.setName(configId); scv.setEffDate(new Date()); InventoryConfigurationVersion createdConfig = bcd.createConfigurationVersion(serv, scv,invSpec); }catch(Exception e){ /* log exception*/ } finally{ if(f!=null) f.close(); }
About Alternate Flows
The generic service fulfillment scenario creates a service and initial service configuration. Alternate flows to this scenario may be to change the service, or to disconnect the service.
The alternate flows described in this section are:
Changing the Service
This section describes the UIM API method used to change an existing service by adding a new service configuration version. The main goal is to create an IN_PROGRESS service configuration version so additional resource or characteristic changes can be executed. For example, after creating an initial service configuration version to assign a custom object to a service, a second service configuration version can be created to unassign the custom object previously allocated.
Table 3-6 and example code provide information about using the API method.
Table 3-6 Changing the Service
Topic | Information |
---|---|
Name |
BaseConfigurationManager.createConfigurationVersion(Configurable configurable, InventoryConfigurationVersion configuration) |
Description |
This method creates new configuration version from the most recently completed previous configuration version. |
Pre-Condition |
A service with a completed service configuration version must exist. |
Internal Logic |
Not applicable |
Post-Condition |
A service configuration version is created with a status of IN_PROGRESS. |
Extensions |
Not applicable |
Tips |
The service and configuration parameters are required. |
Example 3-7 Changing the Service
Finder f = null; try{ f = PersistenceHelper.makeFinder(); Collection<Service> serviceCollection = f.findById(Service.class, servId); Service serv = serviceCollection.iterator().next(); f.reset(); Collection<InventoryConfigurationSpec> invSpecCollection = f.findByName(InventoryConfigurationSpec.class,"Serv_Config"); InventoryConfigurationSpec invSpec = invSpecCollection.iterator().next(); BaseConfigurationManager bcd = PersistenceHelper.makeConfigurationManager(ServiceConfigurationVersion.class); InventoryConfigurationVersion scv = bcd.makeConfigurationVersion(serv); scv.setDescription(configId); scv.setId(configId); scv.setName(configId); scv.setEffDate(new Date()); InventoryConfigurationVersion createdConfig = bcd.createConfigurationVersion(serv, scv); } catch(Exception e){ /*log exception */ }finally{ if(f!=null) f.close(); }
Example 3-8 Updating the Characteristics of a Service
Service service = null; Finder f = null; BaseConfigurationManager configMgr = null; try{ f = PersistenceHelper.makeFinder(); Collection<Service> services = f.findByName(Service.class, "service_name"); Service = Services.iterator.next(); HashSet<CharacteristicSpecification> charSpecs = new HashSet<CharacteristicSpecification>(); charSpecs = CharacteristicHelper.getCharacteristicSpecifications (Service.getSpecification()); if (!charSpecs.isEmpty()) { Set<ServiceConfigurationItemCharacteristic> sciChars = new HashSet<ServiceConfigurationItemCharacteristic>(); ServiceConfigurationItemCharacteristic sciChar = null; for (CharacteristicSpecification charSpec : charSpecs) { sciChar = configItem.makeCharacteristicInstance(); String charName = sciChar.getName(charSpec.getName()); if (charName.equals("char_name_1)){ sciChar.setValue("textupdated"); } sciChars.add(sciChar); } } service.setCharacteristics(sciChars); } } catch(Exception e){ /* log exception*/ } finally{ if(f!=null) f.close(); }
Disconnecting the Service
This section describes the UIM API method used to disconnect a service when the service is no longer needed.
Table 3-7 and example code provide information about using the API method.
Table 3-7 Disconnecting the Service
Topic | Information |
---|---|
Name |
ServiceManager.disconnectService |
Description |
This method will transition the state of a service and invoke necessary business logic for the service and configuration version depending on the type of transition initiated. |
Pre-Condition |
The service exists and there are no configuration versions in a state other than Completed or Cancelled. |
Internal Logic |
Not applicable |
Post-Condition |
The service has a Pending Disconnect status. A new configuration version is created and any resources that are currently assigned, are unassigned. The configuration version has an In Progress status. |
Extensions |
Not applicable |
Tips |
The businessAction to be passed as input to the transition method is ServiceAction.DISCONNECT. |
Example 3-9 Disconnecting the Service
ServiceManager sm = PersistenceHelper.makeServiceManager(); sm.disconnectService(service);
Creating and Associating the Party
This section describes the UIM API methods used to create a party, create a party role, and associate the party and party role with the service. The API methods are listed in the order in which they must be called.
Note:
The associations of the party and party role with the service are optional, and can be associated before or after the creation of the initial service configuration. Typically, these types of associations do not change for the service, but alternate flows are presented to show how the associations can be changed if necessary.
Creating the Party
This section describes the UIM API method used to create the party.
Table 3-8 and example code provide information about using the API method.
Table 3-8 Creating the Party
Topic | Information |
---|---|
Name |
PartyManager.createParties |
Description |
This method takes a collection of Party entities and persist them into the database. The Party Role and association to the Service is setup by a different API. |
Pre-Condition |
Party Specification is valid and retrieved from the database. Party has a valid and unique ID. |
Internal Logic |
Take the collection of transient Party entities and persists them into the database, and return the collection of persisted Party entities. Validate that the Parties are not duplicated by ID and they all have valid PartySpecification. |
Post-Condition |
Persistent Party entities are returned. |
Extensions |
This API is defined as an extension point to allow custom validation before or after the Parties are created. For instance, the IDs can be generated based on some custom algorithm. |
Tips |
Party is a CharacteristicExtensible entity. The characteristic values should be added when the Party instance is created. Use RoleManager APIs to manage the roles played by a given Party, and use AttachmentManager to associate the Party with specific Role to a given Service. |
Example 3-10 Creating the Party
Finder finder = null; PartyManager mgr = null; try{ finder = PersistenceHelper.makeFinder(); mgr = PersistenceHelper.makePartyManager(); Party party = mgr.makeParty(); Collection<Party> parties = new ArrayList<Party>(); party.setId(partyId); party.setName("Party_Name"); party.setDescription("Party_Description"); Collection<PartySpecification> partyspec = finder.findByName(PartySpecification.class,"Test_Party_Spec"); PartySpecification partySpec =partyspec.iterator().next(); party.setSpecification(partySpec); parties.add(party); List<Party> results = mgr.createParties(parties); Party resulty = results.iterator().next(); } catch(Exception e){ /*log exception here*/ }finally{ if(finder!=null){ finder.close(); } }
Creating the Party Role
This section describes the UIM API method used to create the party role.
Table 3-9 and example code provide information about using the API method.
Table 3-9 Creating the Party Role
Topic | Information |
---|---|
Name |
RoleManager.createInventoryRole |
Description |
This method takes a collection of InventoryRole entities and persist them into the database. The roles passed in are the concrete subclass, for instance PartyRole. |
Pre-Condition |
InvRoleSpecification is valid and retrieved from the database. The Party which has the roles is already created. |
Internal Logic |
Take the collection of transient InventoryRole entities and persists them into the database, and return the collection of persisted InventoryRole entities. Validate that the roles are not duplicated and they all have valid InvRoleSpecification. |
Post-Condition |
Persistent concrete subclass (i.e. PartyRole) entities are returned. |
Extensions |
Not applicable |
Tips |
Use RoleManager.makePartyRole() API to get a transient instance of the correct concrete subclass of role to create. InvRoleSpecification is required. |
Example 3-11 Creating the Party Role
Finder finder = PersistenceHelper.makeFinder(); RoleManager roleMgr = PersistenceHelper.makeRoleManager(); PartyRole role = roleMgr.makePartyRole(); /* Utility Method Call - see 3.2.1 Query Spec */ Collection<InvRoleSpecification> invrolespeclist = finder.findByName(InvRoleSpecification.class,("Test_Party_Role_Spec"); InvRoleSpecification rolespec = (InvRoleSpecification)invrolespeclist.iterator().next(); role.setSpecification(roleSpec); List<InventoryRole> roles = new ArrayList<InventoryRole>(); roles.add(role); roleMgr.createInventoryRole(roles);
Associating the Party and Party Role with the Service
This section describes the UIM API method used to associate the party and party role with the service. The API method must be called once per association. So, in this scenario, the API is called to associate the party with the service, and then called again to associate the party role with the service.
Table 3-10 and example code provide information about using the API method. The example shows associating the party with the service; it does not show associating the party role with the service, which is accomplished by calling the same API method.
Table 3-10 Associating the Party and Party Role with the Service
Topic | Information |
---|---|
Name |
AttachmentManager.createRel |
Description |
This method creates an involvement (an association) between two entities. |
Pre-Condition |
Service, Party and PartyRole are already created. |
Internal Logic |
Creates an involvement entity to represent the relationship from Party to Service with a specific PartyRole. The Party is the parent of this involvement. Validates that the relationship is not duplicated. |
Post-Condition |
PartyServiceRel is created referencing the entities. |
Extensions |
Not applicable |
Tips |
Set the FROM entity to Party and TO entity to Service. Set the FROM entity role to the PartyRole. |
Example 3-12 Associating the Party to the Service
String roleOid = role.getOid(); AttachmentManager involvementMgr = PersistenceHelper.makeAttachmentManager(); Involvement involvement = involvementMgr.makeRel(PartyServiceRel.class); involvement.setToEntity(service); involvement.setFromEntity(party); involvement.setFromEntityRoleKey(roleOid); involvementMgr.createRel(involvement); PartyServiceRel partyServiceRel = (PartyServiceRel)involvement;
About Alternate Flows
The generic service fulfillment scenario creates a party and party role, and associates them with the service. Alternate flows to this scenario may be to disassociate the party and party role from the service, and then delete the party and party role.
The alternate flows described in this section are:
Disassociating the Party and Party Role from the Service
This section describes the UIM API methods used to retrieve a party or service, and then use the retrieved data to disassociate the party from the service. The API methods are listed in the order in which they must be called.
The API methods must be each called once per disassociation. So, in this scenario, an API is called to retrieve the party or service, and another API is called to disassociate the party from the service. This process is repeated to disassociate the party role from the service: An API is called to retrieve the party role or service, and another API is called to disassociate the party role from the service.
Table 3-11 and Table 3-12 provide information about using the API methods.
Table 3-11 Getting the Party and the Service
Topic | Information |
---|---|
Name |
Service.getParty() or Party.getService() |
Description |
These methods are used to retrieve the bidirectional relationship PartyServiceRel between Party and Service. Once retrieved, the correct instance can be deleted. |
Pre-Condition |
PartyServiceRel is already created. |
Internal Logic |
Simple relationship attribute on the entities to get list of relationships to iterate through. |
Post-Condition |
PartyServiceRel is found and passed to next method for deletion. |
Extensions |
Not applicable |
Tips |
Not applicable |
Table 3-12 Disassociating the Party from the Service
Topic | Information |
---|---|
Name |
AttachmentManager.deleteRel |
Description |
This method deletes an involvement (an association) between two entities. In this example, an existing relationship between the Party and Service with a specific role is deleted. |
Pre-Condition |
PartyServiceRel is already created. |
Internal Logic |
Delete the PartyServiceRel entity. |
Post-Condition |
PartyServiceRel is deleted. |
Extensions |
Not applicable |
Tips |
Delete existing PartyServiceRel and create new ones to change Party to Service relationships. |
Deleting the Party
This section describes the UIM API method used to delete a party.
Table 3-13 provides information about using the API method.
Table 3-13 Deleting the Party
Topic | Information |
---|---|
Name |
PartyManager.deleteParty |
Description |
This method deletes an existing Party, and all its existing PartyRoles. |
Pre-Condition |
Party is already created. |
Internal Logic |
Delete the Party entity. The Party will not be deleted if it is associated with other entities, such as involvement with a Service. |
Post-Condition |
Party is deleted. |
Extensions |
The API is an extension point for adding custom validation logic, such as logging and removing any relationships before deleting. |
Tips |
Use this method to delete an incorrect or obsolete Party before creating a new Party. |
Deleting the Party Role
This section describes the UIM API method used to delete a party role.
Table 3-14 provides information about using the API method.
Table 3-14 Deleting the Party Role
Topic | Information |
---|---|
Name |
RoleManager.deleteInventoryRoles |
Description |
This method deletes an existing InventoryRole on a given entity. In this example, a PartyRole subclass instance is deleted. |
Pre-Condition |
PartyRole is already created. |
Internal Logic |
Delete the PartyRole entity. |
Post-Condition |
PartyRole is deleted. |
Extensions |
Not applicable |
Tips |
Use this method to delete an incorrect or obsolete role before creating a new role. |
Creating and Associating the Geographic Address with the Service
This section describes the UIM API methods used to create a place, create a place role, and associate the place and place role with the service. (A place is a GeographicPlace entity, which id is a concrete entity representing a geographic address / service address.) The API methods are listed in the order in which they must be called.
Note:
The associations of the place and place role with the service are optional, and can be associated before or after the creation of the initial service configuration. Typically, these types of associations do not change for the service, but alternate flows are presented to show how the associations can be changed if necessary.
Creating the Geographic Place
This section describes the UIM API method used to create the geographic place.
Table 3-15 and example code provide information about using the API method.
Table 3-15 Creating the Geographic Place
Topic | Information |
---|---|
Name |
PlaceManager.createGeographicPlace |
Description |
This method takes a collection of Geographic Address entities which represents the Service Address and persist them into the database. The Place Role and association to the Service is setup by a different API. For this example, create a Geographic Address, a concrete subclass of Geographic Place, as an instance of the Service Address. |
Pre-Condition |
Place Specification is valid and retrieved from the database. Geographic Address has a valid and unique ID. |
Internal Logic |
Take the collection of transient Geographic Address entities and persists them into the database, and return the collection of persisted Geographic Address entities. Validate that the Geographic Address are not duplicated by ID and they all have valid PlaceSpecification. |
Post-Condition |
Persistent Geographic Address entities are returned. |
Extensions |
This API is defined as an extension point to allow custom validation before or after the Geographic Addresses are created. For instance, the IDs can be generated based on some custom algorithm. |
Tips |
Geographic Address is a CharacteristicExtensible entity. Its characteristic values should be added as the instance is created. Use RoleManager APIs to manage the roles played by a given Geographic Address, and use AttachmentManager to associate the Geographic Address with specific Role to a given Service. (Same as Party.) |
Example 3-13 Creating the Geographic Place
Finder finder = PersistenceHelper.makeFinder(); PlaceManager placeMgr = PersistenceHelper.makePlaceManager(); GeographicAddress place = placeMgr.makeGeographicPlace(GeographicAddress.class); place.setId("Place_ID"); place.setName("Place_Name"); Collection<PlaceSpecification> placeSpecification = finder.findByName (PlaceSpecification.class,(String)paramMap.get("Test_Place_Spec")); PlaceSpecification pcspec = PlaceSpecification.iterator().next(); place.setSpecification((PlaceSpecification) placeSpec); List places = new ArrayList<GeographicAddress>(); places.add(place); places = placeMgr.createGeographicPlace(places); place = (GeographicAddress) places.iterator().next();
Creating the Place Role
This section describes the UIM API method used to create the place role.
Table 3-16 and example code provide information about using the API method.
Table 3-16 Creating the Place Role
Topic | Information |
---|---|
Name |
RoleManager.createInventoryRole |
Description |
This method takes a collection of InventoryRole entities and persist them into the database. The roles passed in are the concrete subclass, for instance PlaceRole. |
Pre-Condition |
InvRoleSpecification is valid and retrieved from the database. The Geographic Address which has the roles is already created. |
Internal Logic |
Take the collection of transient InventoryRole entities and persists them into the database, and return the collection of persisted InventoryRole entities. Validate that the roles are not duplicated and they all have valid InvRoleSpecification. |
Post-Condition |
Persistent concrete subclass (i.e. PlaceRole) entities are returned. |
Extensions |
Not applicable |
Tips |
Use RoleManager.makePlaceRole() API to get a transient instance of the correct concrete subclass of role to create. InvRoleSpecification is required. |
Example 3-14 Creating the Place Role
Finder finder = PersistenceHelper.makeFinder(); RoleManager roleMgr = PersistenceHelper.makeRoleManager(); PlaceRole role = roleMgr.makePlaceRole(); Collection<InvRoleSpecification> invrolespeclist = f.findByName(InvRoleSpecification.class, "Test_Place_Role_Spec"); InvRoleSpecification rolespec = (InvRoleSpecification)invrolespeclist.iterator().next(); role.setSpecification(roleSpec); List<InventoryRole> roles = new ArrayList<InventoryRole>(); roles.add(role); roleMgr.createInventoryRole( roles);
Associating the Geographic Place and Place Role with the Service
This section describes the UIM API method used to associate the geographic place and place role with the service. The API method must be called once per association. So, in this scenario, the API is called to associate the geographic place with the service, and then called again to associate the place role with the service.
Table 3-17 and example code provide information about using the API method. The example shows associating the geographic place with the service; it does not show associating the place role with the service, which is accomplished by calling the same API method.
Table 3-17 Associating the Geographic Place and Place Role with the Service
Topic | Information |
---|---|
Name |
AttachmentManager.createRel |
Description |
This method creates an involvement (an association) between two entities. In this example, a relationship is created between Geographic Address and Service with a specific role created earlier. |
Pre-Condition |
Service, Geographic Address and PlaceRole are already created. |
Internal Logic |
Creates an involvement entity to represent the relationship from Geographic Address to Service with a specific PartyRole. The Geographic Address is the parent of this involvement. Validates that the relationship is not duplicated. |
Post-Condition |
PlaceServiceRel is created referencing the entities. |
Extensions |
Not applicable |
Tips |
Set the FROM entity to Geographic Address and TO entity to Service. Set the FROM entity role to the PlaceRole. |
Example 3-15 Associating the Geographic Place with the Service
String roleOid = role.getOid(); AttachmentManager involvementMgr = PersistenceHelper.makeAttachmentManager(); Involvement involvement = involvementMgr.makeRel(PlaceServiceRel.class); involvement.setToEntity(service); involvement.setFromEntity(place); involvement.setFromEntityRoleKey(roleOid); involvementMgr.createRel(involvement); PlaceServiceRel placeServiceRel = (PlaceServiceRel) involvement;
About Alternate Flows
The generic service fulfillment scenario creates a geographic place and place role, and associates them with the service. Alternate flows to this scenario may be to disassociate geographic place and place role from the service, and then delete the geographic place and place role.
The alternate flows described in this section are:
Disassociating the Geographic Place and Place Role from the Service
This section describes the UIM API methods used to retrieve a place or service, and then use the retrieved data to disassociate the place from the service. The API methods are listed in the order in which they must be called.
The API methods must be each called once per disassociation. So, in this scenario, an API is called to retrieve the place or service, and another API is called to disassociate the place from the service. This process is repeated to disassociate the place role from the service: An API is called to retrieve the place role or service, and another API is called to disassociate the place role from the service.
Table 3-18 and Table 3-19 provide information about using the API methods.
Table 3-18 Getting the Place and Service
Topic | Information |
---|---|
Name |
Service.getPlace() or GeographicPlace.getPlaceservicerels () |
Description |
These methods are used to retrieve the bidirectional relationship PlaceServiceRel between Geographic Address and Service. Once retrieved, the correct instance can be deleted. |
Pre-Condition |
PlaceServiceRel is already created. |
Internal Logic |
Simple relationship attribute on the entities to get list of relationships to iterate through. |
Post-Condition |
PlaceServiceRel is found and passed to next method for deletion. |
Extensions |
Not applicable |
Tips |
Not applicable |
Table 3-19 Disassociating the Place and Place Role from the Service
Topic | Information |
---|---|
Name |
AttachmentManager.deleteRel |
Description |
This method deletes an involvement (an association) between two entities. In this example, an existing relationship between the Geographic Address and Service with a specific role is deleted. |
Pre-Condition |
PlaceServiceRel is already created. |
Internal Logic |
Delete the PlaceServiceRel entity. |
Post-Condition |
PlaceServiceRel is deleted. |
Extensions |
Not applicable |
Tips |
Delete existing PlaceServiceRel and create new ones to change Geographic Address to Service relationships. |
Deleting the Geographic Place
This section describes the UIM API method used to delete a geographic place.
Table 3-20 provides information about the API method.
Table 3-20 Deleting the Geographic Place
Topic | Information |
---|---|
Name |
PlaceManager.deleteGeographicPlace |
Description |
This method deletes an existing Geographic Address, and all its existing PlaceRoles. In this example, the Service Address as in instance of a Geographic Address is deleted. |
Pre-Condition |
Geographic Address is already created. |
Internal Logic |
Delete the Geographic Address entity, and all its existing PlaceRoles. The Geographic Address will not be deleted if it is associated with other entities, such as involvement with a Service. |
Post-Condition |
Geographic Address is deleted. |
Extensions |
The API is an extension point for adding custom validation logic, such as logging and removing any relationships before deleting them. |
Tips |
Use this method to delete an incorrect or obsolete Geographic Address before creating a new Geographic Address. |
Deleting the Place Role
This section describes the UIM API method used to delete a place role.
Table 3-21 provides information about the API method.
Table 3-21 Deleting the Place Role
Topic | Information |
---|---|
Name |
RoleManager.deleteInventoryRoles |
Description |
This method deletes an existing InventoryRole on a given entity. In this example, a PlaceRole subclass instance is deleted. |
Pre-Condition |
PlaceRole is already created. |
Internal Logic |
Delete the PlaceRole entity. |
Post-Condition |
PlaceRole is deleted. |
Extensions |
Not applicable |
Tips |
Use this method to delete an incorrect or obsolete role before creating a new role. |
Configuring the Resources for the Service Configuration
This section describes the APIs need to assign a custom object to a service configuration item. The APIs are listed in the order in which they must be called.
Note:
If assignment is being done as part of creating the service and service configuration (see "Creating the Service and Service Configuration"), then start at section "Finding the Service Configuration Item" because the service and service configuration are already known.
Figure 3-3 shows how the service and configuration are created by calling the APIs described in Creating the Service and Service Configuration.
Finding the Service
This section describes the UIM API method used to find the service. The retrieved service will be used to find the service configuration.
Table 3-22 and example code provide information about using the API method.
Table 3-22 Finding the Service
Topic | Information |
---|---|
Name |
ServiceManager.findServices |
Description |
This method retrieves services based on input criteria. |
Pre-Condition |
The desired service already exists. |
Internal Logic |
The database is queried for services meeting the input criteria. Services matching the criteria are returned. |
Post-Condition |
The desired service has been retrieved. |
Extensions |
Not applicable |
Tips |
If a list of services is returned, the list will need to be iterated to select the desired service. |
Example 3-16 Finding the Service
ServiceManager mgr = PersistenceHelper.makeServiceManager(); ServiceSearchCriteria criteria = mgr.makeServiceSearchCriteria(); citem = criteria.makeCriteriaItem(); citem.setValue("Service_Test_22"); citem.setOperator(CriteriaOperator.EQUALS); criteria.setName(citem); List<Service> list = mgr.findServices(criteria);
Finding the Service by ID Using Finder API
This section describes the UIM API method that is used to find the service using the finder.findByName API.
Table 3-23 and example code provide information about using the API method.
Table 3-23 Querying for the Service by ID using Finder API
Topic | Information |
---|---|
Name |
Finder.findByName |
Description |
This method retrieves services based on input criteria. |
Pre-Condition |
The desired service already exists. |
Internal Logic |
The database is queried for services meeting the input criteria. Services matching the criteria are returned. |
Post-Condition |
The desired service has been retrieved. |
Extensions |
Not applicable |
Tips |
If a list of is returned, the list will need to be iterated to select the desired service. If the service is not found, the find method will return empty collection. Note: The name is not a unique field, but it is a common to have unique service names. This method is applicable for retrieving other entities by supplying the correct class as the query parameter. For example, it can be used to retrieve a CustomObject or any UIM entity to be used later for resource query or creation. |
Example 3-17 Finding the Service by ID Using Finder API
Service service = null; Finder f = null; try{ f = PersistenceHelper.makeFinder(); Collection<Service> services = f.findByName(Service.class, "service_name"); service = Services.iterator.next(); } catch(Exception e){ /* log exception*/ } finally{ if(f!=null) f.close(); }
Finding the Current Service Configuration Version
To find the current service configuration version:
-
Find the service. See "Finding the Service".
-
Select the service configuration versions using service.getConfigurations().
-
Process the retrieved service configuration versions, looking for one with a configState of IN_PROGRESS, DESIGNED or ISSUED.
There will only be one service configuration version in one of these states at a given point in time for a service. If a service configuration version is not found in one of these states, you cannot proceed with resource assignment.
In the generic service fulfillment scenario, Version 1 would be selected.
Example 3-18 Finding the Current Service Configuration Version
InventoryConfigurationVersion invConfigVersion = null; ServiceConfigurationManager scm = PersistenceHelper.makeServiceConfigurationManager(); BusinessInteractionState configState = BusinessInteractionState.IN_PROGRESS; /*similarly, other BusinessInteractionStates (COMPLETED, CANCELLED) can also be passed as parameter*/ List<InventoryConfigurationVersion> configs = scm.getEntityConfigurationVersions(configurable, configState); InventoryConfigurationVersion latestConfig = null; if (!Utils.isEmpty(configs)) { invConfigVersion = configs.get(0); } ServiceConfigurationVersion scv = (ServiceConfigurationVersion) invConfigVersion;
Finding the Service Configuration Item
To find the service configuration item:
-
Find the current service configuration version. See "Finding the Current Service Configuration Version".
-
Select the service configuration items using service.getConfigItems().
-
Process the retrieved service configuration items, looking for one with the configType of ITEM.
In the generic service fulfillment scenario, CO Item would be selected.
Note:
In this simplified example, we know there is only one item level configuration item, and we know it is associated to an option for a custom object specification, which is why the following sections find or create a custom object to assign.
Example 3-19 Finding the Current Service Configuration Item
ServiceConfigurationVersion scv = (ServiceConfigurationVersion) invConfigVersion; List<? extends InventoryConfigurationItem> items = confVersion.getConfigItems(); InventoryConfigurationItem invConfigItem = null; for (InventoryConfigurationItem item : items) { if (name.equalsIgnoreCase(item.getName())) { invConfigItem =item; break; } }
Example 3-20 Finding the Current Service Configuration Item - Alternate Way Including Checks for Existing References or Assignments on the Item
ServiceConfigurationVersion scv = (ServiceConfigurationVersion) invConfigVersion; boolean checkReferenceAndAssignment = true; List<? extends InventoryConfigurationItem> items = confVersion.getConfigItems(); InventoryConfigurationItem invConfigItem = null; for (InventoryConfigurationItem item : items) { if (name.equalsIgnoreCase(item.getName())) { if (checkReferenceAndAssignment) { if (configItem.getAssignment() == null && configItem.getReference() == null) { invConfigItem =item; break; } } } }
Finding the Custom Object to Assign
This section describes the UIM API method used to find the custom object to assign to the retrieved service configuration item. When assigning a custom object to a service configuration item, you can either find an existing custom object, or you can create a new custom object to assign, as described in the following section, "Creating the Custom Object to Assign".
Table 3-24 and example code provide information about using the API method.
Table 3-24 Finding the Custom Object
Topic | Information |
---|---|
Name |
CustomObjectManager.findCustomObjects |
Description |
This method retrieves custom objects based on input criteria. |
Pre-Condition |
The custom object to be allocated already exists. |
Internal Logic |
The database is queried for custom objects meeting the input criteria. Custom objects matching the criteria are returned. |
Post-Condition |
The desired custom object has been retrieved. |
Extensions |
Not applicable |
Tips |
Set the CustomObjectSearchCriteria.setAssignmentState(AssignmentState.UNASSI GNED) to instruct the find method to only return available custom objects. In this example, we could choose to set the CustomObjectSearchCriteria.setCustomObjectSpecification (CustomObjectSpecification) to the CO Spec instance. If a list of custom objects is returned, the list will need to be iterated to select the desired custom object to be allocated to the service configuration item. |
Example 3-21 Finding the Custom Object
Finder finder = null; CustomObjectManager mgr = null; try{ mgr = PersistenceHelper.makeCustomObjectManager(); CustomObjectSearchCriteria criteria = mgr.makeCustomObjectSearchCriteria(); criteria.setAdminState(InventoryState.INSTALLED); finder = PersistenceHelper.makeFinder(); int quantity = 1;// any positive number to ensure the query does not go unbounded Collection<CustomObjectSpecification> customObjectSpecs = finder.findByName(CustomObjectSpecification.class,"Test_Custom_Object_Spec"); criteria.setCustomObjectSpecification(customObjectSpecs.iterator().next()); criteria.setRange(0, quantity); mgr.findCustomObjects(criteria); /* another example */ Collection<CustomObject> custObjs = f.findById(CustomObject.class, "CO-1"); } catch (Exception e){ /* log exception */ } finally{ if(f!=null) f.close(); }
Creating the Custom Object to Assign
This section describes the UIM API method used to create a custom object to assign to the retrieved service configuration item. When assigning a custom object to a service configuration item, you can either create a new custom object, or you can find an existing custom object to assign, as described in "Finding the Custom Object to Assign".
Table 3-25 and example code provide information about using the API method.
Table 3-25 Creating the Custom Object
Topic | Information |
---|---|
Name |
CustomObjectManager.createCustomObjects |
Description |
This method creates a custom object. The custom object will be populated with the hard facts and characteristics supplied by the caller. |
Pre-Condition |
Not applicable |
Internal Logic |
The custom object is created. |
Post-Condition |
The custom object has been created and is in Installed status. |
Extensions |
Not applicable |
Tips |
A custom object can be created with or without a specification. |
Example 3-22 Creating the Custom Object
Finder f = null; CustomObjectManager custMgr = null; try{ custMgr = PersistenceHelper.makeCustomObjectManager(); f = PersistenceHelper.makeFinder(); Collection<CustomObjectSpecification> specList = new ArrayList<CustomObjectSpecification> (f.findByName(CustomObjectSpecification.class, "SPEC_CUST_001")); if (specList != null && !specList.isEmpty()) { CustomObjectSpecification custObjSpec = specList.iterator().next(); Collection<CustomObject> custObjects = new ArrayList<CustomObject>(); CustomObject custObj = custMgr.makeCustomObject(); custObj.setId("CUST_OBJ_ID"); custObj.setName("CUST_OBJ_NAME"); custObj.setDescription("CUST_OBJ_DESC"); custObj.setSpecification(custObjSpec); /* optional */ custObjects.add(custObj); custMgr.createCustomObjects(custObjects);} } catch(Exception e){ /* log exception*/ } finally{ if(f!=null) f.close(); }
Assigning the Resource to a Configuration Item
This section describes the UIM API method used to assign the resource to a configuration item. In the generic service fulfillment scenario, the resource is the custom object that was either found or created when "Finding the Custom Object to Assign" or "Creating the Custom Object to Assign".
Table 3-26 and example code provide information about using the API method.
Table 3-26 Assigning the Resource to a Configuration Item
Topic | Information |
---|---|
Name |
BaseConfigurationManager.assignResource(E item,oracle.communications.inventory.api.entity.common.ConsumableResource resource,java.lang.String reservedFor,java.lang.String reservedForType) In this example, the full signature of the method is included because there are multiple overloaded assignResource methods. |
Description |
This method assigns the input resource to the input service configuration item. In this example, a custom object is used as the consumable resource for assignment. |
Pre-Condition |
The configuration item to allocate the custom object to has been selected. |
Internal Logic |
Not applicable |
Post-Condition |
The custom object has been allocated to the service configuration item. |
Extensions |
Not applicable |
Tips |
The input item is the entity configuration item to assign the resource to (ConsumableResource). In this example, ConsumableResource is set to the CustomObject for CO-1. The reservedFor and reservedForType parameters should be populated if the resource to be assigned is reserved, so the reservation can be redeemed. |
Example 3-23 Assigning the Resource to a Configuration Item
Finder finder = PersistenceHelper.makeFinder(); Collection<CustomObject> custObjs = finder.findByName(CustomObject.class, "CO-1"); CustomObject custObj = custObjs.iterator().next(); ServiceManager mgr = PersistenceHelper.makeServiceManager(); ServiceSearchCriteria criteria = mgr.makeServiceSearchCriteria(); CriteriaItem citem = criteria.makeCriteriaItem(); citem.setValue("Service_Test_22"); citem.setOperator(CriteriaOperator.EQUALS); criteria.setName(citem); List<Service> list = mgr.findServices(criteria); Service service = list.get(0); List<ServiceConfigurationVersion> srvConfigurations = service.getConfigurations(); ServiceConfigurationItemAllocationData itemData = new ServiceConfigurationItemAllocationData(); int i = srvConfigurations.get(0).getVersionNumber(); //Write logic to get the latest ServiceConfigurationVersion of the Service. //Process the retrieved service configuration versions, //looking for one with a configState of IN_PROGRESS, DESIGNED or ISSUED. ServiceConfigurationVersion latestConfiguration; //Assign the latest ServiceConfigurationVersion //to the variable latestConfiguration List<ServiceConfigurationItem> configItems = latestConfiguration.getConfigItems(); for(ServiceConfigurationItem item : configItems) { if((item.getName()!= null && item.getName().equalsIgnoreCase("CO Item"))) { itemData.setResource(custObj); itemData.setServiceConfigurationItem(item); String reservedFor= null; // "Service-123" String reservedForType= null; // "Longterm" BaseConfigurationManager bcd = PersistenceHelper.makeConfigurationManager (ServiceConfigurationVersion.class); bcd.assignResource(item, custObj,reservedFor, reservedForType); break; } }
Referencing the Resource to a Configuration Item
This section describes the UIM API method used to reference the resource to a configuration item. In a generic service fulfillment scenario, the resource is a custom object that was either found or created when "Finding the Custom Object to Assign" or "Creating the Custom Object to Assign".
Table 3-24 and example code provide information about using the API method.
Table 3-27 Referencing the Resource to a Configuration Item
Topic | Information |
---|---|
Name |
BaseConfigurationManager. referenceEntity (E item, ConfigurationReferenceEnabled entity) |
Description |
This method refers the input resource to the input service configuration item. In this example, a custom object is used as the resource for reference. |
Pre-Condition |
The configuration item to allocate the custom object to has been selected. |
Internal Logic |
Not applicable |
Post-Condition |
The custom object has been allocated to the service configuration item. |
Extensions |
Not applicable |
Tips |
The input item is the entity configuration item to refer the resource to (referenceEnabledEntity). In this example, resource is set to the CustomObject for CO-1. |
Example 3-24 Referencing the Resource to a Configuration Item
Finder finder = null; BaseConfigurationManager configMgr = null ServiceManager mgr = null; try{ finder = PersistenceHelper.makeFinder(); Collection<CustomObject> custObjs = finder.findByName(CustomObject.class, "CO-1"); CustomObject custObj = custObjs.iterator().next(); mgr = PersistenceHelper.makeServiceManager(); ServiceSearchCriteria criteria = mgr.makeServiceSearchCriteria(); CriteriaItem citem = criteria.makeCriteriaItem(); citem.setValue("Service_Test_22"); citem.setOperator(CriteriaOperator.EQUALS); criteria.setName(citem); List<Service> list = mgr.findServices(criteria); Service service = list.get(0); List<ServiceConfigurationVersion> srvConfigurations = service.getConfigurations(); ServiceConfigurationItemAllocationData itemData = new ServiceConfigurationItemAllocationData(); int i = srvConfigurations.get(0).getVersionNumber(); //Write logic to get the latest ServiceConfigurationVersion of the Service. //Process the retrieved service configuration versions, //looking for one with a configState of IN_PROGRESS, DESIGNED or ISSUED. ServiceConfigurationVersion latestConfiguration; //Assign the latest ServiceConfigurationVersion //to the variable latestConfiguration List<ServiceConfigurationItem> configItems = latestConfiguration.getConfigItems(); ServiceConfigurationItem configItem = null; configMgr = PersistenceHelper.makeConfigurationManager (ServiceConfigurationItemDAO.class); ConfigurationItemSearchCriteria configItemCriteria = configMgr.makeConfigurationItemSearchCriteria(); configItemCriteria.setConfigurationItemClass(ServiceConfigurationItemDAO.class); CriteriaItem criteriaItem = configItemCriteria.makeCriteriaItem(); criteriaItem.setValue("item_name"); criteriaItem.setOperator(CriteriaOperator.EQUALS); configItemCriteria.setConfigurationItemName(criteriaItem); criteriaItem = configItemCriteria.makeCriteriaItem(); criteriaItem.setValue(version.getVersionNumber()); criteriaItem.setOperator(CriteriaOperator.EQUALS); configItemCriteria.setConfigurationVersionNumber(criteriaItem); List<InventoryConfigurationItem> configItems = configMgr.findConfigurationItems(configItemCriteria); configItem = configItems.iterator().next(); if (configItem != null) { BaseConfigurationManager configurationManager = PersistenceHelper.makeConfigurationManager(configItem.getClass()); configurationManager.referenceEntity(configItem, referenceEnabledEntity); } catch(Exception e){ /* log exception*/ } finally{ if(finder!=null) finder.close(); }
Example 3-25 Unreferencing the Resource to a Configuration Item
Finder finder = null; BaseConfigurationManager configMgr = null; ServiceManager mgr = null; try{ finder = PersistenceHelper.makeFinder(); Collection<CustomObject> custObjs = finder.findByName(CustomObject.class, "CO-1"); CustomObject custObj = custObjs.iterator().next(); mgr = PersistenceHelper.makeServiceManager(); ServiceSearchCriteria criteria = mgr.makeServiceSearchCriteria(); CriteriaItem citem = criteria.makeCriteriaItem(); citem.setValue("Service_Test_22"); citem.setOperator(CriteriaOperator.EQUALS); criteria.setName(citem); List<Service> list = mgr.findServices(criteria); Service service = list.get(0); List<ServiceConfigurationVersion> srvConfigurations = service.getConfigurations(); ServiceConfigurationItemAllocationData itemData = new ServiceConfigurationItemAllocationData(); int i = srvConfigurations.get(0).getVersionNumber(); //Write logic to get the latest ServiceConfigurationVersion of the Service. //Process the retrieved service configuration versions, //looking for one with a configState of IN_PROGRESS, DESIGNED or ISSUED. ServiceConfigurationVersion latestConfiguration; //Assign the latest ServiceConfigurationVersion //to the variable latestConfiguration List<ServiceConfigurationItem> configItems = latestConfiguration.getConfigItems(); ServiceConfigurationItem configItem = null; configMgr = PersistenceHelper.makeConfigurationManager (ServiceConfigurationItemDAO.class); ConfigurationItemSearchCriteria configItemCriteria = configMgr.makeConfigurationItemSearchCriteria(); configItemCriteria.setConfigurationItemClass(ServiceConfigurationItemDAO.class); CriteriaItem criteriaItem = configItemCriteria.makeCriteriaItem(); criteriaItem.setValue("item_name"); criteriaItem.setOperator(CriteriaOperator.EQUALS); configItemCriteria.setConfigurationItemName(criteriaItem); criteriaItem = configItemCriteria.makeCriteriaItem(); criteriaItem.setValue(version.getVersionNumber()); criteriaItem.setOperator(CriteriaOperator.EQUALS); configItemCriteria.setConfigurationVersionNumber(criteriaItem); List<InventoryConfigurationItem> configItems = configMgr.findConfigurationItems(configItemCriteria); if (!Utils.isEmpty(configItems)) { configMgr. dereferenceInventoryConfigurationItems (configItems); } } catch(Exception e){ /* log exception*/ } finally{ if(finder!=null) finder.close(); }
About Alternate Flows
The generic service fulfillment scenario assigns a custom object resource to a service configuration item. An alternate flow to this scenario may be to unassign the resource from a configuration item.
Additional alternate flows may be to manage consumable resources by creating reservations and conditions. Reservations are created to prevent a given resource to be consumed by another service. The reservation can only be redeemed successfully during resource assignment when the correct token is provided. Also, a reservation can expire if not redeemed within the expiry time period. Conditions are created to add informational or blocking codes to a given resource. A blocking condition prevents a resource from being assigned.
The alternate flows described in this section are:
Unassigning Resources from a Configuration Item
This section describes the UIM API method used to unassign the resource from a configuration item.
Table 3-28 and example code provide information about using the API method.
Table 3-28 Unassigning Resources from a Configuration Item
Topic | Information |
---|---|
Name |
BaseConfigurationManager.unallocateInventoryConfigurationItems(java.util.Collection<E> configurationItems) |
Description |
This method unassigns/deallocates resources that were previously assigned on a configuration item of a service configuration version. |
Pre-Condition |
A service configuration version exists with a custom object assigned to a configuration item of the version. |
Internal Logic |
Not applicable |
Post-Condition |
The custom object/s has been unassigned. |
Extensions |
Not applicable |
Tips |
In this example the ConsumableResource to be unassiged is custom object 'CO-1'. |
Example 3-26 Unassigning Resources from a Configuration Item
BaseConfigurationManager bcd = PersistenceHelper.makeConfigurationManager(ServiceConfigurationVersion.class); Finder f = PersistenceHelper.makeFinder(); Collection<CustomObject> custObjs = f.findById(CustomObject.class, "CO-1"); CustomObject custObj = custObjs.iterator().next(); Collection<ServiceConfigurationVersion> scvList = f.findByName(ServiceConfigurationVersion.class, "Se_123_2"); ServiceConfigurationVersion scv = (ServiceConfigurationVersion)scvList.iterator().next(); BusinessInteractionManager biMgr = PersistenceHelper.makeBusinessInteractionManager(); biMgr.switchContext(scv, null); /* Find Service Configuration Item (SCI) by: */ /* 1) Using Finder query by name, OR */ /* 2) Get Service Configuration and iterate to correct SCI */ //Collection<ServiceConfigurationItem> serviceConfigItems = // f.findByName(ServiceConfigurationItem.class, "CO Item"); //ServiceConfigurationItem sci = serviceConfigItems.iterator().next(); ServiceConfigurationItem unSci = null; Collection<ServiceConfigurationItem> sciList = scv.getConfigItems(); for (ServiceConfigurationItem sci : sciList) { if (sci.getName().equals("CO Item") && sci.getConfigAction() == ConfigurationItemAction.ASSIGN && sci.getAssignment() != null && sci.getAssignment() instanceof Assignment) { Assignment assignment = (Assignment) sci.getAssignment(); if (assignment.getResource().equals(custObj)) { unSci = sci; break; } } } if (unSci != null) { Collection<ServiceConfigurationItem> unSciList = new ArrayList<ServiceConfigurationItem>(); unSciList.add(unSci); bcd.unallocateInventoryConfigurationItems(unSciList); }
Reserving a Custom Object
This section describes the UIM API methods used to make a reservation and to reserve a custom object using the reservation. To find a custom object to reserve, you must find or create a custom object. See "Finding the Custom Object to Assign" or "Creating the Custom Object to Assign".
Table 3-29, Table 3-30, Table 3-31 and example code provide information about using the API methods.
Table 3-29 Making a Reservation
Topic | Information |
---|---|
Name |
ReservationManager.makeReservation(ConsumableResource conRes) In this example, the full signature of the method is included because there are multiple overloaded makeReservation methods. |
Description |
This method will make an instance of the appropriate Reservation class based on the type of ConsumableResource. For example, if a CustomObject is input, then a CustomObjectReservation will be returned. |
Pre-Condition |
Not applicable |
Internal Logic |
This method will determine the appropriate Reservation class to be constructed based on the input ConsumableResource. |
Post-Condition |
The caller has an instance of the appropriate Reservation class. In this scenario, it will be a CustomObjectReservation. |
Extensions |
Not applicable |
Tips |
The CustomObject instance for CO-1 should be passed as input to the method. |
Table 3-30 Reserving a Resource
Topic | Information |
---|---|
Name |
ReservationManager.reserveResource(Collection <? extends ConsumableResource> resources, Reservation reservation) |
Description |
This method will reserve the input resources. |
Pre-Condition |
The resource exists. In this scenario the resource is Custom Object CO-1. |
Internal Logic |
The input parameters are validated, and if no errors are detected each input resource is reserved. The system will generate a new reservation number. All the input resources will be reserved for this reservation number. |
Post-Condition |
The resource (Custom Object CO-1) is reserved. |
Extensions |
The RESERVATION_EXPIRATION ruleset can be customized to change the default behavior of setting the expiry date for a resource reservation. By default, a long term reservation will expire after 30 days and a short term reservation will expire after 10 minutes. |
Tips |
At least one ConsumableResource must be input. For this scenario, it will be the CustomObject instance for CO-1. The Reservation passed to the method must have the following attributes set:
Optionally, the Reservation.reason can be set. This is free form text. The startDate, endDate, and expiry can also be set, but for this example we will allow them to be defaulted by the system. |
You can also add a resource to an existing reservation number by calling the ReservationManager.addResourceToReservation method using this API method:
Table 3-31 Adding a Resource to a Reservation
Topic | Information |
---|---|
Name |
ReservationManager.addResourceToReservation(Collection <? extends ConsumableResource> resources, Reservation reservation) |
Description |
This method will reserve the input resources. |
Pre-Condition |
The resource exists. In this scenario the resource is Custom Object CO-1. |
Internal Logic |
The input parameters are validated, and if no errors are detected each input resource is reserved. The resources will be reserved with an existing reservation number. The reservedFor and reservedForType values will always be the same for all resource reservations for the same reservation number. Other reservation information, such as reason and expiry, can differ among resource reserved with the same reservation number. |
Post-Condition |
The resource (Custom Object CO-1) is reserved. |
Extensions |
The RESERVATION_EXPIRATION ruleset can be customized to change the default behavior of setting the expiry date for a resource reservation. By default, a long term reservation will expire after 30 days and a short term reservation will expire after 10 minutes. |
Tips |
At least one ConsumableResource must be input. For this scenario, it will be the CustomObject instance for CO-1. The Reservation passed to the method must have the following attributes set:
If Reservation.reservedForType or Reservation.ReservedFor are populated, they must match the equivalent values for existing resource reservations for the reservationNumber. The startDate, endDate, and expiry can also be set, but for this scenario, these dates are defaulted by the system. |
Example 3-27 Reserving a Custom Object
ReservationManager resMgr = PersistenceHelper.makeReservationManager(); ConsumableResource cr = (ConsumableResource) custObj; List<ConsumableResource> crList = new ArrayList<ConsumableResource>(); crList.add(cr); Reservation reservation = resMgr.makeReservation(cr); reservation.setReason("Future reqiurement"); reservation.setReservedFor("Order-333"); reservation.setReservedForType(ReservedForType.ORDER); reservation.setReservationType(ReservationType.LONGTERM); resMgr.reserveResource( crList, reservation); ReservationManager resMgr = PersistenceHelper.makeReservationManager(); ConsumableResource cr = (ConsumableResource) custObj; List<ConsumableResource> crList = new ArrayList<ConsumableResource>(); crList.add(cr); Reservation reservation = resMgr.makeReservation(cr); reservation.setReservationNumber("111111111"); reservation.setReservedFor("Order-333"); reservation.setReservedForType(ReservedForType.ORDER); reservation.setReservationType(ReservationType.LONGTERM); resMgr.addResourceToReservation( crList, reservation);
Unreserving a Custom Object
This section describes the UIM API methods used to unreserve a custom object. To find the custom object to unreserve, you must find the custom object. See "Finding the Custom Object to Assign".
Table 3-32 and example code provide information about using the API method.
Table 3-32 Unreserving a Custom Object
Topic | Information |
---|---|
Name |
ReservationManager.unreserveResource(Collection<? extends ConsumableResource> resources, String redeemer, ReservedForType redeemerType) In this example, the full signature of the method is included because there are multiple overloaded unreserveResource methods. |
Description |
This method will delete the reservation for the input resources. |
Pre-Condition |
The resource exists and is reserved. |
Internal Logic |
The input parameters are validated, and if no errors are detected each input resource is unreserved. The input redeemer and redeemerType must match the persisted reservation information for each of the input resources. |
Post-Condition |
The resource (custom object CO-1) is no longer reserved. |
Extensions |
Not applicable |
Tips |
At least one ConsumableResource must be input. For this scenario, it will be the CustomObject instance for CO-1. The redeemer and redeemerType are required. |
Example 3-28 Unreserving a Custom Object
ReservationManager resMgr = InventoryHelper.makeReservationManager(); ConsumableResource cr = (ConsumableResource) custObj; List<ConsumableResource> crList = new ArrayList<ConsumableResource>(); crList.add(cr); resMgr.unreserveResource(crList, "Order-333", ReservedForType.ORDER);
Creating a Blocked Condition for a Custom Object
This section describes the UIM API methods used to create a blocked condition for a custom object. To find a custom object to create the condition for, you must find or create a custom object. See "Finding the Custom Object to Assign" or "Creating the Custom Object to Assign".
Table 3-33, Table 3-34 and example code provide information about using the API methods.
Table 3-33 Making a Condition
Topic | Information |
---|---|
Name |
ConditionManager.makeCondition(ConsumableResource conRes) In this example, the full signature of the method is included because there are multiple overloaded makeCondition methods. |
Description |
This method will make an instance of the appropriate Condition class based on the type of ConsumableResource. For example, if a CustomObject is input, then a CustomObjectCondition will be returned. |
Pre-Condition |
Not applicable |
Internal Logic |
This method will determine the appropriate Condition class to be constructed based on the input ConsumableResource. |
Post-Condition |
The caller has an instance of the appropriate Condition class. In this scenario, it will be a CustomObjectCondition. |
Extensions |
Not applicable |
Tips |
The CustomObject instance for CO-1 should be passed as input to the method. |
Table 3-34 Creating Conditions
Topic | Information |
---|---|
Name |
ConditionManager.createConditions |
Description |
This method will create a condition on each of the input resources. |
Pre-Condition |
The resource exists. In this scenario the resource is Custom Object CO-1. |
Internal Logic |
The input Condition instances are validated, and if no errors are detected a condition is created for each resource specified in the input Condition collection. |
Post-Condition |
The resource (custom object CO-1) has a blocked condition. |
Extensions |
Not applicable |
Tips |
The Condition passed to the method must have the following attributes set:
Optionally, the Condition.validFor can be set with a startDate and endDate value. If startDate is not specified, it is defaulted to the current date. If endDate is not specified, it is defaulted to the java max date value of 18- Jan-2038. Optionally, the Condition.description can be set. This is free form text. |
Example 3-29 Creating a Blocked Condition for a Custom Object
ConditionManager conMgr = PersistenceHelper.makeConditionManager(); Collection<Condition> inputCons = new ArrayList<Condition>(); Finder f = PersistenceHelper.makeFinder(); Collection<CustomObject> custObjs = f.findById(CustomObject.class, "CO-1"); CustomObject custObj = custObjs.iterator().next(); Condition con = conMgr.makeCondition(custObj); con.setDescription("Test Failure"); con.setReason("Under Repair"); con.setType(ConditionType.BLOCKED); Date now = new Date(); Date later = getEndDate(now); /* call to an utility method */ con.setValidFor(new TimePeriod(now, later)); con.setResource(custObj); con.setMaster(true); inputCons.add(con); Collection <? extends Condition> cons = conMgr.createConditions(inputCons);
Deleting a Blocked Condition for a Custom Object
This section describes the UIM API methods used to delete a blocked condition from a custom object. To find the custom object to delete the blocked condition from, you must find the custom object. See "Finding the Custom Object to Assign". To delete the condition from the custom object, you must first find the condition to be deleted using the API method described here.
Table 3-35, Table 3-36, Table 3-37 and example code provide information about using the API methods.
Table 3-35 Making a Condition Search Criteria
Topic | Information |
---|---|
Name |
ConditionManager.makeConditionSearchCriteria |
Description |
This method will make an instance of ConditionSearchCriteria. |
Pre-Condition |
Not applicable |
Internal Logic |
Not applicable |
Post-Condition |
The caller has an instance of ConditionSearchCriteria. |
Extensions |
Not applicable |
Tips |
Not applicable |
Table 3-36 Finding Conditions
Topic | Information |
---|---|
Name |
ConditionManager.findConditions |
Description |
This method retrieves conditions based on input criteria. |
Pre-Condition |
The custom object to find conditions for has been selected. The desired condition exists. |
Internal Logic |
The database is queried for conditions meeting the input criteria. Conditions matching the criteria are returned. |
Post-Condition |
The desired condition has been retrieved. |
Extensions |
Not applicable |
Tips |
In this scenario, the following CriteriaItems could be populated on the ConditionSearchCritiera:
If a list of conditions is returned, the list will need to be iterated to select the desired condition to be deleted. |
Table 3-37 Deleting Conditions
Topic | Information |
---|---|
Name |
ConditionManager.deleteConditions |
Description |
This method will delete conditions on resources. |
Pre-Condition |
The condition to be deleted has been selected. |
Internal Logic |
The input Condition instances are validated, and if no errors are detected the conditions are deleted. |
Post-Condition |
The resource (Custom Object CO-1) no longer has the blocked condition. |
Extensions |
Not applicable |
Tips |
Not applicable |
Example 3-30 Deleting a Blocked Condition from a Custom Object
Finder f = PersistenceHelper.makeFinder(); Collection<CustomObject> custObjs = f.findById(CustomObject.class, "CO-1"); CustomObject custObj = custObjs.iterator().next(); ConditionManager conMgr = PersistenceHelper.makeConditionManager(); ConditionSearchCriteria criteria = conMgr.makeConditionSearchCriteria(); CriteriaItem res = criteria.makeCriteriaItem(); res.setValue(custObj); res.setOperator(CriteriaOperator.EQUALS); criteria.setResource(res); CriteriaItem type = criteria.makeCriteriaItem(); type.setValue(ConditionType.BLOCKED); type.setOperator(CriteriaOperator.EQUALS_IGNORE_CASE); criteria.setType(type); Collection <CustomObjectCondition> cons = conMgr.findConditions(criteria); CustomObjectCondition con = cons.iterator().next(); conMgr.deleteConditions(cons);
Setting Characteristic Values for the Service Configuration Item
The following APIs are used to set characteristic values on a service configuration item. The set of allowable characteristic values for a given service configuration item are defined by the service configuration specification used to create the service configuration.
The following shows a configuration item hierarchy that has two characteristic values associated with the Customer Equipment (CE) Router ITEM:
ITEM - Site
-
ITEM - Customer Equipment Router
-
Specification - Logical Device
-
Characteristic - Customer
-
Instructions - Characteristics
-
Additional Information
-
The Configuration ITEMs are used to create the Service Configuration Item instances. Characteristics will be related to the Service Configuration Item. Since Service Configuration Item is a Characteristic Extensible entity, we can use the CharacteristicManager.init API to initialize the set of characteristic values on the entity. In the example above, the two Characteristics under the Customer Equipment Router ITEM would create two instances on the ServiceConfigurationItemCharacteristic, and if there is default values defined, it is also copied.
Table 3-38 and example code provide information about using the API method.
Table 3-38 Setting Characteristic Values for the Service Configuration Item
Topic | Information |
---|---|
Name |
CharacteristicManager.init(CharacteristicExtensible<CharValue> characteristicExtensible, Specification spec) |
Description |
This method initializes the CharacteristicExtensible entity. In this case, the ServiceConfigurationItem). It sets the default value for each characteristic which has one. |
Pre-Condition |
A service configuration item exists and the InventoryConfigurationSpec is known. |
Internal Logic |
The InventoryConfigurationSpec is used to get the CharacteristicSpecUsage, from the CharacteristicSpecUsage to get the CharacteristicSpecification, so that the default spec value can be retrieved and set to the CharValue. And the Charvalue will be set to the Service configuration item. |
Post-Condition |
ServiceConfigurationItem has the default characteristics set. |
Extensions |
Not applicable |
Tips |
Not applicable |
Note:
When creating a Service Configuration Item, call CharacteristicManager.init (CharacteristicExtensible<CharValue> characteristicExtensible, Specification spec) method to initiate the default characteristics value.
Example 3-31 Setting Characteristic Values for the Service Configuration Item
CharacteristicManager characteristicManager = PersistenceHelper.makeCharacteristicManager(); // Initialize the characteristics to the item characteristicManager.init((CharacteristicExtensible)childConfigItem, inventoryConfigurationSpec); // Get the characteristics from service config item HashSet<CharValue> characteristics = serviceConfigItem.getCharacteristics(); // Loop through the HashSet of characteristics and set the value as defined for (CharValue charValue : characteristics) { charValue.setValue("myValue"); charValue.setLabel("myLabel"); }
Finding Configuration Item and Setting Characteristics
Characteristics can be added to the service configuration items. The service configuration items are maintained on each service configuration version as a tree, as specified in Design Studio. This is to make sure the history of the characteristics are set or unset across the service configuration versions.
These characteristics cannot be added on service configuration version. They can be added only on the Service Configuration Items. The characteristics added directly under the Service Configuration Specification tree are added to the top-most item of the service configuration version, called CONFIG item.
Unlike other entities, characteristics cannot be added to a service configuration item when it is created, except for the default characteristics.
Example 3-32 Creating Characteristics on Top-most Service Configuration Item
Service service = null; Finder f = null; try{ f = PersistenceHelper.makeFinder(); Collection<Service> services = f.findByName(Service.class, "service_name"); Service = Services.iterator.next(); ServiceConfigurationVersion version = null; List<ServiceConfigurationVersion> configs = service.getConfigurations(); for (ServiceConfigurationVersion config : configs) { if (config.getAdminState().equals(BusinessInteractionState. IN_PROGRESS)) { version = config; } } if(version != null){ ServiceConfigurationItem configItem = (ServiceConfigurationItem)version.getConfigItemTypeConfig(); HashSet<CharacteristicSpecification> charSpecs = new HashSet<CharacteristicSpecification>(); charSpecs = CharacteristicHelper.getCharacteristicSpecifications(configSpec); if (!charSpecs.isEmpty()) { Set<ServiceConfigurationItemCharacteristic> sciChars = new HashSet<ServiceConfigurationItemCharacteristic>(); ServiceConfigurationItemCharacteristic sciChar = null; for (CharacteristicSpecification charSpec : charSpecs) { sciChar = configItem.makeCharacteristicInstance(); sciChar.setName(charSpec.getName()); if (charSpec.getControlType() == ControlType.CALENDAR){ sciChar.setValue("07/15/2019"); }else if(charSpec.getControlType() == ControlType.CHECKBOX){ sciChar.setValue("true"); }else if(charSpec.getControlType() == ControlType.DROPDOWN_LIST){ Set<CharacteristicSpecValue> values = charSpec.getValues(); sciChar.setValue(((DiscreteCharSpecValue)values.iterator().next()).getValue()); }else if(charSpec.getControlType() == ControlType.TEXT_FIELD){ if(charSpec.getValueType() == ValueType.NUMERIC) sciChar.setValue("500"); else if(charSpec.getValueType() == ValueType.URL) sciChar.setValue("http://oracle.com"); else sciChar.setValue("pipe testing"); } sciChar.setCharacteristicSpecification(charSpec); sciChars.add(sciChar); } configItem.setCharacteristics(sciChars); } catch(Exception e){ /*log exception*/ } finally{ if(f!=null) f.close(); }
Example 3-33 Creating Characteristics On Any Level Service Configuration Item
Service service = null; Finder f = null; BaseConfigurationManager configMgr = null; try{ f = PersistenceHelper.makeFinder(); Collection<Service> services = f.findByName(Service.class, "service_name"); Service = Services.iterator.next(); ServiceConfigurationVersion version = null; List<ServiceConfigurationVersion> configs = service.getConfigurations(); for (ServiceConfigurationVersion config : configs) { if (config.getAdminState().equals(BusinessInteractionState. IN_PROGRESS)) { version = config; } } if(version != null){ ServiceConfigurationItem configItem = null; configMgr = PersistenceHelper.makeConfigurationManager (ServiceConfigurationItemDAO.class); ConfigurationItemSearchCriteria configItemCriteria = configMgr.makeConfigurationItemSearchCriteria(); configItemCriteria.setConfigurationItemClass(ServiceConfigurationItemDAO.class); CriteriaItem criteriaItem = configItemCriteria.makeCriteriaItem(); criteriaItem.setValue("item_name"); criteriaItem.setOperator(CriteriaOperator.EQUALS); configItemCriteria.setConfigurationItemName(criteriaItem); criteriaItem = configItemCriteria.makeCriteriaItem(); criteriaItem.setValue(version.getVersionNumber()); criteriaItem.setOperator(CriteriaOperator.EQUALS); configItemCriteria.setConfigurationVersionNumber(criteriaItem); List<InventoryConfigurationItem> configItems = configMgr.findConfigurationItems(configItemCriteria); if(!Utils.isEmpty()) configItem = configItems.iterator.next(); HashSet<CharacteristicSpecification> charSpecs = new HashSet<CharacteristicSpecification>(); charSpecs = CharacteristicHelper.getCharacteristicSpecifications(configSpec); if (!charSpecs.isEmpty()) { Set<ServiceConfigurationItemCharacteristic> sciChars = new HashSet<ServiceConfigurationItemCharacteristic>(); ServiceConfigurationItemCharacteristic sciChar = null; for (CharacteristicSpecification charSpec : charSpecs) { sciChar = configItem.makeCharacteristicInstance(); sciChar.setName(charSpec.getName()); if (charSpec.getControlType() == ControlType.CALENDAR){ sciChar.setValue("07/15/2019"); }else if(charSpec.getControlType() == ControlType.CHECKBOX){ sciChar.setValue("true"); } else if(charSpec.getControlType() == ControlType.DROPDOWN_LIST){ Set<CharacteristicSpecValue> values = charSpec.getValues(); sciChar.setValue(((DiscreteCharSpecValue)values.iterator().next()).getValue()); }else if(charSpec.getControlType() == ControlType.TEXT_FIELD){ if(charSpec.getValueType() == ValueType.NUMERIC) sciChar.setValue("500"); else if(charSpec.getValueType() == ValueType.URL) sciChar.setValue("http://oracle.com"); else sciChar.setValue("pipe testing"); } sciChar.setCharacteristicSpecification(charSpec); sciChars.add(sciChar); } configItem.setCharacteristics(sciChars); } catch(Exception e){ /*log exception*/ } finally{ if(f!=null) f.close(); }
Example 3-34 Modifying Characteristics on Service Configuration Item
Service service = null; Finder f = null; BaseConfigurationManager configMgr = null; try{ f = PersistenceHelper.makeFinder(); Collection<Service> services = f.findByName(Service.class, "service_name"); Service = Services.iterator.next(); ServiceConfigurationVersion version = null; List<ServiceConfigurationVersion> configs = service.getConfigurations(); for (ServiceConfigurationVersion config : configs) { if (config.getAdminState().equals(BusinessInteractionState. IN_PROGRESS)) { version = config; } }if(version != null){ ServiceConfigurationItem configItem = null;configMgr = PersistenceHelper.makeConfigurationManager (ServiceConfigurationItemDAO.class); ConfigurationItemSearchCriteria configItemCriteria = configMgr.makeConfigurationItemSearchCriteria(); configItemCriteria.setConfigurationItemClass(ServiceConfigurationItemDAO.class); CriteriaItem criteriaItem = configItemCriteria.makeCriteriaItem(); criteriaItem.setValue("item_name"); criteriaItem.setOperator(CriteriaOperator.EQUALS); configItemCriteria.setConfigurationItemName(criteriaItem); criteriaItem = configItemCriteria.makeCriteriaItem(); criteriaItem.setValue(version.getVersionNumber()); criteriaItem.setOperator(CriteriaOperator.EQUALS); configItemCriteria.setConfigurationVersionNumber(criteriaItem); List<InventoryConfigurationItem> configItems = configMgr.findConfigurationItems(configItemCriteria);if(!Utils.isEmpty())configItem = configItems.iterator.next(); HashSet<CharacteristicSpecification> charSpecs = new HashSet<CharacteristicSpecification>(); charSpecs = CharacteristicHelper.getCharacteristicSpecifications(configSpec); if (!charSpecs.isEmpty()) { Set<ServiceConfigurationItemCharacteristic> sciChars = new HashSet<ServiceConfigurationItemCharacteristic>(); ServiceConfigurationItemCharacteristic sciChar = null; for (CharacteristicSpecification charSpec : charSpecs) { sciChar = configItem.makeCharacteristicInstance(); String charName = sciChar.setName(charSpec.getName()); if (charName.equals("char_name_12)){ sciChar.setValue("updated_valued"); } sciChar.setCharacteristicSpecification(charSpec); sciChars.add(sciChar); } configItem.setCharacteristics(sciChars);}catch(Exception e){/*log exception*/}finally{ if(f!=null) f.close();}
About Alternate Flows
The generic service fulfillment scenario sets characteristic values for the service configuration item. An alternate flow to this scenario may be to unset characteristic values from the service configuration item.
The alternate flow described in this section is "Unsetting Characteristic Values for the Service Configuration Item".
Unsetting Characteristic Values for the Service Configuration Item
The following API is to unset characteristic values on a service configuration.
The following example code provides information about using the API method.
Note:
From ServiceConfigurationItem, get the characteristics and then delete the ServiceConfigurationItemCharacteristics to remove the characteristic values. If only one particular characteristic needs to be deleted for the ServiceConfigurationItem, then a name match should be compared before deleting the ServiceConfigurationItemCharacteristic.
Example 3-35 Unsetting Characteristic Values for the Service Configuration
HashSet<ServiceConfigurationItemCharacteristic> characteristics = serviceConfigItem.getCharacteristics(); Iterator<ServiceConfigurationItemCharacteristic> itr = characteristics.iterator(); while (itr.hasNext()) { ServiceConfigurationItemCharacteristic characteristic = itr.next(); if characteristic.getName().equals("myName") itr.remove();}
Transitioning the Lifecycle Status
The transition APIs are used for transitioning the lifecycle status of a given entity which implements the LifeCycleManaged interface. The state transition rules are defined in the *-transitions.xml files.
Table 3-39 and example code provide information about using the API method.
Table 3-39 Transitioning the Lifecycle Status
Topic | Information |
---|---|
Name |
TransitionManager.transition |
Description |
Transitions a LifeCycleManaged entity by finding the matching transition definition which has the business action defined and the object activity defined the same as the input parameters, and which from business state matches the entity's business state. |
Pre-Condition |
TransitionManager.isValidTransition has successfully validated that the specified business action can trigger the transition of either the business state or the object state. |
Internal Logic |
Finds a matching transition definition. For a version object it matches on business action and object activity only. Other objects are matched from most specific to least specific in the following order:
Switches to a Business Interaction context if applicable and updates the business or object state of the object and its dependents based on the transition definition. |
Post-Condition |
The object state or business state is updated. |
Extensions |
BusinessInteractionSpec_TransitionManager_validateBusinessStateTransitions BusinessInteractionSpec_TransitionManager_validateObjectStateTransitions |
Tips |
See UIM Developer's Guide for more information. |
Example 3-36 Transitioning the Lifecycle Status
TransitionManager transitionManager = PersistenceHelper.makeTransitionManager(service); boolean success = false; success = transitionManager.transition(service, ServiceAction.COMPLETE);
Example 3-37 Performing Operations Under Business Interaction Context
To perform operations such as assign, unassign, reference, or unreferenced and set, unset, or modify characteristics, you need to make sure the business interaction context is set before executing the code.
Add the following code before executing the code:
BusinessInteraction currentBI = (BusinessInteraction)UserEnvironmentFactory.getBusinessInteraction(); if(currentBI == null){BusinessInteraction bi = (BusinessInteraction)f.findById(BusinessInteraction.class, "biId").iterator().next(); currentBI = bi; } BusinessInteractionManager biMgr = PersistenceHelper.makeBusinessInteractionManager(); biMgr.switchContext(currentBI, null);
After the operation is complete, block the switch back to the current context by entering the following code:
currentBI = null; biMgr.switchContext(currentBI, null);
Creating a Property Location
Example 3-38 provides information about creating a property location.
Example 3-38 Creating a Property Location
Finder finder = null; PropertyLocation propertyLocation = null; PropertyAddress propertyAddress = null; FeedbackProviderImpl.getFeedbackProvider().reset(); try { LocationManager locationManager = PersistenceHelper.makeLocationManager(); finder = PersistenceHelper.makeFinder(); BusinessInteractionManager bimgr = PersistenceHelper.makeBusinessInteractionManager(); bimgr.switchContext((String)null, null); String networkLocationCode ="ALLNTX"; PropertyLocation networkLocation = this.findNetworkEntityLocation(networkLocationCode); //If PropertyLocation is not already created then only create it if (networkLocation == null) { FeedbackProviderImpl.getFeedbackProvider().reset(); propertyAddress = locationManager.makePropertyAddress(); propertyLocation = locationManager.makePropertyLocation(); propertyAddress.setStreetAddress("ALLNTX_street1"); propertyAddress.setCity("ALLN_city1")); propertyAddress.setState("TX1"); propertyAddress.setCountry("US"); propertyAddress.setIsValidated(true); propertyAddress.setIsNonValidatedAddressAccepted(false); propertyAddress.setIsPrimaryAddress(true); Set<PropertyAddress> addressSet = new HashSet<PropertyAddress>(1); addressSet.add(propertyAddress); propertyLocation.setPropertyAddresses(addressSet); propertyLocation.setNetworkLocationCode(networkLocationCode); propertyLocation.setLatitude("34"); propertyLocation.setLongitude("75"); Collection<PropertyLocation> list = new ArrayList<PropertyLocation>(1); list.add(propertyLocation); List<PropertyLocation> propLocobjects = locationManager.createPropertyLocation(list); networkLocation = propLocobjects.get(0); networkLocation.connect(); } List<NetworkEntityCode> networkEntityCodes = new ArrayList<NetworkEntityCode>(); List<String> NECs = {"0,1,2,3,4"}; if (!Utils.isEmpty(NECs)) { for (String necStr : NECs) { NetworkEntityCode existingNEC = this.findNetworkEntityCode(networkLocation, necStr); if (existingNEC == null) { NetworkEntityCode nec = locationManager.makeNetworkEntityCode(); nec.setName(necStr); networkEntityCodes.add(nec); } } } if (!Utils.isEmpty(networkEntityCodes)) { locationManager.associateNetworkEntityCodeToNetworkLocation(networkEntityCodes, networkLocation); }
Referring Property Location to a Service Configuration Item
A property location can be referenced to service configuration item. It cannot be assigned to any service configuration item.
See "Referencing the Resource to a Configuration Item" for more information.
About Undo Actions
You can Undo and unassign a resource for a configuration item that is in Pending Unassign status.
This transition happens when all the following conditions are met:
-
The resource is in a pending status in the current configuration.
-
The current configuration is in progress.
-
The resource belongs to a configuration item in an earlier configuration for the same service.
-
The earlier configuration is also in progress.
Table 3-40 Reallocating a Resource on the Service Configuration Item
Topic | Information |
---|---|
Name |
BaseConfigurationManager.reallocateEntityConfigurationItems(Collection<E> configurationItems) |
Description |
This method reallocates the de-allocated entities on a given configuration item. The configuration version cannot be in a completed or cancelled state. |
Pre-Condition |
A service configuration item exists on which an assignment was just unassigned. |
Internal Logic |
The assignment state on the consumable resource is transitioned back to ASSIGNED state. |
Post-Condition |
The resource is assigned again. |
Extensions |
Not Applicable |
Tips |
Not Applicable |
You can undo the removal of a resource reference for a configuration item that is in Pending Un-reference status. This transition happens when all the following conditions are met:
-
The resource is in a pending status in the current configuration.
-
The resource is in a pending status in the current configuration.
-
The resource belongs to a configuration item in an earlier configuration for the same service.
-
The earlier configuration is also in progress.
Table 3-41 Referencing a Resource on the Service Configuration Item
Topic | Information |
---|---|
Name |
BaseConfigurationManager.rereferenceInventoryConfigurationItems(Collection<E> configurationItems) |
Description |
This method reallocates the de-allocated entities on a given configuration item. The configuration version cannot be in a completed or cancelled state. |
Pre-Condition |
A service configuration item exists on which an assignment was just unreferenced. |
Internal Logic |
The assignment state on the consumable resource is transitioned back to REFERENCED state. |
Post-Condition |
The resource is referenced again. |
Extensions |
Not Applicable |
Tips |
Not Applicable |
Example 3-39 Referencing the Resource to a Configuration Item
Finder f = null; BaseConfigurationManager bcd = null; try { f = PersistenceHelper.makeFinder(); PersistenceHelper.makeBusinessInteractionManager().switchContext((String)null,null); ServiceConfigurationVersion configuration = f.findByName(ServiceConfigurationVersion.class, configId).iterator().next(); InventoryConfigurationItem icToAssign = null; Collection<InventoryConfigurationItem> dereferenceList = new ArrayList<InventoryConfigurationItem>(); for (InventoryConfigurationItem ic : configuration.getConfigItems()) { if (ConfigurationType.CONFIG.equals(ic.getConfigType())) continue; if(ic.getReference() != null){ PersistenceHelper.makeBusinessInteractionManager().switchContext(configuration,null); if(ConfigurationReferenceState.PENDING_UNREFERENCE.equals( ((ConfigurationReference)ic.getReference()).getAdminState()) && ic.getDepChildConfigItem() == null){ dereferenceList.add(ic); } } } f.reset(); CustomObject coToAssign = f.findByName(CustomObject.class, "CO2_ASSIGN0009" ).iterator().next(); bcd = PersistenceHelper.makeConfigurationManager(configuration.getClass()); bcd.rereferenceInventoryConfigurationItems(dereferenceList); } catch (Throwable t) { catchThrowable(t, ut); } finally { if (f != null) { f.close(); } }