16 Managing OSM Solution Cartridges

This chapter describes managing cartridges in an Oracle Communications Order and Service Management (OSM) solution.

Solution Management Overview

Cartridges are an important part of every OSM solution. OSM is a metadata-driven system that includes model entities necessary for order management functions. OSM model entities include tasks, processes, data elements, data structures, orchestration stages and sequences, decomposition rules, roles, order life cycle policies, and so on. You define how you want to use and extend OSM to meet your business needs by creating these model entities in Oracle Communications Design Studio. Design Studio is a client application with editors that allows you to configure the OSM model and model entities. In addition to the model entities, you can create and include artifacts such as automation plug-ins, XQuery and XSLT scripts, XML Catalog, and other resource files in a cartridge. You must package these entities and artifacts and deploy them to the OSM system as cartridges.

Creating and modeling cartridges in Design Studio is a design-time activity. You do not use Design Studio to manage a run-time environment. Once you have created cartridges in Design Studio, you can build the cartridges and then deploy them into a run-time OSM environment. Deploying is the act of installing a packaged cartridge to the run-time environment, which is where orders are executed, and where end users login and use the OSM Order Management web client or Task web client to view and manage orders and tasks. The run-time environment could be an OSM server that is installed on the local machine of a developer along with Design Studio, or could be a dedicated OSM environment setup with some server hardware. You do not require an OSM run-time environment to use Design Studio to model and build cartridges, but you do require an OSM run-time environment to deploy and test cartridges with test orders.

An OSM solution is typically made up of multiple cartridges. Each cartridge is a building block that specifies an aspect of the OSM solution. For example, some cartridges may define how OSM interacts with particular fulfillment systems. Other cartridges may define data dictionaries common across applications, and shared across other OSS applications such as Oracle Communications Unified Inventory Management (UIM) or Oracle Communications ASAP. Some cartridges are more foundational to an OSM implementation, such as those that specify how orders are represented and how order decomposition and orchestration occur. Together, they contain the directives of the OSM implementation for a particular deployment such as OSM running in the central order management (COM), service order management (SOM), and technical order management (TOM) roles.

Cartridges allow you to decouple solution behavior from the core OSM system that the cartridges run on. This decoupling allows you to upgrade to a newer versions of OSM to take advantage of improvements without needing to make extensive changes to the solution cartridges.

Cartridges can also help you manage development cycles. You can use cartridges to divide OSM development work into logical pieces among development team members contributing to the implementation. For example in Figure 16-1, OSM developer 1, 2, and 3 work in parallel on different component cartridges in the solution. You can also port cartridges between OSM environments. This is useful for sharing between developer team members, promoting cartridges from development to test environments, or from test to production.

Figure 16-1 Cartridge Portability in Development, Test, and Production Systems

About OSM Cartridge Scope

Cartridge scope refers to the logical boundary of whether an OSM model entity would be visible to various orders or not, once it is deployed to the run-time environment. If a particular OSM entity is considered in scope, that entity can be used to influence how that order is processed. Conversely, the entity cannot influence an order if it is considered out of scope; that is as if the entity never existed in the run-time environment, in the perspective of that order.

The scoping mechanism of OSM has evolved over the years. The following sections describe how scoping behaves in different releases of OSM.

Scope of OSM Entities Without Namespaces

In OSM 6.x, entities only have visibility to other entities contained within its cartridge version; they cannot, for example, reference another entity that resides in another cartridge or another version of the same cartridge name.

In an OSM 6.x run-time environment where multiple cartridge versions are deployed, each cartridge version is self-confined. That is, as an incoming order is tied to an Order type of a cartridge version, processes and tasks in that cartridge version are solely used for processing of that order. Models located in other cartridges shall have no impact; this is even true for processes and tasks or other 6.x entities of the same name across different versions of cartridges.

Let's illustrate with an example. Version 1.0 of Cartridge BServiceOM contains Order type BusinessServiceOrder, Process BSOProcess, and Tasks A, B, as well as other 6.x entities. Version 1.1 of the same cartridge contains the same things but has added Task C, and made updates to Task B and the flow of BSOProcess. Version 1.0 of Cartridge RServiceOM contains Order type ResServiceOrder and other 6.x entities. They are all deployed to an OSM run-time environment.

Figure 16-2 An Example of Cartridge Namespaces in an OSM Run-Time Environment

If order 123 is tied to Cartridge BServiceOM 1.0, it will not be influenced by, say, BSOProcess or Task B of BServiceOM 1.1, even though it has a Task with the same name, B, at its own cartridge version. The converse is true similarly for order 147 that is tied to Cartridge BServiceOM 1.1 – it will be impacted by Task B of BServiceOM 1.0.

Thus essentially, the cartridge name is the identifier that confines entities of the cartridge to a logical scope. For this reason, the name of the cartridge is commonly referred to as the cartridge namespace.

Scope of OSM Entities with Namespaces

OSM 7.0 introduces many new entities to configure for orchestration. Along with it, OSM 7 introduces a separate mechanism to scope them. For almost all entities that are introduced in OSM 7.0 and later, there is an explicit namespace attribute that you can specify for each of them in Design Studio. To illustrate, orchestration entities such as order component specification, order item specification, order recognition rule have such namespace attribute that can be configured in Design Studio.

For convenience in this document, we shall refer all OSM entities that have the namespace attribute as 7.x entities. Those that do not, such as Order and Task, are referred to as 6.x entities. Based on this qualification, not all ”6.x entities” are actually introduced before OSM 7. For instance, the Composite Cartridge View is qualified as a ”6.x entity” even though it is introduced in 7.2, as the entity is essentially a task view and thus was not provided a namespace by design.

Scoping of 6.x entities remain the same in OSM 7.0.x, which is confined by cartridge namespace and version. However in Design Studio, beware that you are not forbidden to reference 6.x entities across cartridges. For instance, when specifying flow of a Process in cartridge A, you are allowed to use a Task in cartridge B. In OSM 7.0.x, you should never do so, since the task will not be found at run-time due to scoping.

For 7.x entities, rather than simply confined by cartridge namespace and version, 7.x entities are referenced by their fully qualified names. The fully qualified name is the combination of:

• Entity type – for example, Order Component Specification

• Entity name – for example, TargetSystem

• Entity namespace – for example, http://oracle.centralom.topology

The figure below illustrates a simple example of how a 7.x entity is referenced by another model. The referencing by fully qualified name occurs ”behind the scenes” when the cartridges are packaged at build time. All you need to do is provide an appropriate entity namespace for all 7.x entities in Design Studio.

Figure 16-3 Referencing 7.x Entity by Fully Qualified Name

Notice that the cartridge namespace (OsmCentralOMExample-Topology) is not part of the fully qualified name. That is, cartridge namespace does not form scoping boundaries for 7.x entities. Cartridges are really just containers for their deployment purposes. Entities can freely reference 7.x entities of other cartridges as long as the fully qualified name is unique in the run-time environment.

A namespace collision may occur when multiple 7.x entities have the same fully qualified name in a run-time environment. This is not an uncommon occurrence when multiple cartridge versions are deployed. For example, in the figure below, TargetSystem between cartridge version 1.0 and 1.1 has duplicated fully qualified name.

Figure 16-4 Namespace Collision of 7.x Entity

In the event of namespace collision, OSM will simply replace one entity over the other – essentially the last loaded stays – and the loading order is not deterministic. For those who are keen to understand the internal mechanics of OSM 7.0.x, a system-wide internal ”resource pool” directory – akin to a virtual file system – is constructed to help locate entities as they are loaded. In the example, it is unknown whether version 1.0 or 1.1 of TargetSystem will be loaded by OSM, but both OsmCentralOMExample-Orchestration 1.0 and 1.1 are going to use the same version of TargetSystem, which means one of them is getting the wrong version

To avoid namespace collision across cartridge versions, the entity namespace shall include a representation of the cartridge version. In our example, the namespace can be specified as, say, http://oracle.centralom.topology/1.0.0.0.0. However, specifying the cartridge version in the namespace would require an update to all entity namespace fields within the cartridge when a version increment is required. In the past, a model variable is used to substitute the cartridge version value in the namespace (http://oracle.centralom.topology/%{CARTRIDGE_VERSION}) to simplify version increments. However with XML Catalog introduced in 7.0.3, the best approach is to keep the entity namespace agnostic to cartridge version, and have XML Catalog to translate namespace of 7.x entities into model location that is cartridge version specific. See [Managing Cartridge Version in XML Catalog Files?] later on in the document for details.

OSM 7.2 and beyond continues to support deploying an OSM implementation as standalone cartridges, albeit the recommended approach is to adopt to the use of composite cartridge. This is because namespace collisions continue to exist with standalone cartridges.

The internal mechanics of locating resources in 7.2.x is slightly enhanced from 7.0.x. Rather than building a singular resource pool that is system-wide as described previously, OSM 7.2.x builds a resource pool for each cartridge when they are loaded, and has three levels of priority tailored to that cartridge. Resources at the local cartridge version are prioritized first, then resources at the cartridge versions of the same cartridge namespace are prioritized second (but in no particular order among versions), and lastly, resources of all other cartridges are prioritized last (in no particular order again).

The priority in such an individualized resource pool means that it is more likely that the OSM server will find the correct copy of 7.x entity when namespace collision occurs, but does not completely eliminate the problem. For instance, it does not help when namespace collision occurs when the reference is not local, as OSM server will arbitrarily choose a copy if there are multiple cartridge versions.

Since patch 7.2.0.7 and 7.2.2.3, further tweaks to scoping of standalone cartridges have been applied and been made configurable. These tweaks are conventionally called FullScopeAccess. First, to save on memory footprint, resource pools are built on only cartridges that contain order definition (Precisely, to those who are familiar with older OSM releases, this is referring to having order source and type.). Second, a FullScopeAccess parameter configurable in the oms-config.xml file is made available, which allows you to choose whether resource pools shall be built to only refer to local cartridge version, or also include other cartridges as it was prior to the patch. For detailed explanation, please see KM note 1568944.1.

It is noteworthy that the FullScopeAccess parameter is defaulted to only refer to the local cartridge version. Thus upon a patch or release upgrade from pre-7.2.0.7/7.2.2.3, if you want to maintain existing scoping behavior, you would have to explicitly configure the oms-config.xml parameter to revert to so. Lastly, the FullScopeAccess enhancement is not ported back to any patches of OSM 7.0.3 or earlier releases, but is in the 7.2.4 GA release.

The FullScopeAccess enhancement and configuration does not impact composite cartridges at all. Again, when upgrading towards 7.2.x, it is highly recommended to adopt composite cartridges to avoid all the headaches originated from namespace collision. However for migration reasons, if you have standalone cartridges deployed in production system along with composite cartridges, note that the resource pools of standalone cartridges will contain resource references of those component cartridges contained in composite cartridges. That is, you will still need to ensure the standalone cartridges can be deployed along with other cartridge versions before being able to migrate.

Composite Cartridge Scope

In release 7.2, composite cartridges are introduced. It is the major advancement in OSM cartridge management that is expected to become the mainstream method to managing the lifecycle of an OSM implementation. If your OSM implementation has not adopted to using composite cartridges, you are strongly recommended to do so. Particularly if you are running into cartridge versioning problems, using composite cartridges will be a worthwhile exercise, even if it means going through the effort of an OSM upgrade from an existing 6.x or 7.0.x release.

Let's begin with how composite cartridges work. A composite cartridge is a ”special” type of cartridge that cannot directly contain any OSM models at design-time. It is best to think of it as a container of cartridge references that makes up an OSM implementation. In Design Studio, it contains only one model, which is the (composite) cartridge-level model itself. In it, you can manage the 5-segment cartridge version of the composite cartridge. The composite cartridge can only reference component cartridges, but not other composite cartridges, which is managed in the Dependency tab.

The composite cartridge provides solution-level scoping boundaries that are appropriate for running concurrent cartridge versions of an OSM implementation. This is largely achieved behind the scenes at build-time. Specifically, when the composite cartridge is built, all 6.x entities in all component cartridges within are aggregated to become one new deployable cartridge artifact. This run-time cartridge holds the namespace of the composite cartridge. Meanwhile, all 7.x entities stay in their respective component cartridges.

To illustrate, the following is a simple example of a composite cartridge having two component cartridges – a base cartridge and a billing cartridge, and how the run-time cartridges will be generated by the build process:

Figure 16-5 The Use of Composite Cartridges in Design-Time versus Run-Time

In this example, a run-time cartridge with name COMExample-Soln is generated to contain all 6.x entities such as Order, Processes and Tasks. Component cartridges COMExample-Base and COMExample-Billing retain their 7.x entities. When a deploy command is issued on the composite cartridge at Design Studio or CMT, all the component cartridges and the generated component cartridge are deployed to the run-time environment. When an incoming order is to be tied to the Order entity of this composite cartridge version, it is in fact tied to the namespace of the generated cartridge, by the name of the composite cartridge COMExample-Soln.

By aggregating all the 6.x entities of the solution into a single cartridge, there is no longer reference ambiguity when 6.x entities are scattered in various component cartridges and when multiple cartridge versions are deployed. In our example, if cartridge COMExample-Billing version 1.0 and 1.1 are deployed, Task BillingFunctionTask from cartridge COMExample-Billing1.0 will be used by orders that are tied to COMExample-Soln 1.0, since the order model and the task are now confined to that same cartridge and version. This predictability in scoping, when referencing across cartridges for 6.x entities, is impossible without the use of composite cartridge.

Composite cartridge also addresses the problem of namespace collision for 7.x entities. The composite cartridge establishes a manifest that explicitly specifies the component cartridge version whenever an entity dependency is established across cartridges in the solution. Conceptually, the scoping of models and resource files in component cartridge versions are confined to the OSM ”solution” bounded by the composite cartridge. Again in our example, if cartridge COMExample-Billing version 1.0 and 1.1 are deployed, orders tied to COMExample-Soln 1.0 will know to use BillingFunction from COMExample-Billing1.0 instead of 1.1, when the same fully qualified name exists in both. With this capability, there is no longer a need to embed cartridge version information into namespace of 7.x entities when composite cartridges are used.

Special Models and Artifacts Scope

For the majority of OSM entities, their use is referenced by other entities that are eventually tied to the Order type. However, there are models and artifacts where they can influence the OSM system beyond logical boundaries that are typical to their resident namespace. The obvious entity is the order recognition rule; this section discusses all artifacts that deserve your special attention when managing cartridge life cycles.

Order Recognition Rule

Order recognition rules (ORR) are a particularly special entity in terms of scoping. When CreateOrder API call is invoked, OSM does not know the version or namespace of the incoming order, and it is the job of ORRs to be able to interrogate inbound messages to determine the kind of order they are (or aren't, as it may be). Even though an ORR has a namespace field just like other 7.x entities, their scope is truly system-wide – all ORRs in the OSM run-time environment are used to match to recognize order payload in CreateOrder, regardless of which cartridge that an ORR resides in. This is true for ORRs located in both standalone component cartridges, and those contained by a composite cartridge. Essentially, ORRs ignore both cartridge version and namespace.

So if you have two versions of an ORR that are both deployed and will pick up the same order type A, how can you know which ORR will get executed first and therefore pick up the orders of type A first? That sequence is determined by their ”Relevancy” setting. OSM will run ORRs on an inbound message from highest to lowest relevancy, until the first match where the ORR recognizes the order. An ORR's relevancy is set on the Recognition sub-tab of the editor for an order recognition rule in Design Studio. Once an ORR is matched, the incoming order is tied to the target order type (and thus its cartridge namespace) that the ORR designates.

Fulfillment Pattern

Fulfillment Pattern, previously known as Product Specification, is responsible for assigning the fulfillment of an order item in the generated orchestration plan. Fulfillment Patterns have their namespace, just like other 7.x entities. However, finding the fulfillment pattern of an order item is a bit of a unique case in scoping – in Order Item Specification, an order item property is designated to map the order item to the Fulfillment Pattern, which appears to be a string match. For example, if ”Service.Broadband” is the value in the order item property to match, OSM only looks for a Fulfillment Pattern that is ”Service.Broadband”. Finding a 7.x entity name using fully qualified name does not seem to be followed.

However, in fact, OSM actually finds the Fulfillment Pattern by fully qualified name, but assuming the namespace of Fulfillment Pattern to be the same of the Order Item Specification's. Because of this, it is important to set the same namespace value between your Order Item Specification and Fulfillment Patterns of your OSM solution. Otherwise, OSM cannot find the Fulfillment Patterns for the order items.

Scoping Fulfillment Patterns with composite cartridges offers similar advantages over standalone cartridges. Consider the example below with standalone cartridges. Cartridge COMExample-FulfillPattern1.0 contains fulfillment patterns Service.Broadband, Service.Fixed and Service.Mobile. Cartridge COMExample-FulfillPattern2.0 introduces new Service.VOIP as well as making changes to existing fulfillment patterns. If the namespaces do not contain cartridge versions, finding ”Service.Broadband” likely results in matching whoever is the last deployed version of the Fulfillment Pattern (for example, 2.0 in a typical case). This results in unexpected and unpredictable behavior in orchestration plan generation, and is obviously undesirable.

Figure 16-6 Fulfillment Patterns in Standalone Cartridges

In contrast, with the use of composite cartridges, OSM understands the logical scope of the solution, and matches fulfillment patterns that are only encapsulated in the composite cartridge. For orders in cartridge version 1.0, only Service.Broadband in COMExample-FulfillPattern1.0 is matched. Similarly for orders in 2.0, only Service.Broadband in COMExample-FulfillPattern2.0 is matched. The collision in fulfillment patterns across cartridge versions is avoided.

Figure 16-7 Fulfillment Patterns Encapsulated in Composite Cartridges

Resource and XML Catalog Files

In addition to OSM model entities, an OSM implementation typically contains other resource files in the cartridges. Query and XSLT files are the most common of all, whether it is for automation plug-ins or for other extension points in the model. There can be other files such as Java files or other XML configuration files, most notably the XML Catalog. The scoping of these resource files follow the same scoping mechanism of OSM entities as described in previous sections of this chapter; you should refer to those sections for details, but to summarize:

• In OSM 7.0.x, resource files are located with a system-wide resource pool.

• In OSM 7.2.x with standalone cartridges before FullScopeAccess patch, resource files are located with a cartridge-specific resource pool that prioritizes local resources.

• In OSM 7.2.x with standalone cartridges after FullScopeAccess patch, resource files are located with the same pool of the cartridge that contains the order, where the pool may or may not contain non-local resource entries, depending on the configuration of the FullScopeAccess parameter.

• OSM 7.2.x Composite Cartridges, resource files of all its component cartridges are confined to the OSM ”solution” bounded by the composite cartridge.

Similar to namespace collision for 7.x entities, it is possible for standalone cartridges to refer to the unintended copy of the resource file when multiple cartridge versions exist. For XQuery files, such collision should be largely mitigated if you are located them via a URL location that is mapped to a cartridge-version specific location using XML Catalog.Consider the following example where cartridge OsmCentralOMExample-Orchestration references an XQuery file located in a centralized resource cartridge OsmResource, and that two versions, 1.0 and 1.1 have been deployed:

Figure 16-8 XML Catalog Conflict

If this reference of the XQuery file is located by URL, say:

http://oracle.centralom/base/xquery/updateOrderFS.xqy,

and that the XML Catalog for cartridge version 1.0 has rewriteURI entry:

http://oracle.centralom/base -> osmmodel:///OsmResources/1.0.0.0.0/resources

and the same XML Catalog for cartridge version 1.1 has rewriteURI entry:

http://oracle.centralom/base -> osmmodel:///OsmResources/1.1.0.0.0/resources

then there is no ambiguity when locating updateOrderFS.xqy since OsmCentralOMExample-Orchestration 1.0 will find the XQuery in OsmResources 1.0 after translating the URL prefix in XML Catalog. That is, the URI of the XQuery file will be resolved to:

osmmodel:///OsmResources/1.0.0.0.0/resources//updateOrderFS.xqy

Similarly, OsmCentralOMExample-Orchestration 1.1 will find it in OsmResources 1.1 by the mapped URI:

osmmodel:///OsmResources/1.1.0.0.0/resources//updateOrderFS.xqy

However, one notable concern of resource file scoping is the XML Catalog files themselves. Each cartridge typically has its own XML Catalog file, and thus there exist multiple XML Catalog files when there are multiple standalone cartridges in a solution. In addition, when cartridge versions are deployed, multiple copies can be found in the same cartridge namespace.

Consider the example above again. It is entirely possible that the wrong XML Catalog file is located. If for instance in OSM 7.0.3, OsmCentralOMExample-Orchestration 1.0 ended up using XML Catalog 1.1 instead of 1.0, the updateOrderFS.xqy in OsmResource 1.1 will be used instead of the 1.0 copy.

The priority preference to local resources in OSM 7.2.x helps locate the correct XML Catalog file to use, but depending on how you have set your rewriteURIs among cartridges' XML Catalogs, it is still possible that OSM ended up loading the wrong rewriteURIs and therefore locating a URI resource at the wrong cartridge or cartridge version.

Not only do you have to be careful with XML Catalog, but to other resource files (that are not mapped via URI using XML Catalog) as well. If you must stay with standalone cartridges, and if you are deploying cartridge versions, you must evaluate your OSM cartridges and possibly need to move/refactor files in cartridges to ensure no collision occurs on resource files. For 7.2.x, because local resource files are prioritized, you can move these resources to the same cartridge that invokes them.

Again, the need to worry about resource pool mechanism and working your cartridge resources around it apply largely only to standalone cartridges. With composite cartridges, there is simply no possibility of resource collision that is due to multiple cartridge versions. This underlies another reason why the use of composite cartridges is the most reliable way to provide proper scoping for your OSM implementation.

Managing Cartridge Versions

The time needed to fulfill orders for a service provider varies among different domains of products and services. For example, consumer orders for mobile services may be seconds or minutes to complete, while consumer orders for fixed line services may take minutes to days, particularly if those orders require human interactions such as physical equipment adjustments or shipments. Business services may take days, weeks, or even months to complete, where an order can encapsulate the services of multi-site network with lots of equipment, off-net components, cabling, etc.

In OSM, existing orders that are running in the system will continue to run against the existing cartridge version that they were using. For example, if order 123 is in progress using cartridge A version 1, and then cartridge A version 2 is deployed to the runtime system, then order 123 will continue to run to completion using cartridge A version 1. This is true for existing orders for cartridge A version 1 that are future-dated as well.

As your OSM implementation evolves to keep up with business, you can either introduce cartridge changes by overwriting the existing cartridge version, or by deploying as a new cartridge version. As you shall see in the following discussion, the longer the order lifetime is, the greater the likelihood that you will need multiple cartridge versions deployed at any one time.

When Cartridges Need a New Version

Often, the changes that are necessary to introduce into a cartridge are not compatible with the way the previous cartridge version worked, or may be disruptive or harmful to the in-progress orders that remain running in the current version of the cartridge. There lies the principle value of cartridge versioning – deploying a new version of a cartridge allows new orders to use the new cartridge, while in-flight orders can continue without disruption in the previous version of the cartridge that it started with. This is often the desired behavior when cartridge changes are for the cause of enhancements, for instance, to support new requirements in another phase of your OSM implementation road map.

Some operators do not want to deal with cartridge versioning at all, and choose to always deploy their cartridges to the same version. To avoid problems with choking in-progress orders in the system, a common tactic is to allow OSM complete the fulfillment of all orders, followed by an order purge operation that removes them from the environment (since the new cartridge may not even be able to read these orders, such as for viewing the order in web UI). For those implementations with a very short order lifetime such as fulfillment for mobile services, this is indeed a plausible strategy. However, there are drawbacks, as it is not possible to keep completed orders in the system for troubleshooting / auditing / reporting purposes. It also limits your implementation from declaring inter-order dependencies (as you cannot guarantee existence of past orders). There are also operational complications that can arise; as inevitably there will be orders that take longer to complete than others, or there are order fallouts. They would need to be dealt with outside of OSM rather than managing them using order fallout capabilities in OSM.

Outside of the above depiction, you should always intend to use cartridge versioning for your production environment. You should also strive for a plan of readiness, starting from cartridge design and implementation, and testing with multiple cartridge versions deployed, all the way to cartridge deployment planning.

This, however, does not mean that you should introduce a new cartridge version every time a change in cartridge content is involved. There are cases where it is necessary to make changes to existing cartridge versions, and redeploying them, as opposed to creating new cartridge versions:

• For fixing critical bugs that need to take effect to existing orders, it may make sense to deploy the fix to the same cartridge version that causes the problem, provided that the fix would not cause incompatibility to in-progress orders.

• Changes need to become effective immediately, applying to existing in-progress orders. For example, an interface change in downstream system that has no backward compatibility support would require OSM adapt to it across all cartridge versions. Generally speaking, the longer-running that orders are, there is more business pressure to make changes that existing orders can take advantage of. For instance for orders in enterprise or business services, it is not uncommon for an OSM implementation to be asked to adopt to the latest business processes or be able to fulfill with resources of the latest technologies.

When changes are required to be made to existing cartridge versions, it is imperative that you ensure that in-progress orders, at any state in its fulfillment execution, can continue to be executed against those changes. KM Note 1612273.1 – A Guideline to Making Cartridge Changes and Re-deploying with the Same Cartridge Version – provides the best practices and analysis at the OSM entity level the do's and don'ts when you endeavor such an activity. It is also imperative to recognize that making changes to existing cartridge versions is risky in nature, and thus adequate test coverage shall be planned and executed to ensure in-progress orders of all scenarios are not impacted (for example, do not stop processing) by those changes.

In general, it is important to minimize the number of cartridge versions that you introduce for performance reasons. Please see the section Minimizing the number of cartridge versions deployed in a production system in this document.

Migrating Orders to a New Version of a Cartridge

Only orders that are in the Not Started order state can be migrated to another cartridge or cartridge version. All running orders (in any order state other than Not Started), including future-dated orders, must continue to run to completion against the version of the cartridge in which they were created.

In the past, there have been deployments of OSM where the operator essentially ”migrates” their orders in the system by re-submitting in-flight orders as new orders to the new cartridge version. This requires either the in-progress fulfillment flow to be manually cleaned up in the fulfillment stack before re-submission, or the flow itself be configured so that past activities can be repeated without needing to be undone (for example, you can resend a message to a downstream system without having to perform any clean up first. This is not quite a recommended way, but nonetheless is a choice where the feasibility mostly hinges on the specifics of your OSM implementation.

Designation of the Default Cartridge Among Cartridge Versions

If there are multiple versions of the same cartridge namespace deployed, which cartridge version would be chosen to be tied to an inbound order of a certain order type? In CreateOrderbySpec request, the cartridge version is an optional attribute while the cartridge name is mandatory as input parameters. In CreateOrder request, the target version cannot be specified as input parameter, but rather could be optionally defined by the matched order recognition rule. In either case, there is the notion of the default cartridge version maintained in the OSM run-time environment. That is, if no target version is explicitly specified, the cartridge version that is deemed the default will be chosen.

For standalone component cartridges, the default designation is configured by the Default flag that is a check box in the Properties tab of the editor for the cartridge entity in Design Studio (In a future release, it is expected that the default flag will be moved to become a cartridge management variable, so that it can be changed without building the cartridges again). This cartridge property is typically set to true for the latest cartridge version. For instance, if version 1 of cartridge A is already deployed and has orders running against it, and version 2 of cartridge A is deployed as the new default version, then new orders created in the runtime system for cartridge A will run against version 2, and any changes made for version 2 will be effective for those new orders.

For composite cartridges, the Default flag also exists at the same location in composite cartridge editor. When set to true, all its component cartridges (and specifically, only those with Standalone flag unchecked in each of their cartridge property) are considered the default versions. The default flag of those component cartridges do not matter to deciding the default version, in fact.

Whether it is standalone or with composite cartridge, the OSM server always recognizes exactly one version as the default for each cartridge namespace. When multiple cartridge versions are deployed with default flag set to true, the OSM run-time environment will make the last deployed version, with default flag set to true, to be the default cartridge.

Special attention is required when deploying an old cartridge version. In the cartridge editor of Design Studio, the "Default" cartridge property is enabled by default, unless you deselect it. For example, cartridge A has version 1 and 2 in OSM. Both cartridge version 1 and 2 will have the Default flag enabled unless you have changed it. This is typically not a problem, as you are deploying chronologically (that is, you deploy version 1, then later deploy version 2). The latest cartridge version, version 2, will end up as the default for new orders. However, if changes are required in cartridge version 1, you will want to ensure that the default flag is un-checked when you deploy it. Otherwise, version 1 will become the default version for new orders, which will not be the intended behavior. There is currently no warning in Design Studio or on the runtime server on deployment that indicates or warns that there is an older version of a cartridge being deployed as the default, so user care is required.

With order recognition rule (ORR), there is the Target Order Version field in the Recognition tab in the editor in Design Studio. You can specify a cartridge version of the chosen order type there, or it can be set to as Default, which means to tie inbound orders from CreateOrder API to the default cartridge version of the order type recognized by the ORR. Internally, this behavior is achieved by the OSM component called Order Recognition Processor (ORP) invoking an (internal) CreateOrderBySpec with the cartridge version specified in the ORR, or that the version is omitted in the call if it is set to Default.

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.

Handling Multiple Cartridge Versions

To distinguish changes in a cartridge over time, each cartridge has a cartridge version. The Cartridge editor in Design Studio contains several fields that make up the version number. In Design Studio 7.2 and onward, there are five fields that constitute the version of a cartridge: Major Version Number, Minor Version Number, Maintenance Pack, Generic Patch, Customer Patch. These constitute a 5-digit version number such as 1.0.0.0.0. In Design Studio versions prior to 7.2, only 3-digit version number was supported, such as 1.0.0, made up of the following three fields: Major Version Number, Minor Version Number, and E-Fix Number. In addition to the cartridge version, there is also a read-only Build Number that is automatically incremented by Design Studio each time a cartridge build is done; it is not reset regardless of any change in cartridge version.

The cartridge version fields are set by you. Deploying a new cartridge version is done by changing the value of these version fields and deploying the cartridge. Multiple cartridge versions can be deployed in an OSM environment at the same time, with orders running against each version.

It should also be noted that in the Cartridge editor in Design Studio there is a Target Version drop-down that must be selected. This represents the version of the run-time OSM environment to which this Cartridge project will be deployed, so that Design Studio builds and validates appropriately for that target OSM runtime environment version. Lastly, there is also a ”default” flag that can be set on the cartridge; the use of default flag will be explained in a later section of the document.

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.

• Composite and component cartridge versions:

  When you update a component of a composite cartridge, you do not always need to update the version of the composite cartridge as well.

  For example, if CompositeCartridge version 1.0 references ComponentCartridgeA version 1.0 and ComponentCartridgeB version 1.0, when you update ComponentCartridgeA to version 1.2, CompositeCartridge and ComponentCartridgeB can both remain at version 1.0.

• 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-ProductSpec version 2.0.0

  • OsmCentralOMExample-FulfillmentPattern 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.

Handling Revision Orders When Multiple Cartridge Versions Are Deployed

As a general rule of thumb, OSM always creates revision orders with the same cartridge version as the base order. This is with good reason – otherwise, generating and executing compensation can cause errors where entities are not available in the original cartridge version. The detection of order revision and the choosing of cartridge version are handled automatically by the OSM server.

For example, order 123 is created against cartridge A version 1.0 (which is the default version of cartridge A), and is currently in an In Progress state. Next, version 1.1 of cartridge A is deployed and is now the default version of the cartridge, and all new orders for cartridge A will be run against version 1.1. Then a revision for order 123 is submitted to the system. When OSM detects that this is a revision of order 123 using its built-in order key matching, it also sees that order 123 is running against version 1.0 of cartridge A, creates the revision order in version 1.0 of cartridge A as well, then proceeds with its delta analysis of the base order 123 and the revision and begins compensating.

This means that an original order and all subsequent revisions of the order will be created against the same cartridge version as the original order. There is no method to override this behavior.

With CreateOrderBySpec API, the submitter of the revision order is not required to know the cartridge version of the order that the revision will be acting on. With CreateOrder API, the matched ORR may specify an explicit Target Order Version or simply set it towards default version. Regardless of how the Target Order Version is set, the order revision always follows the cartridge version of the base order. Precisely speaking, the revision order auto-completes in the same cartridge version of the base order, and the base order will perform compensation according to its cartridge version.

Building and Packaging 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:

• From the Project menu, select Build.

  Oracle recommends that you periodically clean the project prior to a build (see "Cleaning and Rebuilding Cartridges Prior to Deployment".)

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

About Generating OSM Cartridges and Deployment Options

When you build OSM cartridges, Design Studio generates a portal archive (PAR) file for each cartridge, which is a ZIP file packaged to contain the metadata interpretable by the OSM run-time environment. This PAR file has the .par file extension, and is the artifact sent to the OSM server when deploying a cartridge. The name you choose for the cartridge becomes the name of the PAR file. Design Studio saves the PAR file to the cartridgeName/cartridgeBin directory, that you can view from the Java perspective Package Explorer.

Both the design-time project files in Design Studio and the deployable PAR file stored on the OSM run-time environment are referred to as cartridges. Often, the context of the discussion clarifies which artifact is being referred to.

You can deploy OSM cartridges using either of the following tools:

• Design Studio environment perspective: Typically, developers and testers managing their own run-time environments use Design Studio to deploy cartridges. Developers may perform build, deploy, and test cycles many times a day. You can deploying cartridges from Design Studio using the Studio Environment Perspective. See Design Studio Concepts for more information about deploying cartridges using the Design Studio environment perspective.

• Design Studio cartridge management tool (CMT): Oracle recommends CMT (packaged with Design Studio) for deploying cartridges to production, pre-production, or automated testing environments. The cartridge management tool is a set of ANT scripts for deploying and un-deploying cartridges to a run-time environment. Script-based deployment is important for run-time environments that are under strict operational control and require an automated, repeatable way to build, deploy and un-deploy cartridges. See Design Studio Developer's Guide for more information about CMT.

Both tools connect to the OSM server using the Cartridge Management Web Service (CMWS) deployed in WebLogic.

Note:

The XML Import/Export (XMLIE) application is a legacy client that can manage cartridges. It does not connect over CMWS. Do not use XMLIE for the purpose of deploying cartridges unless you are supporting an 6.x OSM implementation. See OSM System Administrator's Guide for more information about XMLIE.

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

• You can deploy different cartridges on different instances of OSM. For example, you can deploy a specific set of cartridges on an instance of OSM that is dedicated to central order management.

• 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.

• You can fulfill orders differently by using functionality deployed by different cartridges.

• You can fulfill orders differently based on functionality deployed by different versions of the same cartridge.

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

About Cartridge Types

You can create the following OSM cartridge types using Design Studio:

• Component cartridge: Component cartridges contain a part of the OSM model entities in an overall OSM solution. For example, some component cartridges may define OSM model entities for interacting with particular fulfillment systems, such as a shipping system, or a billing and revenue management system, or OSM system running in a different role. Other component cartridges may define data dictionaries common across OSS or BSS applications.

• Composite cartridge: Composite cartridges designate an OSM solution by referencing a collection of component cartridges. The composite cartridge does not contain any OSM model entities itself but acts as a container that includes the component cartridges it references. For this reason, composite cartridges are also called solution cartridges. When you deploy a composite cartridge, all the included component cartridges are also deployed, effectively deploying the entire OSM solution in a single action. Oracle recommends using composite cartridge to manage the component cartridges of an OSM implementation in the production environment. Composite cartridge projects may contain any number of component cartridges, but not other composite cartridges.

• Standalone cartridge: Standalone cartridges are component cartridges that are not part of a composite cartridge solution. Standalone cartridges can have dependencies to other standalone cartridges, but cannot be dependent on any component cartridge within a composite cartridge solution.

About Design Studio Editors for OSM Cartridges

Figure 16-9 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 16-9 Cartridge View of a Cartridge

Description of ''Figure 16-9 Cartridge View of a Cartridge''

Expand the cartridge in the Cartridge explorer pane (on the left in Figure 16-9) 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.

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

Figure 16-10 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 16-10 Package Explorer View of a Cartridge

Description of ''Figure 16-10 Package Explorer View of a Cartridge''

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 16-10.

After creating the cartridge, an immediate build of the project creates additional directories and files in the cartridge, as shown in Figure 16-11. 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 16-11 Package Explorer View of a Cartridge After a Build

Description of ''Figure 16-11 Package Explorer View of a Cartridge After a Build''

Note:

If working with automation plug-ins, the directories and files listed below are of importance, and are further explored in "About Automation Plug-ins":

• src directory

• src/automationBuild.xml

• Referenced Libraries/automation_plugins.jar

• cartridgeBin/cartridgeName.par

• customAutomation/automationMap.xsd

• customAutomation/databasePlugin.xsd

• resources directory

Organizing Design Studio and Naming Conventions

Oracle recommends that you determine a set of naming conventions for the Design Studio entities being created and a directory structure to contain those elements that is appropriate to your implementation. Following is an example set of naming conventions for selected configuration elements within Design Studio. However, each project team should determine what conventions are suitable for a particular project.

Table 16-1 Suggested Design Studio Naming Conventions

Metadata Element	Naming Convention	Sample
Order recognition rules	Use the convention of OrderTypeORR	SalesOrderORR ProvisioningOrderORR
Order item specifications	Use the convention of OrderItemTypeItemSpec	CentralOrderItemSpec
Fulfillment patterns	Use a name that indicates the fulfillment flow being supported. For example: PS_FulfillmentType_SpecType	PS_Service_Broadband
Fulfillment modes	Use names that clearly identify the type of action to be taken	DELIVER QUALIFY QUOTE
Order component specifications: Fulfillment actions	Use names that indicate the function of the fulfillment action; for example, Billing, or Shipping.	ResidentialBillingFunction EnterpriseBillingFunction ProvisioningFunction
Order component specifications: Fulfillment target systems	Use names that indicate the function of the target system; for example, Billing, or Shipping.	BillingSystem CRMSystem ServiceManagementSystem
Order component specifications: Processing Granularity	Use names that correspond to the order structure defined in the product catalog; for example, Item, Bundle, and Order.	ItemBased BundleBased OrderBased
Orchestration stages	Use names that describe the stages.	DetermineFulfillmentFunctionStage DetermineFulfillmentSystemStage DetermineProcessingGranularityStage
Orchestration sequences	Use the convention CartridgeNameSequence	SalesOrderFulfillmentSequence
Decomposition rules	Use the naming convention DR_FunctionName_To_SystemName for system decomposition rules Use the naming convention DR_DetermineGranularity_For_FunctionName for granularity decomposition rules	DR_BillingFunction_To_ResBRM DR_DetermineGranularity_For_BillingFunction

Cartridge Packaging Design

When you model OSM entities, you can define separate cartridges and combine them in a single solution. This allows you to create individual cartridges for specific purposes, and to create a library of cartridges which can be shared across multiple solutions. This approach can result in lower maintenance, better performance, and easier collaboration within the implementation team.

While each deployment has its own specific considerations, Oracle recommends that you consider the following guidelines:

• Build separate cartridges based on function. For example, build separate cartridges for COM, SOM, and TOM roles.

• Put configuration elements that are more commonly changed into a separate cartridge for ease of maintenance.

• If a component has distinct notification and status management requirements, use a separate cartridge and pass the data to this "sub-order" from the main order. For example, if the process of shipping a piece of equipment involves interactions with three to four systems and multiple notifications to other systems, consider creating a "Shipping order management cartridge" to handle this requirement.

• For a given cartridge, limit the total number of sub-processes and the number of tasks per sub-process for ease of maintenance. Consider limiting both to ten or fewer, although in some situations more might be required.

• Consider defining a cartridge which contains only a data dictionary with data nodes and structures that are specific to a technology or service or space. Other cartridges can then reference this data.

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.

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:

• OSM resolves a URI against a test server in a test environment and resolves that URI against a different server in a development environment.

• OSM resolves the location of files in a developer's local workspace to the location of equivalent files available to the OSM server at a generic URI. You might use XML Catalogs in this way for XQuery module import statements that at design time need to refer to files in your local workspace but at run time need to refer to files within the resources directory of a deployed cartridge.

• Your OSM model might reference a resource located on the Internet. If your server deployment runs behind a firewall with no Internet access, you can load the resource behind the firewall and use an XML Catalog to redirect the URI of the Internet location to the location of the resource behind the firewall.

For more information on XML Catalogs and valid XML Catalog entries, see the OASIS web page:

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

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:

• Specified in your OSM cartridge projects

  XML Catalogs specified in your OSM cartridge projects are packaged as part of the cartridges and deployed to the OSM server. The XML Catalog manages only the resource files in the resources folder of your cartridge project. When you deploy a cartridge with XML Catalog support enabled, the contents of the resources folder are loaded into a virtual file system. Those resources are available through URI redirection to any other deployed cartridges. XML Catalogs can be defined in any cartridge, and those defined in one cartridge can reference resources in other cartridges. All of the XML Catalogs deployed on the OSM server are stored in memory and rebuilt each time the metadata refreshes. If there are conflicting XML Catalog entries, the latest entry loaded overwrites the earlier entry. See "Defining rewriteURI Entries in XML Catalogs" for information on how to avoid conflicting entries.

• Specified on the OSM server

  XML Catalogs specified on the OSM server are defined in the oms-config.xml file and are loaded ahead of the XML Catalogs specified in OSM cartridge projects. XML Catalogs defined on the server are global in scope, applying to all cartridges. XML Catalogs specified on the OSM server override the URI mapping of XML Catalogs in cartridge projects. URIs mapped in oms-config.xml are resolved for each specific environment. For example, a cartridge developer can specify an XML Catalog in oms-config.xml to point certain URIs defined in the data model to her own local Design Studio workspace, allowing her to change the contents of the resources locally and test the changes without having to redeploy the entire cartridge. Because OSM uses XML Catalogs that are specified on the OSM server to resolve URIs to be environment specific, XML Catalogs specified in OSM cartridge projects should not reference URI locations that are environment specific (such as drive letters).

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

• Automation logic: You can configure XQuery and XSLT automators with the XML Catalog to specify the XQuery/XSLT file that drives the automation logic.

• Data from a data provider: A data instance provider can use the XML Catalog to specify a resource for providing the data loaded by the provider.

• Order item properties (for orchestration orders): Order item properties can be configured to be loaded through a URI locator. You can configure the XML Catalog to redirect the URI to specify the XQuery file that implements determining the property value.

• Decomposition rules (for orchestration orders): Decomposition rules can be configured to be loaded through a URI locator. You can configure the XML Catalog to redirect the URI to specify the XQuery file that implements determining the decomposition condition.

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 16-12 shows the Expression, File, and URI options in the XQuery tab of a Design Studio editor:

Figure 16-12 URI Option for Defining Resource Properties

Description of ''Figure 16-12 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

• Using XML Catalogs to Load Resources from a Development File System

• Using XML Catalogs to Insulate Run-Time Environments from Development

Using XML Catalogs to Support Cartridge Versioning

Cartridge versioning requires multiple versions of cartridges to reference their own versioned set of resources. For example, if you have version 1.0 and version 2.0 of an OSM cartridge deployed, you might have version-specific XQuery or JAR files that need to be used depending on which cartridge you are using. XML Catalogs ensure that the cartridges reference the correct resources.

To use XML Catalogs to support cartridge versioning:

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

   For more information about model variables, see the Design Studio Help.

2. In the parts of your model where you need OSM to substitute the version number, use %{CARTRIDGE_VERSION}. For example:

    http://company.com/%{CARTRIDGE_VERSION}/xquery/myFile.xqy
   

3. In the XML Catalog, define the rewriteURI entries as follows:

   • If the cartridge is a component of a composite cartridge, use the CARTRIDGE_VERSION model variable. For example:

     <rewriteURI uriStartString="http://company.com/%{CARTRIDGE_VERSION}" rewritePrefix="osmmodel:///MyCartridge-Resources/%{CARTRIDGE_VERSION}/resources"/>
     

   • If the cartridge is not a component of a composite cartridge, use the specific cartridge version number. Do not use a model variable. For example:

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

   When you deploy the cartridge, OSM replaces all instances of %{CARTRDIGE_VERSION} with the value that you set on the cartridge editor Model Variables tab.

4. When you create a new version of a cartridge, update the CARTRIDGE_VERSION model variable with the new version number.

5. In the XML Catalog, update the rewriteURI entries as follows:

   • If the cartridge is a component of a composite cartridge, no further updates are required. Because you used the model variable in the rewriteURI entries, OSM automatically replaces the model variable with the new version number when you deploy the cartridge.

   • If the cartridge is not a component of a composite cartridge, update the cartridge version number in each rewriteURI. For example:

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

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.

Cartridge Deployment

Design Studio allows you to deploy cartridges to an OSM environment. For more information about creating environment entities and deploying cartridges, see the topic about deploying cartridge projects in Design Studio Help.

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 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 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 Order Management web client or with an Ant refresh

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

Table 16-2 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".