Implementing a Generic Service Fulfillment 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 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 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 run. 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.

Figure 3-3 Generic Service Example

Description of "Figure 3-3 Generic Service Example"

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: Reservation.reservedFor (Free form text identifying the reserver.) Resevation.reservedForType (A ReservedForType such as CUSTOMER.) Reservation.reservationType (This would be set to ReservationType.LONGTERM for this scenario.) 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: Reservation.reservationNumber An existing resource reservation must already exist with this same reservation number. Reservation.reservationType In the generic service fulfillment scenario, this would be set to ReservationType.LONGTERM. 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: Condition.resource This should be set to the CustomObject instance for CO-1. Condition.reason This is free form text describing the reason for the condition. For example, Under Repair. Condition.type This should be set to ConditionType.BLOCKED. 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: resource The CustomObject instance for CO-1. type ConditionType.BLOCKED 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: Match businessAction, objectActivity, entity type, and the specification. Match businessAction, objectActivity, entity type. Match businessAction, objectActivity. 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 running the code.

Add the following code before running 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();
  }
}