Skip Headers
Oracle® Communications Order and Service Management Developer's Guide
Release 7.2.2

E35419-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 Using Design Studio

This chapter provides information on Oracle Communications Design Studio and the plug-ins specific to Oracle Communications Order and Service Management (OSM) that enable you to configure and customize OSM.

About Implementing OSM

Before you can use OSM to fulfill orders, you need to use Design Studio to model how orders are fulfilled. For example, if you sell a DSL service, you model your DSL order to include the data necessary to activate the DSL service on the network.

You can approach the creation of process-based orders by modeling the process flow first or by defining data first and analyzing the process flow needed to support the data model. You can also use a hybrid approach, defining data as needed while modeling your process flow.

When you use Design Studio, you create order specifications for the types of orders your business uses. You also create specifications for each of the elements in an order model; for example, order item specifications, and order component specifications.

You also use Design Studio to define how OSM fulfills orders. For example, you design the way orders are recognized, how they are decomposed, the processes and data required to complete them, and how to manage fallout.

You create projects to contain the order specifications that you develop. When a project is complete, you use Design Studio to build a cartridge that is deployed into OSM.

You also define the following entities in Design Studio to further specify particular aspects of order management.

Design Studio is based on Eclipse, an industry-standard, open-source development environment.

See the Design Studio Help for more information.

Installing Design Studio

Design Studio is the primary application for modeling orders, orchestration details, processes, and creating automated tasks. For directions on how to install Design Studio, which includes the installation of Eclipse, see Design Studio Installation Guide. For version compatibility information for Design Studio and plug-ins, see OSM Installation Guide.

Installing the OSM Plug-ins

For directions on how to install the OSM plug-ins, see Design Studio Installation Guide. The section on installing Design Studio features into Eclipse describes how to install all available Oracle Communications plug-ins.

For OSM, you need to install the following plug-ins:

  • Design Studio Platform: This is the core plug-in required for working with all the Oracle Communications applications that use Design Studio.

  • Design Studio for Order and Service Management: This Design Studio feature enables you to configure entities used by OSM.

If you plan to integrate OSM with Oracle Communications ASAP or with Oracle Communications IP Service Activator, or if you plan to use the orchestration capabilities of OSM, you need to install the following plug-ins:

  • Design Studio for Order and Service Management Integration: This Design Studio feature includes the Design Studio activation task feature for integrating with ASAP and with IP Service Activator. To model activation tasks, you must also install the Design Studio for Activation feature.

  • Design Studio for Order and Service Management Orchestration: This Design Studio feature enables you to configure orchestration-related entities for OSM.

Configuring Design Studio

Before developing with Design Studio, configure your Oracle WebLogic Server, Java, and OSM SDK home directories:

  1. From the Window menu, select Preferences.

  2. In the left pane tree view, expand Oracle Design Studio and select Order and Service Management Preferences.

  3. In the Deploy Properties section:

    1. Set the WebLogic Home field: Click Browse and navigate to your WebLogic Server installation directory; for example, C:\wls_1035\wlserver_10.3.

    2. Set the Java SDK Home field: Click Browse and navigate to your Java installation directory; for example, C:\jdk160_11.

    3. Set the OSM Home field: Click Browse and navigate to your OSM SDK installation directory; for example, C:\OSM_home\SDK.

  4. In the Delete Orphaned Task References With Activity section, select the Prompt radio button.

  5. Click OK.

About Design Studio Perspectives and Views

Perspectives define your Workbench layout and provide different functionality for working with different types of resources. Several perspectives are available within Design Studio. The Java perspective, Design perspective, and Environment perspective are commonly used when customizing OSM.

Within a given perspective, views further define your Workbench layout and provide different presentations of resources. Several views are available within Design Studio, and the available views are dependent upon the perspective.

For example, within the Java perspective, commonly used views include:

Within the Design perspective, commonly used views include:

Within the Environment perspective, commonly used views include:

For instructions on how to open perspectives and views in Design Studio, see the Design Studio Help.

About Cartridges

Cartridges contain OSM customizations, such as order templates, order processes, automated tasks, and custom automation plug-ins. Use Design Studio to develop cartridges that model your business logic.

When customizing OSM, you can create one or more cartridges, depending on how you choose to organize the customizations. For example, you may create a cartridge that contains only order templates, another that contains only processes, another that contains only automations, and so on. Or, you may create one cartridge per business area where all order templates, processes, and automations for one business area are defined in one cartridge, while all order templates, processes, and automations for another business area are defined in a different cartridge.

Everything you create in Design Studio (order templates, processes, automations, and so on) resides in a cartridge. After the initial build of the cartridge project, a corresponding portal archive (PAR) file is created. A PAR file is a standard ZIP file with a .par extension that contains Java classes, Web resources, and other files required to run the application. The name you choose for the cartridge becomes the name of the PAR file. The PAR file is saved to the cartridgeName/cartridgeBin directory, as seen from the Java perspective Package Explorer view. Everything you create in Design Studio that resides in a cartridge is saved to the corresponding PAR file.

There are two types of cartridges in OSM: component cartridges and composite cartridges. Most cartridges (and all cartridges in versions of OSM prior to 7.2) are component cartridges. An OSM composite cartridge is a type of cartridge that references other cartridges, called component cartridges, within a single logical scope. You use component cartridges and composite cartridges together to develop, deploy, and maintain OSM solutions. A composite cartridge is used to assemble an OSM solution from a collection of component cartridges. When you deploy the composite cartridge into the run-time environment, all of the component cartridges that are referenced in the composite cartridge are deployed as a solution in a single action.

Composite cartridge projects may contain any number of component cartridges, but not other composite cartridges. You cannot create entities directly in a composite cartridge project; rather, you create the entities in the component cartridges that are referenced in the composite cartridge.

You can configure how orders are fulfilled by deploying cartridges in different ways. For example:

Configuration Guidelines: Steps to Create an Orchestration Cartridge

The following is an outline of creating a cartridge using Design Studio.

  • Create a new OSM project in Design Studio.

  • Create new role that will own the execution of the activities.

    • Associate the role to manual and automated tasks.

    • Define a query task for the role, which will be used later for defining which data is available when a user performs a query.

  • Create a new ControlData section in the data schema and populate it.

    The OracleComms_OSM_CommonDataDictionary model project contains predefined base data elements for control data. It is recommended that you use the data schema of this model project to add the ControlData data element in the data schema.

    If you define ControlData in the data schema manually:

    • Set Cardinality: it should be able to accept multiple order items.

    • The componentKey element in ControlData is 100 chars long. Others do not have an explicit length.

    • Display names should be the same as real names.

  • Populate the main data schema. This will hold all the individual data elements and data structures that contain the order data.

  • Configure recognition rules.

    • Set name space upon creation.

    • Fill in recognition and transformation tabs.

  • Define order item specs.

    • Define data instance to support product spec mapping.

    Create or import at least a skeleton order item specification that contains the base ControlData/OrderItem structure. The OracleComms_OSM_CommonDataDictionary model project contains this base structure.

  • Define manual tasks and sub-processes that will be mapped in order component specs.

  • Define order component specifications.

  • Define fulfillment modes (which must be unique in the workspace).

  • Create orchestration stages.

  • Create a three-stage orchestration sequence with the following stages: Function, followed by system, followed by processing granularity.

  • Create an orchestration process.

  • Create product specifications.

  • Create product classes.

  • Define decomposition rules.

    • Use two types of decomposition rules: System decomposition rules to map the functions to a system and processing granularity decomposition rules to map a function-system combination to the "level of execution," for example order or order item level.

    • Even in cases where there is only one system of a given fulfillment type, use dummy decomposition rules (a 1:1 mapping) for ease of maintenance if more systems are added later.

  • Create the creation task and add the needed data.

  • Create an order life-cycle policy.

  • Complete the order.

Creating a Cartridge

For instructions on how to create a cartridge in Design Studio, see the Design Studio Help.

When you create and build a cartridge, OSM gives the cartridge and resultant PAR file the same name. The name is based on what was entered in the Project name field when creating the cartridge.

Cartridge Explorer View of a Cartridge

Figure 3-1 shows an example of a cartridge, named myCartridge, as it appears in the Design perspective Cartridge view (left side). The corresponding Order and Service Management Cartridge editor is also shown (right side).

Figure 3-1 Cartridge View of a Cartridge

Shows an example of a cartridge in the Design perspective Cartridge view. Also shows the corresponding Order and Service Management Cartridge editor.

Expand the cartridge in the Cartridge explorer pane (on the left in Figure 3-1) to see the contents created with each cartridge. For a component cartridge, this includes a default order based on the name of the cartridge. When you initially create a new OSM component cartridge, errors are always present because the default order requires you to define:

  • A creation task

  • A default process

  • A role that grants creation permissions

  • An order life-cycle policy

  • An order template

  • Order permissions

A composite cartridge does not require these entities, so there are no errors when it is initially created. For a component cartridge, after these entities are defined for the order, the errors are resolved, but the graphic will still show the presence of an error by placing a small red "x" box on the lower left corner of the icons in the Cartridge explorer pane. This is because the graphic shows what is present when the cartridge is created. When the errors are resolved, the pane reflects the additional entities of a process and a life-cycle policy that are not part of cartridge creation.

Note:

Steps to resolve these errors are provided in "Automation: Start to Finish".

Package Explorer View of a Cartridge

Switching to the Java perspective Package Explorer view and expanding the cartridge displays the file types of the contents created with each cartridge.

Figure 3-2 shows an example of a cartridge, named myCartridge, as it appears in the Java perspective Package Explorer view. The corresponding Order and Service Management Cartridge editor is also shown.

Figure 3-2 Package Explorer View of a Cartridge

Shows an example of a cartridge in the Java perspective Package Explorer view. Also shows the corresponding Order and Service Management Cartridge editor.

In the example, myCartridge was entered in the Project name field when creating the cartridge. As a result, the Java perspective Package Explorer view shows:

  • myCartridge: The Design Studio Order and Service Management Cartridge project.

  • myCartridge/dataDictionary/myCartridge.xsd: The schema file used internally by Design Studio.

  • myCartridge/model/myCartridgeOrder.order: The Order editor.

  • myCartridge/myCartridge.osmCartridge: The Order and Service Management Cartridge editor shown on the right side of Figure 3-2.

After creating the cartridge, an immediate build of the project creates additional directories and files in the cartridge, as shown in Figure 3-3. The directories include, among others:

  • cartridgeBin

    This directory contains the myCartridge.par file, which contains the Design Studio entity files and is deployed to the OSM server.

  • customAutomation

    This directory is created with the cartridge, but the automationMap.xsd and databasePlugin.xsd files are pulled into the cartridge with the build.

Figure 3-3 Package Explorer View of a Cartridge After a Build

Shows additional directories and files created in a cartridge after an immediate build of the project.

Note:

If working with automation plug-ins, the directories and files listed below are of importance, and are further explored in "Using Automation":
  • src directory

  • src/automationBuild.xml

  • Referenced Libraries/automation_plugins.jar

  • cartridgeBin/cartridgeName.par

  • customAutomation/automationMap.xsd

  • customAutomation/databasePlugin.xsd

  • resources directory

Adding Content to a Cartridge

For instructions on how to add content to a cartridge in Design Studio, see the Design Studio Help.

To see the OSM-specific options that are available to add to a cartridge:

  • From the Studio menu, select New, then select Order and Service Management.

For example, some of options may be Automated Task, Custom Automation Plug-in, Manual Task, Order, and Process. When content is added to a cartridge, Design Studio automatically groups the content based on these options.

For example, when an Automated Task is created, it is grouped under Automated Tasks. When a Manual Task is created, it is grouped under Manual Tasks. These groupings are not physical directories, and they display only in the Cartridge view of the Design perspective. Figure 3-4 illustrates this concept, showing four Design Studio entity instances created from two different Design Studio entity types.

Figure 3-4 Cartridge Content

Shows four Design Studio entity instances created from two different Design Studio entity types.

Handling Multiple Cartridge Versions

Some additional configuration is necessary to deploy multiple versions of a cartridge to an OSM environment. All of the following considerations should be taken into account:

  • Default field in Cartridge Editor Properties tab

    Only one version of a cartridge should be set as the default version of the cartridge. For example, if you have versions 1.0.0 and 2.0.0 of an OSM cartridge deployed, only one of them should have the Default box in the editor checked.

    See the Design Studio Help for the cartridge editor Properties tab for more information.

  • Cartridge versioning using XML Catalog

    XML Catalog should be used to allow multiple cartridge versions to refer to their own set of resources using the cartridge model variable CARTRIDGE_VERSION.

    If a rewriteURI entry in the XML Catalog contains a version-specific portion in the URI such as “1.0.0” in the following:

    <rewriteURI uriStartString="http://company.com/" rewritePrefix="osmmodel:///MyCartridge-Resources/1.0.0/resources"/>
    

    the version-specific portion of the rewriteURI must be updated to point to the correct cartridge version.

    See "Using XML Catalogs to Support Cartridge Versioning" for more information.

  • Automation – External Event Receiver

    When there are multiple versions of automation external event receivers listening to the same JMS Source, this can pose a problem because the automation external event receivers may consume the wrong version of the message. To configure the correct version of the message to be consumed, a version identifier should be encoded in either the JMS message properties or the XML message body. This will allow the automation to consume the right version of the message through either the Message Property Selector or XML Message Body Selector option in the External Event Receiver tab of the automation property.

    See the Design Studio Help for the External Event Receiver sub-tab of the properties view in the automated task editor Automation tab.

  • Order Recognition Rule

    When there are multiple versions of a cartridge with orchestration entities, order recognition rules should be modeled to recognize a specific version of the order instead of the default version. To recognize a specific version of the order, the Target Order Version of the order recognition rule should be set to the version of the cartridge where the specific version of the order resides.

    Note:

    When an order recognition rule is used in a composite cartridge and there are multiple versions of the composite cartridge, the Target Order Version of the order recognition rule should be set to the version of the composite cartridge that contains the target order as part of the solution.

    For example, we might have version 1.0.0 of the OsmCentralOMExample-Solution composite cartridge with the following dependent cartridges:

    • OsmCentralOMExample-Orchestration version 1.2.0 – OsmCentralOMExampleOrder is defined here

    • OsmCentralOMExample-ProductClass version 2.0.0

    • OsmCentralOMExample-ProductSpec version 2.0.0

    • OsmCentralOMExample-Topology version 1.1.0

    The target order version of the order recognition rule should be set to 1.0.0, because the order recognition rule is used as part of a composite cartridge and the version of the composite cartridge that contains the order is 1.0.0.

Packaging and Building a Cartridge

Use Design Studio to package a cartridge by specifying entities to include in the cartridge. By default, all entities created within the cartridge are included unless otherwise specified on the Order and Service Management Cartridge editor Packaging tab.

To build cartridges:

For instructions on how to package and build a cartridge, see the Design Studio Help.

Modifying the Build

If you need to modify the build performed by Eclipse, you can modify the build files that are provided with the creation of each cartridge. Common modifications include adding logic to the build file for the generation of Java code and the creation of JAR files. The build files are:

  • CartridgeName/src/build.xml

  • CartridgeName/src/automationBuild.xml

As part of the build process, the CartridgeName/lib directory is copied into the automation staging area, resulting in the lib directory being included in the automation.ear file. The CartridgeName/src/build.xml file can be customized to add files to the lib directory before this happens. For example, you may want to get a JAR file from another project as part of the build or do some other custom staging activity. Nothing in the lib directory goes on the classpath automatically. You can do this manually as well.

Deploying a Cartridge

Design Studio allows you to deploy a cartridge to an OSM environment. However, you must first specify the OSM environment by creating a Design Studio environment entity. The Design Studio environment entity defines the connection information for the server hosting the OSM environment to which you plan to deploy your cartridge. For instructions on how to define an environment in Design Studio, or instructions on how to do any of the steps described in this section, see the Design Studio Help.

Note:

You do not need to define the environment every time you deploy a cartridge; the environment is only be defined once per OSM environment.

Note:

If you are deploying to a clustered environment, specify the proxy server when defining the Environment Design Studio entity.

To deploy a cartridge:

  1. Ensure the OSM environment to which you are deploying is running.

  2. Ensure the Environment Design Studio entity is defined for the OSM environment to which you are deploying.

  3. From Design Studio, deploy the cartridge to the OSM server, which can be done one of two ways:

    1. From the Studio menu, select Deploy.

      A menu is displayed, listing the cartridges within your workspace that are available for deployment.

    2. Select the cartridge to deploy.

      A menu is displayed, listing the configured OSM environments available to which you can deploy a cartridge.

    3. Select the environment to which the cartridge is to be deployed.

    OR

    1. Open the Environment perspective Cartridge Management view.

      A list of the cartridges within your workspace that are available for deployment is displayed.

    2. Select a cartridge to deploy.

    3. Click Deploy.

Note:

You can also undeploy previously deployed cartridges from the Environment perspective Cartridge Management view.

Cleaning and Rebuilding Cartridges Prior to Deployment

Cleaning and rebuilding a cartridge is not included as a deployment step because it is not required for a successful deployment. However, Oracle recommends that you periodically clean and rebuild a cartridge prior to deployment because multiple people can work in the same cartridge; cleaning and rebuilding the cartridge picks up these changes, ensuring that the cartridge is in its current state.

Optimizing Cartridge Deployment

During the development process, you can save time by redeploying your changes only, rather than redeploying the entire application. For more information about this option, see the Design Studio Platform Help.

Deploying Multiple Cartridges

You can simultaneously deploy multiple cartridges when deploying from the Environment perspective Cartridge Management view. When you select multiple cartridges for deployment, the system deploys the cartridges individually based on any existing cartridge dependencies. The system prevents you from deploying cartridges independently of those cartridges upon which they depend. See "Deploying Cartridges with Dependencies".

Deploying Cartridges with Dependencies

A cartridge can be dependent upon information defined in another cartridge. When dependencies exist between cartridges, the build of the cartridge with the dependency extracts the dependent information from the built cartridge upon which it is dependent and copies it to the cartridge being built. As a result, the cartridges can be deployed independently from each other.

For example, CartridgeA is created and defines phoneNumber as a data element in a data schema. CartridgeB is then created, and phoneNumber is added to a CartridgeB order template. This causes CartridgeB to be dependent upon CartridgeA. CartridgeA is built first. When CartridgeB is built, the phoneNumber data element is extracted from CartridgeA and copied to cartridgeB. As a result, cartridgeB can be deployed even if CartridgeA is not deployed.

Caution:

Cartridges should not be circularly dependent upon each other (CartridgeA is dependent upon CartridgeB and CartridgeB is dependent upon CartridgeA). If you define cartridges with a circular dependency, the cartridge build will fail, with an error like, "CartridgeA Cartridge Model Dependency Error – Cyclic dependency exists: CartridgeA <- CartridgeB." If there is a composite cartridge that refers to cartridgeX or cartridgeY, the composite cartridge build will also fail, as a result of the component cartridge builds failing.

Building and Deploying Composite Cartridges

When you build and package a composite cartridge, it is packaged as a single PAR file which contains:

  • All non-orchestration entities aggregated and packaged into the composite cartridge

  • A PAR file for each component cartridge referenced in the composite cartridge

When a composite cartridge is deployed, it includes all of the OSM non-orchestration entities and all component cartridges referenced in the composite cartridge, if they are either changed or not currently deployed.

Setting Cartridge Dependencies

Projects have dependencies on other projects when entities in one project reference entities in a different project. If you configure a cartridge to reference content in other cartridges without declaring project dependencies, Design Studio creates a warning. For information about how to set cartridge dependencies, see the Design Studio Platform Help.

Post-Deployment Effect on Numeric Data

When defining a data element in Design Studio, you have the option of defining numeric data as type int, double, float, or decimal. OSM does not directly support these data types. Rather, the OSM Data Dictionary defines the data type numeric. When a cartridge containing the data types int, double, float, or decimal is deployed to the OSM server, the data types are converted to the OSM Data Dictionary type numeric.

Post-Deployment Changes to Cartridge

You can make changes to a cartridge after the cartridge has been deployed to the OSM server by making changes to the original cartridge in Design Studio and then redeploying the cartridge. Before doing this, you should back up the original cartridge, because exporting a deployed Design Studio cartridge back out of OSM into Design Studio is not supported.

Metadata Errors

Metadata errors can cause order processing failures and can occur in any cartridge with orchestration model entities. Metadata is the information used to represent OSM modeled entities such as order templates, order components, order items, tasks, decomposition rules and so on. If there are no metadata errors, the cartridge models deployed are valid.

Metadata errors occur when OSM references an entity that is missing or the modeling for an entity is incorrect (for example, a data type for an entity is incorrectly entered).

OSM detects and logs metadata errors during the following procedures:

  • Deploying a cartridge to a server

  • Restarting an OSM server

  • Refreshing OSM metadata with the OSM Administrator application or with an Ant refresh

These actions reload OSM metadata, and errors are detected while running validation constraints against certain orchestration model entities. Table 3-1 lists the orchestration entities that are currently validated.

Table 3-1 Orchestration Entities That Are Currently Validated

Entity Type Schema Constraint Description

OrchestrationStageType

Verifies that the value for the element dependsOnStage is a valid stage. dependsOnStage is empty if the stage is independent. A stage is valid if it is defined in the orchestrationSequence of orchestrationModel.

OrderComponentSpecRef

Verifies that this reference is pointing to a valid OrderComponentSpec. OrderComponentSpec is valid if it is defined in orchestrationModel.

OrchestrationConditionRef

Verifies that this reference is pointing to a valid orchestration condition. An orchestration is valid if it is defined in orderItemSpec of orchestrationModel.

DurationType

Verifies that a valid duration value is specified.

ProductSpecRef

Verifies that this reference is pointing to a valid ProductSpec. ProductSpec is valid if it is defined in orchestrationModel.

OrderItemSpecRef

Verifies that this reference is pointing to a valid OrderItemSpec. OrderItemSpec is valid if it is defined in orchestrationModel.


After rebuilding or deploying a cartridge, check for metadata errors. Search for the string Metadata Errors in the Console view of the Cartridge Management editor in Design Studio. If you are not using Design Studio to deploy cartridges, look in the Oracle WebLogic Server logs for the same string.

Metadata errors appear together in a numbered list. For example:

Metadata Modeling Errors**************************

1) Metadata error Severity:ERROR Description:Invalid 
ProductSpec[name=NonService.Offer,
namespace:CommunicationsSalesOrderFulfillmentPIP]
Cartridge Name:TypicalSalesOrderFulfillment Version:1.0.0
EntityName:NonService.Offer EntityType:ProductSpecRef

where

  • Severity can be an ERROR, WARNING or CRITICAL.

  • Description describes the failure and provides the entity type, name and name space.

  • Cartridge Name is the name of the Cartridge that is reporting the problem.

  • Version is the cartridge version.

  • EntityName and EntityType are the name and type of the entity reporting the metadata error and its name space. In some cases, the modeled entity within the cartridge is invalid. In other cases, the modeled entity is referring to another entity which is missing or invalid.

If you find metadata errors, it most likely means that OSM is calling on an entity that is missing, has the wrong name, or has a value that is incompatible for the entity type.

To fix the problem, clean and rebuild your cartridges, and make sure all related cartridges are deployed. If you still have metadata errors, it may mean that you have errors in your data. In this case you will have to use Design Studio to re-validate your model. See "Cleaning and Rebuilding Cartridges Prior to Deployment".

Automating the Cartridge Build and Deployment

Automating the cartridge build and deployment is accomplished by creating a process that builds and deploys a cartridge outside of the Design Studio environment, and then scheduling that process to run using a batch file. You can automate the cartridge build and deployment for development, test, and production environments.

For more information, see the discussion of working with automated builds in Design Studio System Administrator's Guide.

Maintaining Cartridges Between Releases and Patches

Cartridges can be maintained between releases of OSM. If you have cartridges built in a prior release, you must clean and rebuild the cartridge in the new version of Design Studio before it can be deployed to the new version of OSM.

For example, OSM 7.0 is released with Design Studio 3.0. You build several cartridges in Design Studio 3.0 that you deploy to your OSM 7.0 environment. Later, you upgrade to OSM 7.n, which is released with Design Studio 3.n. The cartridges you created in Design Studio 3.0 can be imported into Design Studio 3.n, cleaned, rebuilt, and deployed to your OSM 7.n environment.

Cartridges can be maintained between patches of OSM by cleaning and rebuilding the cartridge in the current version of Design Studio, which would not change with a patch (this would only change with a new release of OSM). Not every patch requires this maintenance; it depends on whether the changes in the patch affect cartridge content.

Modeling Order Template Structures for Orchestration Plan Generation

Orchestration plan generation requires a specific order template structure which you must model at design time.

ControlData
   OrderItem
   Functions
      OrderComponentName
         componentKey
         calculatedStartDate
         duration
         OrderItem
            orderItemRef

ControlData/OrderItem

This is a multi-instance node that OSM populates with a set of order items generated off the in-bound message. The children of this structure must exactly match the set of order item properties defined on the Order Item specification editor in Design Studio.

The OracleComms_OSM_CommonDataDictionary model project contains predefined base data elements for control data. It is recommended that you use the data schema of this model project to add the ControlData/OrderItem data element to the order item specification Order Template tab.

See the Design Studio Help for instructions on modeling the ControlData/OrderItem structure.

ControlData/Functions/OrderComponentName

This is a multi-instance node that OSM populates with the set of order components generated by executing the decomposition rules through an orchestration sequence. OrderComponentName must be defined for each order component included in a product specification's orchestration plan. This section of the ControlData represents all of the order components in the orchestration plan. If you use the OracleComms_OSM_CommonDataDictionary model project, Design Studio automatically generates data (OrderComponentName) and adds it to the ControlData/Functions structure for each order component that is associated to the product specification that is part of the orchestration plan.

Each order component is assigned a unique key, which is stored in componentKey. OSM generates a key by concatenating the names of the order components traversed through the orchestration stages. An example componentKey name would be FulfillBilling.MobileBillingSystem.WholeOrderGranularity. The Order Component specification editor's Component ID tab can be used to customize an order component's name. The component ID can be used to implement processing granularity, as an example. In BundleGranularity, a component ID string would be generated for each order item based on the bundle that it belongs to. OSM then groups order items by component ID into order components.

OSM populates the calculatedStartDate (dateTime type) and duration (string type) nodes for each ControlData/Function. With calculatedStartDate and duration per Function, both central order management and service order management solutions can use these values as the requested delivery date for the order line in a downstream system. based on the modeling done in the Order Component Specification entity, the date does affect the runtime behavior of the order component. If there is a Duration Value associated with a dependency, it is used in the order component start date calculation since this value is relative value to the orchestration dependency.

OSM populates the multi-instance orderItem node with the set of order items that have been decomposed into this order component. The order items are accessed through orderItemRef, which is a reference node to ControlData/OrderItem. A reference node is used to point to the actual storage location of the order item so that updates to the order item data are reflected in all order components the order item is referenced from.

Modeling Order Template Structures for Fulfillment States

Fulfillment state processing requires specific structures and data elements inside the order template. The specific locations of the data can be changed using XML catalog: the default locations are presented here. See "About XML Catalogs" for more information about using XML catalogs in OSM. See "Sample XQuery for Changing Default Data Locations" for more information about changing the default data locations.

External Fulfillment States

External fulfillment state information is populated for order components. Write the automation code so that it populates the information in the correct place.

The default location for external fulfillment state information is ControlData/OrderItem/OrderComponentName/ExternalFulfillmentState.

Order Fulfillment State

OSM populates the order fulfillment state based on the configuration in the order fulfillment state composition rule set. For more information about order fulfillment state composition, see OSM Concepts.

The default location for OSM to populate the order fulfillment state is ControlData/OrderFulfillmentState. The Data Dictionary contains a root-level OrderFulfillmentState element. For cartridges created in a pre-7.2 version of OSM, drag the root-level OrderFulfillmentState element into the ControlData node on the order. For new cartridges, the element will get added automatically to the order template as a child of ControlData.

Order Item Fulfillment State

OSM populates the order item fulfillment state based on the configuration in the order item fulfillment state composition rule set. For more information about order item fulfillment state composition, see OSM Concepts.

The default location for OSM to populate the order item fulfillment state is ControlData/OrderItem/OrderItemFulfillmentState. The Data Dictionary contains a root-level OrderItemFulfillmentState element. For order items in cartridges created in a pre-7.2 version of OSM, drag the root-level OrderItemFulfillmentState element into the ControlData/OrderItem node on the order. For new cartridges and order items, the element will get added automatically to the order template as a child of ControlData/OrderItem.

Point of No Return

If points of no return have been configured using fulfillment states, OSM populates the point of no return when processing the order item fulfillment state composition rules. For more information about points of no return, see OSM Concepts.

The default location for OSM to populate the point of no return value is ControlData/OrderItem/PointOfNoReturn.

Fulfillment State and Point of No Return Initial Values

You can set initial values for order item fulfillment states and points of no return, so that these values will appear on the order before any processing takes place. See "Sample XQuery for Changing Default Data Locations" for more information about setting these values.

Sample XQuery for Changing Default Data Locations

To change the default locations and set initial values for point of no return and order item fulfillment state, include an XQuery file in the XML catalog. To use the defaults, do not provide a file.

To include your custom XQuery file in the cartridge, include a line similar to the following in the XML catalog file for your cartridge:

<rewriteURI uriStartString="cp:oracle/communications/ordermanagement/execution" rewritePrefix="osmmodel:///CartridgeName/CartridgeVersion/resources/Directory"/>

For more information about using XML catalogs, see "About XML Catalogs".

If you choose to configure a custom file, you should include all of the functions, even those for defaults you are not changing. This will clarify the configuration and assist in maintenance activities. The purpose of each function is indicated in comments in the file. For all values that specify order template locations (for example /OrderLifeCycleManagement), begin the value with a forward slash, as shown below.

xquery version "1.0";
module namespace fulfillmentstatemodule = "http://xmlns.oracle.com/communications/ordermanagement/fulfillmentstatemodule";

declare namespace saxon="http://saxon.sf.net/";
declare namespace xsl="http://www.w3.org/1999/XSL/Transform"
declare namespace oms = "urn:com:metasolv:oms:xmlapi:1";

(: Returns the composite fulfillment state path for an order. :)
declare function fulfillmentstatemodule:getOrderCompositeFulfillmentStatePath ($orderMnemonic as xs:string) as xs:string {
    "/ControlData/OrderFulfillmentState" };

(: Returns the composite fulfillment state path for an order item. :)
declare function fulfillmentstatemodule:getOrderItemCompositeFulfillmentStatePath ($orderMnemonic as xs:string) as xs:string {
    "/ControlData/OrderItem/OrderItemFulfillmentState" };

(: Returns the default order item external fulfillment state path. :)
declare function fulfillmentstatemodule:getOrderItemExternalFulfillmentStatePath ($orderMnemonic as xs:string) as xs:string {
    "ExternalFulfillmentState" };

(: Returns the default type of the order item external fulfillment state path. 
   Valid values are RELATIVE_PATH and ABSOLUTE_PATH. :)
declare function fulfillmentstatemodule:getOrderItemExternalFulfillmentStatePathType ($orderMnemonic as xs:string) as xs:string {
    "RELATIVE_PATH" };

(: Returns the point of no return path for an order item. :)
declare function fulfillmentstatemodule:getOrderItemPoNRPath ($orderMnemonic as xs:string) as xs:string {
    "/ControlData/OrderItem/PointOfNoReturn" };

(: Returns the name of the initial fulfillment state. :)
declare function fulfillmentstatemodule:getOrderInitialFulfillmentStateName ($orderMnemonic as xs:string) as xs:string {
    "" };

(: Returns the namespace of the initial fulfillment state. :)
declare function fulfillmentstatemodule:getOrderInitialFulfillmentStateNamespace ($orderMnemonic as xs:string) as xs:string {
    "" };

(: Returns the initial point of no return value of an fulfillment state. :)
declare function fulfillmentstatemodule:getOrderItemInitialPoNR($orderMnemonic as xs:string) as xs:string {
    "" };

declare function fulfillmentstatemodule:getExternalFulfillmentStates(
    $orderData as element()) as element()?
{
    let $orderMnemonic := 
        if (fn:exists($orderData/OrderType)) 
        then $orderData/OrderType/text() 
        else ""  
    let $orderItems := $orderData/_root/ControlData/OrderItem
    where (fn:exists($orderItems))
    return
        <oms:ExternalFulfillmentStates>
        {
            for $orderItem in $orderItems
            let $orderItemIndex := $orderItem/@index
            let $components := $orderData/_root/ControlData/Functions/*[orderItem/orderItemRef/@referencedIndex=$orderItemIndex]
            let $externalFulfillmentStatePath := fulfillmentstatemodule:getOrderItemExternalFulfillmentStatePath($orderMnemonic)
            let $externalFulfillmentStatePathExistsCheck := fn:concat($externalFulfillmentStatePath, "[text()!='']")
            let $externalFulfillmentStateExists := fn:exists($components/orderItem[orderItemRef/@referencedIndex=$orderItemIndex]/saxon:evaluate($externalFulfillmentStatePathExistsCheck))
            where (fn:exists($components) and $externalFulfillmentStateExists=fn:true())
            return
                <oms:OrderItemExternalFulfillmentState index="{$orderItemIndex}">
                {
                    for $component in $components
                    let $componentKey := fn:normalize-space($component/componentKey/text())
                    let $componentId := $component/@index
                    let $externalFulfillmentStateValuePath := fn:concat($externalFulfillmentStatePath, "[last()]/text()")
                    let $externalFulfillmentState := fn:normalize-space($component/orderItem[orderItemRef/@referencedIndex=$orderItemIndex]/saxon:evaluate($externalFulfillmentStateValuePath))
                    where (fn:exists($externalFulfillmentState) and $externalFulfillmentState != "")                    
                    return
                        <oms:OrderItemComponentState componentId="{$componentId}">
                            <oms:ComponentKey>{$componentKey}</oms:ComponentKey>
                            <oms:ExternalFulfillmentState>{$externalFulfillmentState}</oms:ExternalFulfillmentState> 
                        </oms:OrderItemComponentState>
                }
                </oms:OrderItemExternalFulfillmentState>
        }    
        </oms:ExternalFulfillmentStates>
};

Orchestration Order Template Definition

Define the orchestration data on the entity that best reflects its structure, rather than defining all of the data on the order specification. Design Studio generates the order level order template by aggregating the order template definitions for the order item specifications and order components with any data defined at the order level.

You should define data at the level where it is needed:

Using this method supports:

Creating and Deploying Custom Files

Custom files can be created and written in Design Studio. This can be done by creating a cartridge and adding custom Java, JavaScript, XSLT, XSD, or XML files to the cartridge. In the Java perspective Package Explorer view, you can create package structures and custom files as needed.

OSM JAR files are not automatically pulled into the project library list within Design Studio; depending on what the custom files reference, you may need to update the project library list to include external JAR files.

Custom files added to a cartridge are deployed to the OSM server as part of the cartridge.

Installing Apache Ant

For information on Ant, and how it is used in OSM development, see "Apache Ant". This section describes how to install and configure Ant.

To install Ant:

  1. Go to the Apache Ant Web site:

    http://archive.apache.org/dist/ant/binaries

  2. Click the Ant installation .zip file corresponding to the supported Ant version as specified in the OSM Installation Guide.

    The File Download window appears.

  3. Click Save.

    The Save As window appears.

  4. Browse to a local working directory and click Save.

  5. Navigate to the local working directory where you saved the downloaded ZIP file.

  6. Extract the contents of the ZIP file to a designated directory.

    The Ant installation directory, for example, apache-ant-1.8.1, is created by the extraction, and the contents of the ZIP file are placed within this directory.

To configure Ant:

  1. From the Windows Start menu, select Control Panel, then select System.

    The System Properties window appears.

  2. Click the Advanced tab.

  3. Click Environment Variables.

    The Environment Variables window appears.

  4. Define a new system variable named ANT_HOME:

    1. In the System Variables section, click New.

      The New System Variables window appears.

    2. In the Variable name field, enter ANT_HOME.

    3. In the Variable value field, enter the path to the extracted Ant installation directory. For example, C:\apache-ant-1.8.1.

    4. Click OK.

  5. Define a new system variable named JAVA_HOME:

    Note:

    If you installed WebLogic Server, this variable may already be defined. If so, ensure that it is set to the correct value.
    1. In the System Variables section, click New.

      The New System Variables window appears.

    2. In the Variable name field, enter JAVA_HOME.

    3. In the Variable value field, enter the path to the jdk directory that is part of your WebLogic Server installation. For example, C:\WebLogic\jdk160_11.

    4. Click OK.

  6. Update the existing system variable CLASSPATH:

    1. In the System Variables section, select CLASSPATH, then click Edit.

      The Edit System Variables window appears.

    2. In the Variable value field, add the path to the extracted Ant installation directory.

      For example, C:\apache-ant-1.8.1.

    3. In the Variable value field, add the path to the jdk directory that is part of your WebLogic Server installation. For example, C:\WebLogic\jdk160_11.

    4. Click OK.

  7. Update the existing system variable Path:

    1. In the System Variables section, select Path, then click Edit.

      The Edit System Variables window appears.

    2. In the Variable value field, add the path to the bin directory of the extracted Ant installation directory.

      For example, C:\apache-ant-1.8.1\bin.

    3. In the Variable value field, add the path to the bin directory that is part of your WebLogic installation.

      For example, C:\WebLogic\jdk160_11\bin.

    4. Click OK.

      The Environment Variables window appears.

  8. Click OK.

    The System Properties window appears.

  9. Click OK.

About XML Catalogs

XML Catalogs are logical structures that act like address books or directories. XML Catalogs contain entries that indicate a placeholder location and then provide the path to the location to be used. At run time, when OSM processes a URI you specify as part of the OSM data model, OSM first attempts to resolve the URI against the XML Catalogs you specified. Based on the mapping defined in the XML Catalogs, OSM can update the URI to adapt to different environments by resolving the location of the URI in your data model with the location it is mapped to in the XML Catalog. For example:

See the OASIS Web page:

http://www.oasis-open.org/committees/entity/spec-2001-08-06.html

for more information on XML Catalogs and valid XML Catalog entries.

See "Using XML Catalogs in OSM" for information on how you can use XML Catalogs in your OSM development.

Using XML Catalogs in OSM

In Design Studio, you model behaviors such as business rules and other model components, which OSM uses at run time to satisfy your business requirements for order processing. The model components used at run time to manage and fulfill orders are referred to as OSM resources and are often contained in resource files. Examples of resource files include XQuery files, XSLT files, custom JAR files, third-party JAR files, and XML files such as a product class mapping file. There can be a large quantity of resources and some of those resources must reference each other. Resources in OSM can be referenced through URI locators in your data model.

A resource must reside on some physical location on a system. Each system has its own unique directory structure. If you use static values or constants to indicate the location of a resource when defining the URI locator for that resource in your data model, the resource will not be accessible if you deploy your cartridge to other systems where the resource is in a different directory. Thus, using static values to indicate the location of a resource limits the portability of your cartridge solution to other systems or run-time environments. XML Catalogs solve this problem by redirecting the URI defined in your data model to the URI where the resource actually resides in whichever run-time environment you deploy your cartridge. XML Catalogs provide a redirection from a URI to another URI. By redirecting the resource URI locators, XML Catalogs serve to insulate your cartridge solution from environment configuration.

At run time, when OSM processes a URI you specify as part of the OSM data model, OSM first attempts to resolve the URI against the XML Catalogs you specified. Based on the mapping defined in the XML Catalogs, OSM updates the URI to adapt to the environment by resolving the location of the URI in your data model with the new URI you mapped for it in the XML Catalogs.

OSM processes XML Catalogs in the order you specify them, as follows:

Following are some examples of data OSM looks up from resource files at run time that you could use the XML catalog to redefine:

See "Specifying XML Catalogs for OSM" for instructions on how to specify XML Catalogs.

You can use the XML Catalog as a tool to perform cartridge versioning, to shorten development cycles, to allow for cartridge extensibility, and to insulate test and production environments from development-specific environments. See "Examples of Using XML Catalogs" for examples of these uses of the XML Catalog.

You can specify a common resources cartridge project that contains all of the shared resources across multiple cartridge projects. Defining the XML Catalog in this common resources cartridge consolidates the XML Catalog entries in one file which makes it easy to identify and eliminate conflicting catalog entries. See "Resource Packaging Considerations for Using XML Catalogs" for information on how you can package your resources when using XML Catalogs.

You can use any valid XML Catalog entry in your XML Catalog, but the rewriteURI entry is the most useful for OSM. See "Defining rewriteURI Entries in XML Catalogs" for information on defining rewriteURI entries for OSM.

Resource Packaging Considerations for Using XML Catalogs

You can specify a common resources cartridge project that contains all of the shared resources across multiple cartridge projects. Defining the XML Catalog in this common resources cartridge consolidates the XML Catalog entries in one file which makes it easy to identify and eliminate conflicting catalog entries. When you specify a common resources cartridge project in this way, other projects with model entities that reference the shared resources do not need to have an XML Catalog defined.

When you define resource properties in Design Studio, you can indicate to retrieve the resource by expression, file, or URI. XML Catalogs apply only to the URI option.

Consider the following when making your decision on which option to choose:

  • Select Expression when the XQuery expression is short (only a few lines in length) and is not shared by other resources.

  • Select File, also referred to as Bundle In, when the XQuery configuration is longer (more than a few lines in length) and is not shared by other resources. Use this method for resources that are not expected to change. You will not be able to access the resource except in the physical location specified. In addition, a resource referenced through File or Bundle In must exist in the same project as the entity referencing it.

  • Select URI when the XQuery configuration is shared by multiple configurations and is located in a remote URI location to be accessed through the specified URI. If the XQuery configuration requires frequent changes, even though it is only used in one cartridge, you may want to use the URI option and also package the XQuery in a separate cartridge. That way, you can modify and redeploy the resource without having to compile and redeploy the possibly larger cartridge that uses it.

Figure 3-5 shows the Expression, File, and URI options in the XQuery tab of a Design Studio editor:

Figure 3-5 URI Option for Defining Resource Properties

Description of Figure 3-5 follows
Description of "Figure 3-5 URI Option for Defining Resource Properties"

Oracle recommends you package resources in the following ways:

  • Package resources to be used by a single cartridge in the cartridge itself. Select File or Bundle in when you define the resource properties in Design Studio.

  • Package resources to be used by multiple cartridges into a shared or common resources cartridge and do the following:

    • Configure the resources to be retrieved by a URI. Select URI when you define the resource properties in the XQuery and XSLT tabs of the Design Studio editor.

    • Configure OSM to access the resources inside of the deployed common resources cartridge through a URI locator.

    Another reason to package resources in a common resource cartridge is when you need to change those resources frequently and they are used by a large cartridge that has automation and model entities that take a long time to build, package, and deploy. By packaging resources that change frequently in a common resources cartridge, you avoid having to rebuild the larger cartridge each time you change the resources.

Defining rewriteURI Entries in XML Catalogs

This section describes how to define a rewriteURI entry in the XML Catalog for OSM. See "Using XML Catalogs in OSM" for general information about XML Catalogs and how they work with OSM.

You can use any valid XML Catalog entry in your XML Catalog, but the rewriteURI entry is the most commonly used entry for OSM. OSM uses the rewriteURI entry to replace the starting string of a URI (such as a URL) with an alternative string. For example, OSM could replace http://somewhere.org/something at run time with http://myhost/something.

During data modeling, you can define a URI locator (such as a URL) to access a resource as part of the OSM data model by using the XQuery and XSLT tabs of various Design Studio editors. For example, in the Order Recognition Rule editor you specify a URI to denote that the XQuery configuration for the recognition rule is hosted in a remote URI location such as http://osm_server/AIARecognitionRule.xqy. You can use the XML Catalog for any of the URIs you specify in the Design Studio editors. OSM uses the rewriteURI entry of the XML Catalog to update URIs you defined in your data model to adapt to different environments.

OSM replaces the starting string of a URI/URL with an alternative string as specified by the rewriteURI entry in the XML Catalog. For example, for this rewriteURI entry:

<rewriteURI uriStartString="http://example.org/somewhere" rewritePrefix="http://192.0.2.0/foo"/>

when OSM processes a URI that starts with http://example.org/somewhere, it replaces that starting string with http://192.0.2.0/foo. A URI you define in Design Studio as http://example.org/somewhere/myfolder/myfile.txt resolves as http://192.0.2.0/foo/myfolder/myfile.txt at run time.

Note:

The uriStartString and the rewritePrefix attributes can be any valid URI: they do not have to be an IP address or host name.

uriStartString is set to the start of the resource URI you defined in Design Studio and rewritePrefix is set to the string OSM replaces uriStartString with after you deploy the cartridge.

To reference resources packaged inside of an OSM cartridge, you can use the OSM model scheme ("osmmodel") rather than the traditional URI schemes (HTTP, FTP, and so on) to define the URI. For example, for this rewriteURI entry:

<rewriteURI uriStartString="http://example.org/somewhere" rewritePrefix="osmmodel:///MyCartridge/1.0.0/resources"/>

when OSM processes a URI that starts with http://example.org/somewhere, it replaces that starting string with osmmodel:///MyCartridge/1.0.0/resources. A URI you defined in Design Studio as http://example.org/somewhere/myfolder/myfile.txt is resolved as osmmodel:///MyCartridge/1.0.0/resources/myfolder/myfile.txt.

This allows you to leverage the contents of the resources directory in each OSM cartridge at run time.

The format of an OSM model schema URI is:

osmmodel:///CartridgeName/CartridgeVersion/resources

where:

  • osmmodel indicates a location inside of a deployed OSM cartridge

  • CartridgeName is the name of your cartridge

  • CartridgeVersion is the version of the cartridge (specified in the cartridge editor)

    The default cartridge version uses the value default.

Note:

See "Using XML Catalogs to Support Cartridge Versioning" for more information on cartridge versioning.

To enable cartridges to refer to resources contained in other cartridges in a non-version specific way, you refer to the default cartridge version. To refer to the default cartridge version, use the OSM model schema URI:

osmmodel:///cartridge_name/default/resources

See "Using XML Catalogs to Support Cartridge Versioning" for information on how the XML Catalog supports cartridge versioning.

Important:

To guarantee the correct resource is located, ensure that resources are always uniquely identifiable to a single catalog entry.

When defining XML Catalog entries, do not define mappings that can be satisfied by more than one entry. The following example shows two rewriteURI entries that can be used by OSM at run time to resolve the same URI locator in two different ways:

<rewriteURI  uriStartString="http://oracle.communications.ordermanagement.sample.centralom.resources/com" rewritePrefix="osmmodel:///CommonResourcesCartridge/1.0.0/resources/com"/>
<rewriteURI uriStartString="http://oracle.communications.ordermanagement.sample.centralom.resources" rewritePrefix="osmmodel:///CommonResourcesCartridge/1.0.0/resources/comMapping"/>

Using the preceding rewriteURI entries, OSM can resolve the URI locator http://oracle.communications.ordermanagement.sample.centralom.resources/com/foo.xml as

osmmodel:///CommonResourcesCartridge/1.0.0/resources/com/foo.xml or osmmodel:///CommonResourcesCartridge/1.0.0/resources/comMapping /com/foo.xml.

Specifying XML Catalogs for OSM

You specify XML Catalogs for an OSM cartridge project in the cartridgeProject\xmlCatalogs\core\ directory (where cartridgeProject is the root of the project directory). In this directory, you create your XML Catalog file (you can use any filename such as core.xml or catalog.xml) and define your catalog entries within it. Design Studio automatically generates a template XML Catalog file cartridgeProject\xmlCatalogs\core\xmlCatalogCoreTemplate.xml.

You specify XML Catalogs on the OSM server in the OSM configuration entry oracle.communications.ordermanagement.util.net.CatalogUriResolver.DefaultXmlCatalogsUris. By specifying XML Catalog files on the OSM server, you can operationally modify how OSM resolves URIs without changing the contents of a cartridge. See "Using XML Catalogs in OSM" for information on how OSM resolves URIs based on the XML Catalogs you specify on the OSM server.

To specify XML Catalogs on the OSM server:

  1. Add or modify a configuration entry for oracle.communications.ordermanagement.util.net.CatalogUriResolver.DefaultXmlCatalogsUris in the oms-config.xml file.

    See the chapter on configuring OSM with oms-config.xml in OSM System Administrator's Guide for detailed instructions on accessing and modifying the oms-config.xml file.

  2. Enter the XML Catalog entries you require.

    • Multiple XML Catalogs can be specified separated by a semicolon (;).

    • Use any standard XML Catalog entry. The rewriteURI entry is the most commonly used for OSM. See "Defining rewriteURI Entries in XML Catalogs" for information on defining rewriteURI entries.

    Important:

    The XML Catalog entries you specify are applied system wide. Ensure that resources are uniquely identifiable to a single catalog entry so that the correct resource can be located.

    Note:

    This configuration defines the XML Catalog entries inline in the oms-config.xml configuration file.
  3. Save the file.

Enabling and Disabling XML Catalog Support

XML Catalog support is enabled by default for all cartridges and is required to be enabled.

If your target run-time software version is OSM 7.0.2 or earlier, you can disable XML Catalog support for a cartridge (or re-enable it) by using the cartridge model variable XML_CATALOG_SUPPORT. For information on disabling or re-enabling XML Catalog support for a cartridge, see the Design Studio Help.

Examples of Using XML Catalogs

This section provides the following examples of how you can use the XML Catalog:

Using XML Catalogs to Support Cartridge Versioning

Cartridge versioning requires that different versions of resources be loaded correctly. If you have version 1.0 and version 2.0 of an OSM solution deployed, you might have version-specific XQuery or JAR files that need to be used depending on which OSM solution you are using. To ensure the correct version is loaded, you encode the version in the URI locator for the resource. However, if you had to encode a version identifier in each URI locator, you would need to update hundreds of URIs every time you changed a version number. Using a cartridge model variable to externalize the version number is a way to manage the version number in one place. You use %{MODEL_VARIABLE_NAME} in the URI locators and set the value for MODEL_VARIABLE_NAME once in the cartridge editor Model Variables tab. OSM can then search and replace all instances of %{MODEL_VARIABLE_NAME} when the model is deployed to the server.

Multiple cartridge versions must reference their own versioned set of resources. If you have a cartridge that uses a URI to reference XQuery resources, a new version of that cartridge must use new versions of the XQuery resources. Deploying the old version and new version of that cartridge on the run-time environment during the same time period poses a problem because the URI is global and is mapped to a single destination. Using cartridge versioning, you can point to a version-specific resource directory for the old and new version of the cartridge (rather than encoding version-specific information in the URIs).

To allow multiple cartridge versions to refer to their own set of resources by using the XML Catalog, follow these high-level steps:

  1. In the Design Studio Model Variables tab of the cartridge editor, set the cartridge model variable CARTRIDGE_VERSION to the version number of the cartridge.

    For example, CARTRIDGE_VERSION = 2.5

  2. In the parts of your model where you need OSM to substitute the model variable, insert %{CARTRIDGE_VERSION}.

    Example: Use the model variable in the URI locator http://company.com/%{CARTRIDGE_VERSION}/xquery/myFile.xqy

  3. Define the rewriteURI entry to point to the version-specific resource directory in the XML Catalog file of your cartridge:

    Example:

    <rewriteURI uriStartString="http://company.com/2.5" rewritePrefix="osmmodel:///MyCartridge-Resources/2.5/resources"/
    

    Tip:

    When the XML Catalog is specified and enabled, resources located through a URI locator are loaded based on the rewriteURI configuration.
  4. When you create a new cartridge version, update the cartridge model variable with the new version value.

    OSM uses the cartridge model variable value to update all entities that use the model variable. For example, OSM updates order recognition rules, URI resources, XSLT resources, and XQuery resources that use %{MODEL_VARIABLE_NAME} with the cartridge version value.

  5. Update the XML Catalog rewriteURI configuration in your XML Catalog file to point to the version-specific resource directory of the new cartridge version.

    Note:

    Be sure to update all XML Catalog URL instances.

Using XML Catalogs to Load Resources from a Development File System

To shorten development cycle times that involve numerous coding, building, deployment, and test cycles, you can use the XML Catalog to load resources from a development file system. By using the XML Catalog in this way, you can test changes to resources located within the cartridge without needing to rebuild and repackage the cartridge. Rebuilding and repackaging can be slow and CPU intensive because Design Studio needs to rebuild the deployment EAR file before any changes can be tested. By redirecting the URIs to a local resource, you can change XQuery, XSLT, XML, or Java code and immediately test the changes without having to rebuild, repackage, and redeploy (Java code would still need to be rebuilt but not repackaged and redeployed).

For example, use the XML Catalog to instruct OSM to load resources:

  • From the development file system during development

  • From the cartridge PAR file after testing

Locate resources on the file system instead of from within the cartridge PAR file so that configuration changes made to a resource are picked up by the run-time environment without having to rebuild and redeploy the cartridge. After testing is complete, the URI is redirected to load resources from the cartridge PAR file.

To redirect the URI so that OSM loads resources from the development file system:

  1. In the Package Explorer view in Design Studio, navigate to the cartridgeProject/xmlCatalogs/core/ directory.

  2. Create or edit the catalog.xml file. You can create the file by renaming a copy of xmlCatalogCoreTemplate.xml.

  3. Create the XML Catalog entry:

    <rewriteURI uriStartString="http://example.org/somewhere" rewritePrefix="file://localhost/dev/env1/mycartridge/resources"/>
    

    OSM loads all resources that start with http://example.org/somewhere from the file system located on localhost at /dev/env1/mycartridge/resources.

To redirect the URI so that OSM loads resources from the cartridge PAR file after testing is complete, change the preceding configuration to:

<rewriteURI uriStartString="http://example.org/somewhere" rewritePrefix="osmmodel:///MyCartridge/1.0.0/resources"/>

OSM loads all resources that start with http://example.org/somewhere from the cartridge PAR file.

The XML Catalog supports resource extensibility in a cartridge solution because URIs can be easily rewritten to change the location from which resources are loaded. The XML Catalog allows you to redirect the cartridge solution to use customized resources different from the ones that were originally provided by the cartridge solution.

Using XML Catalogs to Insulate Run-Time Environments from Development

To insulate test and production environments from development-specific environments, you can use the XML Catalog. When you develop your code, you can set your XML Catalog to point to local resources on your file system on your laptop. Assume you have an automated test environment that runs daily tests on certain cartridges that use resources on the testing box. In production, you would use the XML Catalog to point resources to your production machines. Note that in this example the resources are not bundled inside of the cartridges.