2 Working with the Service Fulfillment Web Service

Reference Schemas

Within the ZIP file, the reference schemas are located in the ora_uim_webservices/wsdl/referenceSchemas directory. The reference schemas define common elements used by more than one operation. So, the elements are defined in one place and then referenced.

The reference schemas are:

• InventoryCommon.xsd

• InventoryFaults.xsd

• FaultRoot.xsd

Web Service Schemas

Within the ZIP file, the web service schemas are located in the ora_uim_webservices/wsdl/schemas directory. The web service schemas define elements specific to the web service, such as the request structures, the response structures, and any fault structures.

The web service schemas are defined in the following files:

• InteractionMessages.xsd

• ConfigurationMessages.xsd

Business Schemas

Within the ZIP file, the business schemas are located in the ora_uim_business/schemas directory. Each web service operation wraps a call (or multiple calls) to the UIM business layer, which is exposed through APIs. The wrapped APIs are the same APIs that the UIM UI calls in response to user input. The business layer APIs are based on functional area, as are the business schemas.

The business schemas are:

• Activity.xsd

• BusinessInteraction.xsd

• Configuration.xsd

• Connectivity.xsd

• CustomNetworkAddress.xsd

• CustomObject.xsd

• Entity.xsd

• InventoryGroup.xsd

• IPAddress.xsd

• LogicalDevice.xsd

• MediaStream.xsd

• Network.xsd

• NetworkAddress.xsd

• Number.xsd

• Party.xsd

• PhysicalDevice.xsd

• Place.xsd

• Property.xsd

• PropertyLocation.xsd

• Role.xsd

• Service.xsd

• Specification.xsd

• Structure.xsd

Business Interaction

captureInteractionRequest captures one interaction per request (lines 02 through 68). For each interaction, the request captures one or more items (lines 12 through 56), and one or more child interactions (lines 57 through 66).

When calling CaptureInteraction, the request must specify an interaction action (line 05) of CREATE or CHANGE. The interaction <action> element is defined as an enumeration in the BusinessInteraction.xsd schema file.

If the interaction action is CREATE, the request must provide an arbitrary name for the business interaction (line 07) being created, and the business interaction specification name (within line 04) upon which the business interaction is being based. (The specification name is typically Service Order, which is the business interaction specification provided in the ora_uim_basespecifications cartridge.) The request can optionally provide an external ID for the business interaction. You do not need to provide the specification entityClass enumeration value of BusinessInteraction; this is assumed based on the placement of the specification structure within the <interaction> element.

If the interaction action is CHANGE, the request must provide the external ID (within line 08) or the business interaction ID (line 06) to indicate the business interaction to change, and the actual changes.

Business Interaction Item

captureInteractionRequest captures one or more items per interaction. Example 2-1 shows just one item (lines 12 through 56). To include multiple items, replicate the item and place it between lines 56 and 57.

Each item defines an interaction action (line 14), which must be ADD regardless of the request.

Business Interaction Item Parameter

Each business interaction item optionally specifies one or more input parameters. For these parameters, the complex type ParameterType is defined as the following:

<xsd:element maxOccurs="unbounded" minOccurs="0"
    name="parameter" type="invbi:ParameterType">
</xsd:element>

The value element definition within ParameterType is the following:

<xs:element name="value" type="xsd:anyType">

For the value element with the anyType declaration, you can use any valid XML schema type that provides the following:

• An entity in UIM

• A type of StructuredType, defined in the business schema file Structure.xsd

Use the StructuredType complex type to pass entities with multiple property values. Example 2-3 provides sample XML for using StructuredType with one level of property information.

<invbi:parameter>
    <invbi:name>StructuredType Parameter</invbi:name>
    <invbi:value xsi:type="invstruc:StructuredType">
        <invstruc:name>CPE Device 1</invstruc:name>
        <invstruc:property>
        <invprop:name>CPE_MAC</invprop:name>
        <invprop:value xsi:type="xs:string">01-23-45-67-89-ab</invprop:value>
        </invstruc:property> 
        <invstruc:property> 
        <invprop:name>CPE_Model</invprop:name>
        <invprop:value xsi:type="xs:string">PBS</invprop:value>
        </invstruc:property>
        <invstruc:property>
        <invprop:name>CPE_Brand</invprop:name>
        <invprop:value xsi:type="xs:string">Motorola</invprop:value>
        </invstruc:property>
        <invstruc:property>
        <invprop:name>CPE_SerialNumber</invprop:name>
        <invprop:value xsi:type="xs:string">4TUI-632552</invprop:value>
        </invstruc:property>
     </invbi:value>
</invbi:parameter>

If you have properties with hierarchical information, you create the parameter list with the StructuredType including a hierarchy. Example 2-4 provides sample XML for using StructuredType including a child element representing hierarchical property information.

<invbi:parameter>
    <invbi:name>Structured Param </invbi:name>
    <invbi:value xsi:type="invstruc:StructuredType">
        <invstruc:name>CPE Device</invstruc:name>
        <invstruc:property>
        <invprop:name>CPE_MAC</invprop:name>
        <invprop:value xsi:type="xs:string">1.2.3.4</invprop:value>
        </invstruc:property>
        <invstruc:property>
        <invprop:name>CPE_Model</invprop:name>
        <invprop:value xsi:type="xs:string">MI6</invprop:value>
        </invstruc:property>
        <invstruc:property>
        <invprop:name>CPE_Brand</invprop:name>
        <invprop:value xsi:type="xs:string">Motorola</invprop:value>
        </invstruc:property>
        <invstruc:property>
        <invprop:name>CPE_SerialNumber</invprop:name>
        <invprop:value xsi:type="xs:string">838373723</invprop:value>
        </invstruc:property>
        <invstruc:child xsi:type="invstruc:StructuredType">
            <invstruc:name>Channel Pack</invstruc:name>
            <invstruc:property>
            <invprop:name>CPE_MAC</invprop:name>
            <invprop:value xsi:type="xs:string">1.2.3.5</invprop:value>
            </invstruc:property>
            <invstruc:property>
            <invprop:name>code</invprop:name>
            <invprop:value xsi:type="xs:string">code value A</invprop:value>
            </invstruc:property>                          
        </invstruc:child>
    </invbi:value>
</invbi:parameter>

Service

Each item defines a service, as shown in Example 2-1 (lines 15 through 51). For each service, you must supply a valid Service specification name (within line 16) from which to create an instance of the specification in UIM.

Each service also defines a service action (line 18). The service action is not an enumeration, as are the interaction action and item action. Rather, there are several predefined service actions that UIM code recognizes. You can extend the list of service actions and their corresponding processes through custom rulesets. Service actions are further explored in "Customizing ProcessInteraction".

Specifically, there are some service actions that the core code recognizes. Through a custom ruleset, you can extend the input service actions and map each custom service action to one of the service actions that the core code recognizes.

The service may also specify a place (lines 22 through 35) or a party (lines 36 through 49) to associate to the service.

The request and response use the same structure. Most of the elements are used only by the response, so there are numerous elements that are not used by the request. For example, a service and configuration for the place (lines 24 through 34), a service and configuration for the party (lines 38 through 48), and the configuration for the service itself (line 50).

Associated Business Interaction

captureInteractionRequest captures one or more child interactions per interaction. Example 2-1 shows just one child interaction (lines 57 through 66). To include multiple interactions, replicate the child interaction (lines 57 through 66) and place it between lines 66 and 67.

ExecuteProcess Element

The <executeProcess> element (line 69) is defined after the interaction and applies to the interaction. This element is defined as a Boolean and is used only by CaptureInteraction. When the value of <executeProcess> is true, CaptureInteraction executes and, upon completion, ProcessInteraction executes. This eliminates the need to place two separate web service calls; one for CaptureInteraction and one for ProcessInteraction. When the value of <executeProcess> is false, just CaptureInteraction executes. The default value is false.

ResponseLevel Element

captureInteractionRequest, processInteractionRequest, getInteractionRequest, and updateInteractionRequest define the <responseLevel> element (line 70). This element specifies an enumeration value, as defined by the InteractionResponseLevelEnum enumeration in the InteractionMessages.xsd schema file.

Depending on the enumeration value specified in the request, the level of information returned by the response can vary:

• INTERACTION

  Returns just the interaction information.

• INTERACTION_ITEM

  Returns the interaction and item information.

• INTERACTION_ITEM_ENTITY

  Returns the interaction, item, and entity information.

• INTERACTION_ITEM_ENTITY_CONFIGURATION (default option)

  Returns the interaction, item, entity, and configuration information.

• INTERACTION_ITEM_ENTITY_CONFIGURATION_EXPANDED

  Returns the interaction, item, entity, configuration, and any child configurations.

Service Configuration Association

Regarding the Associate Service Configuration to BI box in Figure 2-4: A service configuration is indirectly associated to a business interaction through the business interaction items. This association is shown by the dotted line in Figure 2-5. To associate the service configuration to the business interaction, ProcessInteraction:

• Creates business interaction items based on the items for the interaction in the request

• Associates the business interaction items to the service configuration

Figure 2-5 Association of Service Configuration to BI

Description of ''Figure 2-5 Association of Service Configuration to BI''

Modeling the Service in Design Studio

Before you begin customizing ProcessInteraction, you must model your service within an Inventory project in Design Studio. For example, your Inventory project must define specifications that describe your service, service configuration, and service configuration items that fulfill the service in UIM.

See UIM Concepts for information about services and service configurations, and see the Design Studio Help for information about modeling services in Design Studio.

Customizing Service Actions

captureInteractionRequest defines a service action for each service in the request. The service action is not an enumeration; rather, there are several predefined actions (called entity actions) that UIM code recognizes and processes.

The UIM-defined entity actions are:

• create

• change

• delete

• disconnect

• suspend

• resume

• no_action

The web service recognizes two additional entity actions that enable the web service to perform additional functionality. They are:

• suspendWithConfiguration

• resumeWithConfiguration

For example, the suspend entity action suspends a service but does not touch the service configuration. The suspendWithConfiguration entity action suspends a service and creates a new service configuration version. Similarly, the resume entity action resumes a suspended service but does not modify the service configuration. The resumeWithConfiguration entity action resumes a suspended a service and creates a new service configuration version. (For either action, if an existing service configuration version does not exist, an error is thrown because the service configuration must already exist if you are suspending or resuming it.)

Customizations are based on the service action (Example 2-1, line 18) and parameters (Example 2-1, lines 52 through 55). So, you must establish a finite list of service actions and parameters that can be specified in the request, which can then be recognized by, and processed by, the custom code.

To customize service actions:

1. Determine the finite list of service actions and parameters to process.

   If your finite list of service actions includes only UIM-defined entity actions (and no custom service actions), you do not need to perform this procedure.

2. In Design Studio, open the Project editor.

   This is the same project that contains the specifications you created to model your service.

3. Click the Dependency tab.

4. Add the ora_uim_base_extpts cartridge to the list of dependencies.

5. Save the project.

6. Create a ruleset.

   Write custom code that maps your custom service actions to entity actions. The custom code can be in the ruleset, or in Java code that the ruleset calls. For information about writing custom rulesets, see UIM Developer's Guide.

7. Save the ruleset.

8. Create a ruleset extension point and configure it as follows:

   1. In Ruleset, select your ruleset.

   2. In Point, select the BusinessInteractionManager_getEntityAction base extension point.

   3. In Placement, select INSTEAD.

   4. Save the ruleset extension point.

9. Open your Service specification.

10. Click the Rules tab.

11. Click Select.

12. Select your ruleset extension point.

13. Click OK.

14. Save the Service specification.

15. Build the project.

16. Deploy the resultant cartridge.

Customizing the Automation of Service Configurations

To customize the automation of service configurations:

1. In Design Studio, open the Project editor.

   This is the same project that contains the specifications that your created to model your service.

2. Click the Dependency tab.

3. Add the ora_uim_base_extpts cartridge to the list of dependencies.

4. Save the project.

5. Create a ruleset.

   Write custom code that processes the business interaction items, evaluates the mapped entity actions and custom parameters, and calls the appropriate API methods to create the service in UIM. See "Developing the Custom Code" for more information.

   The custom code can be in the ruleset, or in Java code that the ruleset calls. For information about writing custom rulesets, see UIM Developer's Guide.

6. Save the ruleset.

7. Create a ruleset extension point and configure it as follows:

   1. In Ruleset, select your ruleset.

   2. In Point, select the BaseConfigurationManager_automateConfiguration base extension point.

   3. In Placement, select INSTEAD.

   4. Save the ruleset extension point.

8. Open your Service Configuration specification.

9. Click the Rules tab.

10. Click Select.

11. Select your ruleset extension point.

12. Click OK.

13. Save the Service Configuration specification.

14. Build the project.

15. Deploy the resultant cartridge.

ProcessInteraction Example

The following list describes some project content your implementation may require to run ProcessInteraction.

• Numerous custom specifications and characteristics

  At a minimum, your project needs to define a Service specification, a Service Configuration specification, and resource-specific specifications, such as Telephone Number, Physical Device, Logical Device, and so forth. Your project may also require characteristics in which to store resource-specific data.

• AUTOMATE_MY_CONFIGURATION.ruleset

  This is a custom ruleset that is the entry point into the custom code. The ruleset calls the AutomateMyConfiguration() method, which is defined in a custom Java class. In this example, the custom Java class is named MyConfigurationManagerImpl.java, which is also described in this list.

• AUTOMATE_MY_CONFIGURATION_EXT.rst

  This is a custom ruleset extension point that associates the AUTOMATE_MY_CONFIGURATION custom ruleset to the UIM-provided BaseConfigurationManager_automateConfiguration extension point and configures the custom ruleset to run instead of the method that the extension point defines (the BaseConfigurationManager.automateConfiguration() method).

• MAP_MY_SERVICE_ACTION.ruleset

  If you defined custom service actions, this is a custom ruleset that evaluates custom service actions specified in the request and maps them to an entity action that is recognizable to UIM. In this example, there are five custom service actions, so this ruleset evaluates the five custom service actions and maps each one to the appropriate entity action. The entity actions are defined in the Service Fulfillment Web Service code, as described in "Customizing ProcessInteraction".

  Table 2-1 provides an example of mapping custom service actions to UIM entity actions.

  Table 2-1 Example Mapping of Custom Service Actions

  Custom Service Action	UIM Entity Action
  createMyService	create
  updateMyService	change
  changeAddToMyService	change
  disconnectMyService	disconnect
  suspendMyService	suspend

  
  

• MAP_MY_SERVICE_ACTION_EXT.rst

  This is a custom ruleset extension point that associates the MAP_MY_SERVICE_ACTION custom ruleset to the UIM-provided BusinessInteractionManager_getEntityAction extension point and configures the custom ruleset to run instead of the method that the extension point defines (BusinessInteractionManager.getEntityAction() method).

• MyConfigurationManagerImpl.java

  This is custom Java code that contains a series of if else statements that evaluate the mapped entity action. For each entity action, the code calls another method within the same class. Within each of these methods, the finite set of parameters that are valid for the specific service action that was mapped to the entity action is evaluated.

  From there, the custom code calls various API methods to perform the work required to realize any service in UIM.

• Any additional custom rulesets and ruleset extension points

  When the custom code calls API methods, the existing API functionality may need to be extended to realize a service in UIM. So, your project may also have to define any needed rulesets that can be configured to run before or after the API methods that the custom code calls.

Request Search Options

In getConfigurationRequest, you specify a search option that indicates the type of configuration to retrieve. The search options, which are defined in the ConfigurationMessages.xsd schema file, are listed and described in Table 2-2.

Request Search Option Examples

Example 2-5 shows getConfigurationRequest with a search option of ServiceConfigurationSearchByConfigId in bold. The element below the search option shows the configuration ID to search for.

<con:getConfigurationRequest>
    <responseLevel>ENTITY_CONFIGURATION_EXPANDED</responseLevel>
    <con:searchOptions xsi:type="con:GetServiceConfigurationType"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <con:configSearchOption
        xsi:type="con:ServiceConfigurationSearchByConfigId">
            <con:configurationId>123456</con:configurationId>
        </con:configSearchOption>
    </con:searchOptions>
</con:getConfigurationRequest>
 

Example 2-6 shows getConfigurationRequest with a search option of ConnectivityConfigurationSearchByVersionNumber in bold. The elements below the search option show the entity ID and configuration version number to search for.

<con:getConfigurationRequest>
    <responseLevel>ENTITY_CONFIGURATION_EXPANDED</responseLevel> 
    <con:searchOptions xsi:type="con:GetConnectivityConfigurationType"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <con:configSearchOption
        xsi:type="con:ConnectivityConfigurationSearchByVersionNumber"> 
            <con:entityId>1</con:entityId> 
            <con:versionNumber>1</con:versionNumber> 
        </con:configSearchOption> 
    </con:searchOptions> 
</con:getConfigurationRequest>

Additional Request Options

In getConfigurationRequest, you can also specify the following options. If an option is not specified in the request, the operation uses the default value.

• includeTags

  • When set to true, the response includes tags on configuration items, with the tag name and description populated.

  • When set to false (the default), the response does not include tags on configuration items.

  For information about tags, see the Design Studio Help.

• includeTagsOtherInfo

  • When set to true, tag name, description, and otherInformation are populated.

  • When set to false (the default), tag name and description are populated; otherInformation is not populated.

    Note:

    The includeTagsOtherInfo option is only applicable when includeTags is true.

  For information about tags, see the Design Studio Help.

• includeNetworkTargets

  • When set to true, the response includes network targets.

  • When set to false (the default), the response does not include network targets.

  For information about network targets, see UIM Concepts.

Additional Request Options Example

Example 2-7 shows getConfigurationRequest with the additional request options.

<con:getConfigurationRequest>
    <com:header></com:header>
    <con:searchOptions
    .
    .
    . 
    </con:searchOptions>
    <con:includeTags>true</con:includeTags>
    <con:includeTagsOtherInfo>true</con:includeTagsOtherInfo>
</con:getConfigurationRequest>

ResponseLevel Element

getConfigurationRequest and updateConfigurationRequest define the <responseLevel> element. This element specifies an enumeration value, as defined by the ConfigurationResponseLevelEnum enumeration in the ConfigurationMessages.xsd schema file. (This element does not apply to getConfigurationDifferencesRequest.)

Depending on the enumeration value specified in the request, the level of information returned by the response can vary:

• ENTITY_CONFIGURATION (default option)

  Returns the entity and configuration information.

• ENTITY_CONFIGURATION_EXPANDED

  Returns the entity, configuration, and any child configurations.

Extension Points

The UIM_Home/cartridges/base/ora_uim_baseextpts cartridge provides the following specification-based extension points for customizing GetConfiguration:

• BaseConfigurationManager_populateCustomProperties.rstp, which defines the following method signature:

  public Map<String, String> 
  populateCustomProperties(ConsumableResource resource, InventoryConfigurationItem item, 
  InventoryConfigurationVersion inventoryConfigurationVersion)
  

• BaseConfigurationManager_populateCustomProperties2.rstp, which defines the following method signature:

  public Map<String, String>
  populateCustomProperties(ConfigurationReferenceEnabled entity, InventoryConfigurationItem item, 
  InventoryConfigurationVersion inventoryConfigurationVersion)
  

GetConfiguration always calls the populateCustomProperties() methods, which are empty methods that exist for customizing GetConfiguration. Within a configuration, each configuration item represents a resource, which may be assigned or referenced. The populateCustomProperties() methods define different inputs; a consumable resource entity versus a reference-enabled entity. The former method is called during the process of retrieving assigned resources, and the latter method is called during the process of retrieving referenced resources.

Customization Steps

To customize GetConfiguration:

1. Create a ruleset to retrieve any additional assigned resource data that your implementation requires.The ruleset must return a Map containing a name/value pair of the retrieved data name and corresponding data value.

2. Create a ruleset extension point to configure your ruleset to run after the populateCustomProperites() method, using the BaseConfigurationManager_populateCustomProperties.rstp extension point.

3. Create a ruleset to retrieve any additional referenced resource data that your implementation requires. The ruleset must return a Map containing a name/value pair of the retrieved data name and corresponding data value.

4. Create a ruleset extension point to configure your ruleset to run after the populateCustomProperites() method, using the BaseConfigurationManager_populateCustomProperties2.rstp extension point.

5. Configure any applicable specifications with the appropriate ruleset extension point. (The base extension points are specification-based, not global.)

6. Deploy the cartridge or cartridges containing the ruleset, ruleset extension points, and specifications.

7. Call GetConfiguration.

   GetConfiguration calls the populateCustomProperties() methods, and your rulesets run afterward, populating the customProperty element in the response. See "Customized Response" for more information.

Customized Response

Example 2-8 shows an excerpt from the Configuration.xsd file, which defines the customProperty element.

<xs:element name="customProperty" type="invprop:PropertyType" nillable="true" 
minOccurs="0" maxOccurs="unbounded">
    <xs:annotation>
        <xs:documentation>
            Custom Properties added for the entity Assignment/Reference.
        </xs:documentation>
    </xs:annotation>
</xs:element>

Example 2-9 shows an excerpt from the Property.xsd file, which defines the PropertyType structure. (The customProperty element references PropertyType in its definition.)

<xs:complexType name="PropertyType">
    <xs:annotation>
        <xs:documentation>PropertyType holds a single dynamic property as a
        name-value pair.</xs:documentation>
    </xs:annotation>
    <xs:sequence>
        <xs:element name="name" type="xs:string" />
        <xs:element name="value" type="xs:string" nillable="true" />
        <xs:element name="action" type="invent:EntityActionEnum" minOccurs="0">
            <xs:annotation>
                <xs:documentation>
                    Action holds the property Action which indicates whether the
                    property needs to be added/deleted/updated.
                    Valid values for this element are defined by EntityActionEnum.
                </xs:documentation>
            </xs:annotation>
        </xs:element>
    </xs:sequence>
</xs:complexType>

Example 2-10 shows the structure that ends up in the response when customizations are in place.

<con:customProperty>
    <invprop:name>customDataName1</invprop:name>
    <invprop:value>customDataValue1</invprop:value>
    <invprop:action><invprop:action>
</con:customProperty>
<con:customProperty>
    <invprop:name>customDataName2</invprop:name>
    <invprop:value>customDataValue2</invprop:value>
    <invprop:action><action>
</con:customProperty>
<con:customProperty>
    <invprop:name>customDataName3</invprop:name>
    <invprop:value>customDataValue3</invprop:value>
    <invprop:action><invprop:action>
</con:customProperty>

Request Search Options

In getConfigurationDifferencesRequest, you specify a search option that indicates the type of configuration versions. The search options, which are defined in the ConfigurationMessages.xsd schema file, are listed and described in Table 2-3.

All search options inherit from the abstract ConfigurationDifferencesSearchOption, and all entity-specific search options inherit from the abstract EntityConfigurationDifferencesSearchOption, as shown in Figure 2-11.

Figure 2-11 Search Options

Description of ''Figure 2-11 Search Options''

The request must specify one of the following:

• Business interaction ID

• Entity ID

• External ID for a business interaction

• External ID for a service entity

In the above list, the entity ID can be for a service, pipe (representing a pipe or channelized connectivity), logical device, logical device account, network, or place entity. However, the external ID for an entity can only be for a service entity.

Target and Source Configuration Versions

ConfigurationDifferencesEntitySearchOption, from which all search options inherit, defines the following:

• Target configuration version

• Source configuration version

The target and source configuration versions indicate the configuration versions to compare. The target configuration is the root of the comparison. Depending on what is specified in the request, the operation does the following:

• If the request specifies both the target and source configuration versions, the operation compares the two configuration versions.

• If the request specifies only a target configuration version, the operation compares the specified target configuration version to a defaulted source configuration version. In this scenario, the source configuration version defaults to the latest non-cancelled configuration version that precedes the specified target configuration version.

• If the request specifies neither, the operation compares a defaulted target configuration version to a defaulted source configuration version. In this scenario, the target configuration version defaults to the latest non-cancelled configuration version, and the source configuration version defaults to the latest non-cancelled configuration version that precedes the defaulted target configuration version.

• If the request specifies only a source configuration version (which is not recommended), the operation compares a defaulted target configuration version to the specified source configuration version. In this scenario, the target configuration defaults to the latest non-cancelled configuration version that follows the specified source configuration version, if it exists. If the operation is unable to default the target configuration version, the response returns an error.

Request Search Option Examples

Example 2-11 shows getConfigurationDifferencesRequest with a search option of BusinessInteractionConfigurationDifferencesSearchOption in bold. The elements below the search option show the specified business interaction ID to search for.

This request example also shows how you can specify an external ID for a business interaction to search for. In the example, these elements are commented out because you can only specify one or the other when using this search option.

<con:getConfigurationDifferencesRequest>
    <com:header/>
    <con:searchOptions 
    xsi:type="con:BusinessInteractionConfigurationDifferencesSearchOption"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <con:interaction xsi:type="bus:BusinessInteractionType">
            <bus:header>
                <bus:id>123456</bus:id>
                <!--
                <bus:externalIdentity xsi:type="invent:ExternalIdentityType">
                    <invent:externalObjectId>9876543</invent:externalObjectId>
                </bus:externalIdentity>
                -->
            </bus:header>
        </con:interaction>
    </con:searchOptions>
</con:getConfigurationDifferencesRequest>
 

Example 2-12 shows getConfigurationDifferencesRequest with a search option of ServiceConfigurationDifferencesSearchOption in bold. The elements below the search option show the specified service ID to search for. In this example, where the search option inherits from the EntityConfigurationDifferencesSearchOption, the request also specifies a source configuration version and a target configuration version.

<con:getConfigurationDifferencesRequest>
    <com:header></com:header>
    <con:searchOptions
    xsi:type="con:ServiceConfigurationDifferencesSearchOption" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <con:service xsi:type = "ser:ServiceCriteriaType">
            <ser:serviceId>2468</ser:serviceId>
        </con:service>
        <con:targetConfigurationCriteriaType
        xsi:type="conf:ConfigurationCriteriaType">
            <conf:configurationVersionNumber>2</conf:configurationVersion
            Number>                       
        </con:targetConfigurationCriteriaType>         
        <con:sourceConfigurationCriteriaType
        xsi:type="conf:ConfigurationCriteriaType">
            <conf:configurationVersionNumber>1</conf:configurationVersion
            Number>                       
        </con:sourceConfigurationCriteriaType>     
    </con:searchOptions>
</con:getConfigurationDifferencesRequest>

Additional Request Options

In getConfigurationDifferencesRequest, you can also specify the following options. If an option is not specified in the request, the operation uses the default value.

• includeConfigItemDifferences

  • When set to true, the response includes changes on the configuration item itself. For example, adding or removing configuration items.

  • When set to false (the default), the response includes only changes on the resources.

• includeChildConfigDifferences

  • When set to true, the response includes differences for child configurations referenced or assigned to a configuration item on a parent configuration. For example, when a resource-facing service (RFS) is assigned on a customer-facing service (CFS).

  • When set to false (the default), the response does not include these differences.

• includeActionPerformedInTargetVersion

  • When set to true, the response includes the actionPerformedInTargetVersion element within the target configuration item differences. The actionPerformedInTargetVersion element is a Boolean value in the response; when true is returned, it indicates the action taken was performed in the target version; when false is returned, it indicates the action taken was performed in the source version.

    For example, when comparing version 1 (source) and version 4 (target), where versions 2 and 3 are not cancelled, and resource A is assigned in version 1: If resource A is modified in version 3, actionPerformedInTargetVersion is set to false; but if resource A is modified in version 4 (the version to compare), actionPerformedInTargetVersion is set to true.

  • When set to false (the default), the response does not include the actionPerformedInTargetVersion element within the target configuration item differences.

• includeTarget

  • When set to true (the default), the response includes the target configuration.

  • When set to false, the response does not include the target configuration.

  Note:

  The includeTarget option takes precedence over the returnTargetWhenNoChange option. For example, if returnTarget is true and returnTargetWhenNoChange is false, and the configurations versions being compared are the same, the response includes the target configuration.

• includeSource

  • When set to true (the default), the response includes the source configuration.

  • When set to false, the response does not include the source configuration.

• returnTargetWhenNoChange

  • When set to true, and the versions being compared are the same, the response returns an action of Unchanged and populates the target configuration; the source configuration is not populated.

  • When set to false (the default), and the versions being compared are the same, the response returns an action of Unchanged and populates neither configuration (target or source).

• includeTags

  • When set to true, the response includes tags on configuration items, with the tag name and description populated.

  • When set to false (the default), the response does not include tags on configuration items.

  For information about tags, see the Design Studio Help.

• includeTagsOtherInfo

  • When set to true, tag name, description, and otherInformation are populated.

  • When set to false (the default), tag name and description are populated; otherInformation is not populated.

    Note:

    The includeTagsOtherInfo option is only applicable when includeTags is true.

  For information about tags, see the Design Studio Help.

• includeNetworkTargets

  • When set to true, the response includes network targets.

  • When set to false (the default), the response does not include network targets.

  For information about network targets, see UIM Concepts.

Additional Request Options Example

Example 2-13 shows getConfigurationRequest with the additional request options.

<con:getConfigurationDifferencesRequest>
    <com:header></com:header>
    <con:searchOptions>
    .
    .
    . 
    </con:searchOptions>
    <con:includeConfigItemDifferences>true</con:includeConfigItemDifferences>
    <con:includeChildConfigDifferences>true</con:includeChildConfigDifferences>
    <con:includeActionPerformedInTargetVersion>true</con:includeActionPerformedInTargetVersion>
    <con:includeTarget>true</con:includeTarget>
    <con:includeSource>true</con:includeSource>
    <con:returnTargetWhenNoChange>true</con:returnTargetWhenNoChange>
    <con:includeTags>true</con:includeTags>
    <con:includeTagsOtherInfo>true</con:includeTagsOtherInfo>
</con:getConfigurationDifferencesRequest>

Example 1

Figure 2-13 shows an example where the start date and end date of the child configuration are on or after the parent configuration start date.

Figure 2-13 Child Start Date Is After Parent Start Date

Description of ''Figure 2-13 Child Start Date Is After Parent Start Date''

In this example, the operation is comparing configuration versions P.2 and P.3. Configuration P is a parent to child configuration C, so the operation must determine which versions of child configuration C to compare.

The process:

1. Starts with parent configuration version P.3, which has a start date of 7/15.

2. Looks for a child configuration version with a start date that is on or after 7/15.

3. Finds child configuration version C.3, which has a start date of 8/15.

4. Proceeds to parent configuration version P.2, which has a start date of 4/15.

5. Looks for a child configuration version with a start date that is on or after 4/15.

6. Finds child configuration version C.2, which has a start date of 5/15.

The operation determines that child configuration version C.3 is compared with child configuration version C.2.

Example 2

In this example, the start dates and end dates of the child configurations are both before and after the parent's configuration start dates, as shown in Figure 2-14:

Figure 2-14 Child Start Date Before and After Parent Start Date

Description of ''Figure 2-14 Child Start Date Before and After Parent Start Date''

In this example, the operation is comparing configuration versions P.2 and P.3. Configuration P is a parent to child configuration C, so the operation must determine which versions of child configuration C to compare.

The process:

1. Starts with parent configuration version P.3, which has a start date of 7/15.

2. Looks for a child configuration version with a start date that is on or after 7/15, but does not find one.

3. Looks for a child configuration version with a start date that is before 7/15.

4. Finds child configuration version C.3, which has a start date of 6/15.

5. Proceeds to parent configuration version P.2, which has a start date of 3/15.

6. Looks for a child configuration version with a start date that is on or after 3/15.

7. Finds child configuration version C.1, which has a start date of 4/15.

The operation determines that child configuration version C.3 is compared with child configuration version C.1.

Example 3

In this example, the same child configuration version is applicable two versions of the parent configuration, as shown in Figure 2-15:

Figure 2-15 Same Child Configuration

Description of ''Figure 2-15 Same Child Configuration''

In this example, the operation is comparing configuration versions P.2 and P.3. Configuration P is a parent to child configuration C, so the operation must determine which versions of child configuration C to compare.

The process:

1. Starts with parent configuration version P.3, which has a start date of 7/15.

2. Looks for a child configuration version with a start date that is on or after 7/15, but does not find one.

3. Looks for a child configuration version with a start date that is before 7/15.

4. Finds child configuration version C.2, which has a start date of 3/15.

5. Proceeds to parent configuration version P.2, which has a start date of 4/15.

6. Looks for a child configuration version with a start date that is on or after 4/15, but does not find one.

7. Looks for a child configuration version with a start date that is before 4/15.

8. Finds child configuration version C.2, which has a start date of 3/15.

The operation determines that child configuration version C.2 is compared with the same child configuration version. In this scenario, the response returns an action of Unchanged and may populate the target configuration, depending on what is specified in the request for the returnTargetWhenNoChange option. See "returnTargetWhenNoChange" for more information.

Overriding the Process Logic that Determines Child Configurations

The process logic that determines the child configuration versions to compare resides in the BaseConfigurationManager.getEffectiveChildConfiguration() method, and Oracle provides a base extension point that defines this method.

You can override the logic by writing a custom ruleset that contains custom code that retrieves the child configuration versions based on your business requirements. You can then configure the custom ruleset to run at the provided base extension point, resulting in the custom ruleset running instead of the BaseConfigurationManager.getEffectiveChildConfiguration() method. See UIM Developer's Guide for more information about rulesets and extension points.

You can find the BaseConfigurationManager_getEffectiveChildConfiguration base extension point in the UIM_Home/cartridges/base/ora_uim_baseextpts.jar file.