Managing OSM Solution Cartridges

15 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 computer 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 15-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 15-1 Cartridge Portability in Development, Test, and Production Systems

Description of "Figure 15-1 Cartridge Portability in Development, Test, and Production Systems"

About OSM Cartridge Scope

Cartridge scope refers to which entities an OSM order has access to. If a particular OSM entity is considered in scope for an order, that entity can be used to influence how that order is processed.

The scoping mechanism of OSM has evolved over the years. For information about the history of scoping in different releases of OSM, see knowledge article 2077384.1, Cartridge Management and Versioning, on the Oracle support website:

https://support.oracle.com

Scope of OSM Entities Without Namespaces

Some OSM entities, such as orders, processes, tasks, composite cartridge views, and resource files, do not have namespaces defined for them.

Design Studio Entities

Design Studio entities that do not have namespaces have visibility only to other entities contained within the same cartridge. At run time, they cannot be referenced by an entity that resides in another cartridge or another version of the same cartridge.

However, at design time (in Design Studio), you can reference entities across cartridges even if those entities do not have namespaces. For example, when designing a process flow, you can include a task from another cartridge. When you do this, Design Studio includes the referenced entity in the cartridge when it is built, so that it will be available at run time.

XML Catalogs and Resource Files

In addition to specific entities in Design studio, an OSM implementation typically contains other resource files in the cartridges. XQuery and XSLT files are the most common types of resource files, but there can also be other types of files such as Java files or other XML configuration files. In addition, there my be XML catalog files. The scoping of these resource files is the same as with other entities that do not have namespaces:

For standalone cartridges, the resource entities belong to a local or global pool, depending on the configuration of the FullScopeAccess parameter in the oms-config.xml file. For more information about this setting, see "Standalone Cartridge Scope."
For solutions using composite cartridges, the scope of resource files is defined by the contents of the composite cartridge.

Scope of OSM Entities with Namespaces

For orchestration entities such as order component specifications, order item specifications, and order recognition rules, there is an explicit namespace attribute that you can specify in Design Studio.

Entities with namespaces 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

Figure 15-2 is a simple example of how an entity with a namespace is referenced by another entity. Referencing by fully qualified name occurs automatically when the cartridges are packaged at build time, as long as you provide appropriate entity namespace values in Design Studio.

Figure 15-2 Referencing an Orchestration Entity by Fully Qualified Name

Description of "Figure 15-2 Referencing an Orchestration Entity by Fully Qualified Name"

The cartridge name (OsmCentralOMExample-Topology) is not part of the fully qualified name. Entities can freely reference entities of other cartridges as long as the fully qualified name is unique in the run-time environment.

Standalone Cartridge Scope

Scope considerations are different depending on whether your cartridges are standalone or grouped using composite cartridges. For more information about the different cartridge types, see "About Cartridge Types."

OSM builds a resource pool for each cartridge that contains an order when it is loaded. The contents of this pool are determined by the oracle.communications.ordermanagement.resource.FullScopeAccess parameter in the oms-config.xml file. By default, this parameter is set to restrict the resource pool to only the resources in the cartridge. You can also set it to enable either all cartridges or specific cartridges to access all of the resources in your solution. For more information about this parameter, see the discussion of oms-config.xml in OSM System Administrator's Guide, or see knowledge article 1568944.1, Cartridge Resources Not Picked Up Correctly for Multiple Cartridge Versions, on the Oracle support website.

For cartridges that have access to all resources, resources in this pool are accessed according to three levels of priority:

Resources in the local cartridge version
Resources in other cartridge versions with the same cartridge namespace (with no determined order between versions)
Resources in all other cartridges (again, with no determined order)

The different access priorities in the pool mean that it is more likely that the OSM server will find the correct copy of an entity with a namespace, but does not completely eliminate the potential for namespace collisions.

XML Catalog Files in Standalone Cartridges

If you are using standalone cartridges, it is important to locate the XML catalog files in the same cartridge as the entities that call them, or the wrong file can be picked up, meaning that the wrong namespace translation will take place, and therefore the wrong resources will be selected.

Avoiding Namespace Collisions for Design Studio Entities

A namespace collision may occur when multiple entities with namespaces have the same fully qualified name in a run-time environment. This is not unusual when multiple versions of the same cartridge are deployed. For example, in Figure 15-3, the TargetSystem order component has the same fully qualified name in both versions 1.0 and 1.1.

Figure 15-3 Namespace Collision of an Orchestration Entity

Description of "Figure 15-3 Namespace Collision of an Orchestration Entity"

In the event of namespace collision, it is not possible to predict which version will be used. In the example, it is unknown whether version 1.0 or 1.1 of TargetSystem will be loaded by OSM, but both versions 1.0 and 1.1 of the OsmCentralOMExample-Orchestration cartridge will use the same version of TargetSystem, which means one of them is using the wrong version.

To avoid namespace collision across cartridge versions, you can include the cartridge version in the entity namespace. In the example above, the namespace can be specified as http://oracle.centralom.topology/1.0.0.0.0. The best way to do this is using an XML catalog, which you can use to translate the namespaces of entities so that they include the cartridge version. See "Using XML Catalogs to Support Cartridge Versioning" for details.

Avoiding Namespace Collisions for Resource and XML Catalog Files

In the same way as for other entities without namespaces, if you are using standalone cartridges, it is possible for your solution to reference an unintended version of a resource file when multiple cartridge versions exist. You can avoid this problem for XQuery files if you locate them using a URI that is mapped to a cartridge-version specific location using the XML Catalog.

Figure 15-4 contains an example where the OsmCentralOMExample-Orchestration cartridge references an XQuery file located in a centralized resource cartridge OsmCentralOsmResources, and that two versions, 1.0 and 1.1, have been deployed:

Figure 15-4 XML Catalog Conflict

Description of "Figure 15-4 XML Catalog Conflict"

If the XQuery file is referenced using a URI like the following:

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

and the XML Catalog for cartridge version 1.0 has a rewriteURI entry like this:

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

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

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

then there is no ambiguity when locating the XQuery file. Entities in the OsmCentralOMExample-Orchestration cartridge version 1.0 will find the XQuery resource in version 1.0 of the OsmCentralOsmResources cartridge, because the URI of the XQuery file will be resolved to:

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

Composite Cartridge Scope

A composite cartridge is a special type of cartridge that does not directly contain any OSM entities at design-time. Instead, it contains references to other cartridges (referred to as component cartridges) that make up an OSM service or solution. The composite cartridge has its own 5-segment version number that you can manage, and contains a list of component cartridges that make up the composite cartridge. For more information about composite cartridges, see Design Studio Modeling OSM Orchestration Help. Oracle recommends that you use composite cartridges in your solution, as they help reduce versioning problems and namespace collisions.

The composite cartridge provides solution-level scoping boundaries that are appropriate for running concurrent cartridge versions of an OSM implementation. When the composite cartridge is built, all of the entities without namespaces from the component cartridges are aggregated to become one new deployable cartridge. This run-time cartridge has a namespace that is the name of the composite cartridge. However, all of the entities with namespaces are built into their respective component cartridges as usual.

For XML catalog files in composite cartridges, unlike in standalone cartridges, it is only necessary to ensure that the XML catalog is located somewhere with the scope of the composite cartridge to ensure that the correct version will be used.

Figure 15-5 is an 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 15-5 The Use of Composite Cartridges in Design Time and Run Time

Description of "Figure 15-5 The Use of Composite Cartridges in Design Time and Run Time"

In this example, a run-time cartridge named COMExample-Soln is generated to contain all of the entities without namespaces, such as orders, processes and tasks. The component cartridges, COMExample-Base and COMExample-Billing, still contain their entities with namespaces. When the composite cartridge is deployed, all of the design-time component cartridges and the generated component cartridge are deployed to the run-time environment. When an incoming order is handled by an order entity in this composite cartridge version, it is given the namespace of the generated cartridge, which is the name of the composite cartridge, COMExample-Soln.

Because all of the entities without namespaces are aggregated into a single cartridge, there is no ambiguity about which entity is referenced. Even if multiple versions of the cartridge are present in OSM, only one version of the cartridge would be included in the composite cartridge. In our example, if cartridge COMExample-Billing version 1.0 and 1.1 are deployed, the BillingFunctionTask task from the COMExample-Billing cartridge version 1.0 will be used by orders that are tied to COMExample-Soln version 1.0, since the order and the task are now confined to a single cartridge and version.

Composite cartridges also address the problem of namespace collision for entities with namespaces. The composite cartridge establishes a manifest that explicitly specifies the component cartridge version whenever an entity dependency is established across cartridges in the solution. Entities and resource files in the component cartridge version are confined to the OSM solution defined by the composite cartridge. So, in the example, if the COMExample-Billing version 1.0 and 1.1 cartridges are both deployed, orders tied to COMExample-Soln 1.0 will use entities from version 1.0 of COMExample-Billing instead of version 1.1, even when the same fully qualified name exists in both, because the. This means that, when you use composite cartridges, you do not need to include the cartridge version in the namespace of entities to avoid namespace collisions.

Special Cases for Scope

Some entities are special cases with regards to scope. First, there is the order recognition rule. Since the order recognition rule is evaluated before the order is selected, its scope cannot be based on the cartridge in which it is located. Also there is the fulfillment pattern, which works differently because the namespace used is based on the order item.

Order Recognition Rules

Order recognition rules (ORRs) are a special case for scoping. When the CreateOrder API is called, OSM does not know the version or namespace of the incoming order. The purpose of ORRs is to be able to determine the kind of order contained in an inbound message. Even though an ORR has a namespace field, its scope is system-wide: all ORRs in the OSM run-time environment are used to recognize the contents of the CreateOrder message, regardless of which cartridge contains the ORR. This is true for ORRs regardless of whether they are in standalone cartridges or component cartridges 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, there is a non-namespace way to configure which ORR will pick up new orders of the relevant type. The Relevancy setting in Design Studio determines the order in which the ORRs are evaluated. OSM will run ORRs on an inbound message from highest to lowest relevancy until an ORR recognizes the order. If two ORRs have the same relevancy, it is not predictable which one will be evaluated first. Once an ORR is matched, the incoming order is tied to the target order type (and thus its cartridge namespace) that the ORR designates, and further rules are not evaluated.

Fulfillment Patterns

Fulfillment patterns are responsible for determining the fulfillment of an order item in the generated orchestration plan. Fulfillment patterns have a namespace. However, finding the fulfillment pattern of an order item is a unique case in scoping. In Design Studio, the order item is mapped to a fulfillment pattern using the value in the Fulfillment Pattern Mapping Property field, which contains a string to map to a fulfillment pattern name. OSM finds the Fulfillment Pattern by fully qualified name (not just the string contained in the property field), using the namespace of the order item to determine what namespace to look for in a fulfillment pattern. Because of this, it is important to use the same namespace for both order items and their related fulfillment patterns in your OSM solution. Otherwise, OSM cannot find the fulfillment patterns for the order items.

Fulfillment Patterns in Standalone Cartridges

In the same way that there can be scoping issues with regular entities in standalone cartridges, there can be scoping issues for fulfillment patterns as well. The example depicted in Figure 15-6 shows what happens if the version number is not included in the namespace of an order item in a standalone cartridges. The COMExample-FulfillPattern version 1.0 cartridge contains the Service.Broadband, Service.Fixed, and Service.Mobile fulfillment patterns. The COMExample-FulfillPattern version 2.0 cartridge introduces the new Service.VOIP fulfillment pattern as well as making changes to existing fulfillment patterns. If the namespaces do not contain cartridge versions, finding Service.Broadband results in matching whichever of the fulfillment patterns was in the version of the cartridge that happens to have been deployed most recently. This results in unpredictable behavior in orchestration plan generation.

Figure 15-6 Fulfillment Patterns in Standalone Cartridges

Description of "Figure 15-6 Fulfillment Patterns in Standalone Cartridges"

Fulfillment Patterns with Composite Cartridges

In contrast, with the use of composite cartridges, OSM matches only fulfillment patterns that are encapsulated in the same composite cartridge. In the example in Figure 15-7, for orders in cartridge version 1.0, only Service.Broadband in COMExample-FulfillPattern1.0 is matched.

Figure 15-7 Fulfillment Patterns Encapsulated in Composite Cartridges

Description of "Figure 15-7 Fulfillment Patterns Encapsulated in Composite Cartridges"

Managing Cartridge Versions

To distinguish changes in a cartridge over time, each cartridge has a cartridge version. 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. The longer the order lifetime is, the greater the likelihood that you will need multiple cartridge versions deployed at the same time.

Changes can be made to cartridges for different reasons, including fixing implementation details and enhancing the cartridge to meet new requirements. Often, the changes that need to be made in a cartridge are not compatible with the way the cartridge currently works, or may be disruptive to the in-progress orders that are running in the current version of the cartridge. This is the primary reason to introduce a new version: deploying a new version of a cartridge allows new orders to use the new cartridge, while in-flight orders can continue without disruption using the version of the cartridge that they started with.

One consideration to keep in mind when planning solution maintenance is the order lifetime. 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, and so on.

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 run-time system, then order 123 will continue to run to completion using cartridge A version 1. This is also true for existing future-dated orders for cartridge A version 1even if the start date has not arrived.

Making Changes to Existing Cartridge Versions

If you have very short-lived orders, it is possible to avoid having different versions of cartridges at the same time, by deploying changes to the cartridges without changing the version. To do this without breaking existing orders, a possible strategy is to allow OSM to complete the fulfillment of all orders, followed by an order purge operation that removes them from the environment (since, once the new cartridge is deployed, OSM may not be able to understand the old orders). However, there are several drawbacks to this strategy:

It does not allow you to keep completed orders in the system for troubleshooting, auditing, and reporting purposes.
It limits your implementation's ability to handle inter-order dependencies, because you cannot guarantee that the parent orders are still in the system.
There are also operational complications that can arise, because there will be some orders that take longer to complete than others, and there may be order fallout that needs to be handled. This would mean that at least some order fallout would need to be handled outside of OSM, rather than managing it using the order fallout capabilities of OSM.

Aside from the scenario mentioned above, where you have only very short-lived orders, you should always plan to use cartridge versioning in your production environment.

However, even if you are using cartridge versioning in your solution, you do not need to introduce a new cartridge version every time you make a change. There are cases where it is better to make changes to an existing cartridge version and redeploy it, instead of creating a new cartridge version, such as:

If you have critical bug fixes that should affect existing orders, and the fixes would not make the cartridge incompatible with existing orders, it may make sense to deploy the fix to the same cartridge version that causes the problem.
If you have changes need to become effective immediately, applying to existing in-progress orders, you may want to deploy the changes in the existing cartridge version. For example, if there is an interface change in a downstream system, and it no longer supports the original version of the interface, that would require OSM to adapt to the new interface across all cartridge versions.

Generally speaking, the longer that orders take to complete, the more business pressure there is to make changes that existing orders can use.

When when you need to make changes to existing cartridge versions, it is important that you ensure that all in-progress orders can continue to be executed against the cartridge after the changes are made. For technical and best practice guidance towards safely making changes to existing cartridge versions, see knowledge article 2077384.1, Cartridge Management and Versioning, on the Oracle support website.

Making changes to existing cartridge versions is inherently risky, and so adequate test coverage is an essential part of the process, to ensure that all in-progress order scenarios are not impacted (for example, do not stop processing) by the changes to the cartridges.

In general, it is important to minimize the number of cartridge versions that you introduce for performance reasons. See the discussion of cartridge management strategy in OSM System Administrator's Guide for more information about removing old versions of cartridges when they are no longer necessary.

Handling Multiple Cartridge Versions

The Cartridge and Composite Cartridge editors in Design Studio contain several fields that make up the version number. There are five fields that you set to indicate the version of a cartridge: Major Version Number, Minor Version Number, Maintenance Pack, Generic Patch, and Customer Patch. These constitute a 5-digit version number, for example, 1.0.0.0.0. In addition to the cartridge version, there is a read-only Build Number field that is automatically incremented by Design Studio each time a cartridge is built. It is not reset when the cartridge version is changed.

To deploy a new cartridge version, change the value of the version fields and deploy the cartridge. Multiple cartridge versions can be deployed in an OSM environment at the same time, with orders running against each version.

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 when implementing multiple cartridge versions:

The DEFAULT_CARTRIDGE cartridge management variable:

Ideally, 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.0.0 and 2.0.0.0.0 of an OSM cartridge deployed, only one of them should be set as default. For more information, see "Designation of the Default Cartridge Among Cartridge Versions."
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, the composite cartridge and ComponentCartridgeB can both remain at version 1.0.
Cartridge versioning using the XML Catalog:

In standalone cartridges, the 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.0.0" in the following:
```
<rewriteURI uriStartString="http://example.com/" rewritePrefix="osmmodel:///MyCartridge-Resources/1.0.0.0.0/resources"/>
```
the version-specific portion of the rewriteURI entry 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, OSM uses the JMSCorrelationID to ensure that the message is consumed by the correct receiver, as long as the external automation receiver is named using the format taskName.automatorName, and there is only one external automation receiver associated with the task.

If your receiver does not have the name format taskName.automatorName, or there is more than one external automation receiver associated with the task, the message listening filter criteria of your automation plug-in must guarantee not to pick up a message that should have been picked up by another cartridge version. This may happen if, for example, your system has asynchronous interaction with an external system that takes days to fulfill your request and you have modeled the correlated response to return to a different task than the one that sent the message, or it might happen if you have an old (pre-OSM 7.0.3.1) cartridge that you have not updated.

See "Properties View External Event Receiver Tab" in Modeling OSM Processes for the External Event Receiver sub-tab of the properties view in the automated task editor Automation tab for more information.
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.

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, you might have version 1.0.0.0.0 of the OsmCentralOMExample-Solution composite cartridge with the following dependent cartridges:
- OsmCentralOMExample-Orchestration version 1.2.0.0.0 – OsmCentralOMExampleOrder is defined here
- OsmCentralOMExample-ProductSpec version 2.0.0.0.0
- OsmCentralOMExample-FulfillmentPattern version 2.0.0.0.0
- OsmCentralOMExample-Topology version 1.1.0.0.0
The target order version of the order recognition rule should be set to 1.0.0.0.0, because that is the version of the composite cartridge.

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.

It is possible to mimic migrating orders to a new cartridge version 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 various external systems before the order is resubmitted, or the flow itself to be configured so that past activities can be repeated without needing to be undone (for example, so that you can resend a message to a downstream system without having to undo any previous commands). This is not a recommended option, but can be a possibility, depending on the specifics of your OSM implementation.

Designation of the Default Cartridge Among Cartridge Versions

If there are multiple versions of the same cartridge deployed, you must designate which version is to be used for to an inbound order. It is possible (but not required) to specify the cartridge version in the CreateOrderbySpec request. In the CreateOrder request, the target version cannot be specified as input parameter, but can optionally be defined by the matched ORR. Alternatively, you can configure the ORR to use the default version of the cartridge. In any case, there must be a way to determine which version of the cartridge should handle the order if the cartridge version is not defined on the order or set by the order recognition rule.

For standalone cartridges, the default designation is configured using the DEFAULT_CARTRIDGE cartridge management variable. This variable should be set to true for the version that should handle new orders, typically 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 run-time 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 is set in the same way, only it is set on the composite cartridge. When the DEFAULT_CARTRIDGE cartridge management variable is set to true, all the composite cartridge's component cartridges are considered the default versions. The default settings of the component cartridges do not have an effect, only the setting of the composite cartridge.

For both standalone and composite cartridges, the OSM server always recognizes exactly one version as the default for each cartridge namespace. When multiple cartridge versions are deployed that have the default flag set to true, the OSM run-time environment will make the last deployed of these versions the default cartridge. Because of this, special attention is required when redeploying an old cartridge version. When you create a new cartridge or composite cartridge in OSM, by default, the DEFAULT_CARTRIDGE cartridge management variable is set to true. When you deploy the versions in numeric order, the latest version will be the default. However, if you redeploy an earlier version after a later version, you must ensure that you have set the DEFAULT_CARTRIDGE cartridge management variable to false for that earlier version. There is no warning in Design Studio or on the run-time server that there is an older version of a cartridge being deployed as the default, so you must take care to set the value properly.

Handling Revision Orders When Multiple Cartridge Versions Are Deployed

OSM always creates revision orders with the same cartridge version as the base order. This is because otherwise, generating and executing compensation can cause errors because entities in the new version 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, 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, and that order 123 is running against version 1.0 of cartridge A, it creates the revision order for version 1.0 of cartridge A, then proceeds with the amendment process.

This means that all subsequent revisions of the order will be created against the same cartridge version as the original order. There is no way to override this behavior. Regardless of any information set on the order or by the ORR, revision orders will use the same cartridge version as the original order.

Working with Cartridges in OSM Cloud Native

For cartridge considerations in an OSM cloud native environment, see "Preparing Cartridges for OSM Cloud Native" in OSM Cloud Native Deployment Guide.

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 "Packaging and Deploying OSM Cartridges" in Modeling OSM Processes.

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 deploy 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) (Traditional OSM Only): 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.
OSM DB Installer: OSM cloud native uses a different mechanism for deploying cartridges. See "Deploying Cartridges Using the OSM DB Installer" in OSM Cloud Native Deployment Guide for more details.

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 to deploy cartridges unless you are supporting an OSM 6.x 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 "Packaging and Deploying OSM Cartridges" in Modeling OSM Processes.

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 15-8 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 15-8 Cartridge View of a Cartridge

Description of "Figure 15-8 Cartridge View of a Cartridge"

Expand the cartridge in the Cartridge explorer pane (on the left in Figure 15-8) 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 15-9 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 15-9 Package Explorer View of a Cartridge

Description of "Figure 15-9 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 15-9.

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

Description of "Figure 15-10 Package Explorer View of a Cartridge After a Build"

Note:

If working with automation plug-ins, the directories and files listed below are important:

src directory
Referenced Libraries/automation_plugins.jar
cartridgeBin/cartridgeName.par
customAutomation/automationMap.xsd
customAutomation/databasePlugin.xsd
resources directory

For more information, see "About Automation Plug-ins."

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 15-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 file for each cartridge is:

CartridgeName/src/build.xml

The CartridgeName/src/build.xml file can be customized to add files to the lib directory. 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 15-11 shows the Expression, File, and URI options in the XQuery tab of a Design Studio editor:

Figure 15-11 URI Option for Defining Resource Properties

Description of "Figure 15-11 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.

Caution:

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

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:

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.
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.
Note:

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.
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 "Enabling and Disabling XML Catalogs for a Cartridge Project" in Modeling OSM Processes.

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 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:

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 "Working with Model Variables" in Modeling Basics.
In the parts of your model where you need OSM to substitute the version number, use %{CARTRIDGE_VERSION}. For example:
```
 http://example.com/%{CARTRIDGE_VERSION}/xquery/myFile.xqy
```
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://example.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://example.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.
When you create a new version of a cartridge, update the CARTRIDGE_VERSION model variable with the new version number.
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://example.com/1.5" rewritePrefix="osmmodel:///MyCartridge-Resources/1.5/resources"/>
```

Using XML Catalogs to Load Resources from a Development File System (Traditional OSM Only)

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:

In the Package Explorer view in Design Studio, navigate to the cartridgeProject/xmlCatalogs/core/ directory.
Create or edit the catalog.xml file. You can create the file by renaming a copy of xmlCatalogCoreTemplate.xml.
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 (not applicable for OSM cloud native). 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 systems. 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 "Deploying Cartridge Projects" in Modeling Basics.

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 "Managing Changes to Deployed Cartridges" in Modeling OSM Processes.

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. For more information, 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 depends and copies the information 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 depends on CartridgeB and CartridgeB is depends on 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.

Deploying Cartridges to the OSM Database Using XMLIE

You can deploy cartridges to the OSM DB directly using XMLIE. This approach is strongly recommended for controlled environments such as production, pre-production or UAT, and for environments managed using a CI/CD pipeline. It is also the preferred approach for semi-formal environments, such as test systems.

Offline Cartridge Deployment

You can deploy cartridges to the OSM DB directly using XMLIE while OSM is shut down.

To deploy a cartridge in offline mode using XMLIE:

Ensure that all managed servers are stopped. Shutting down the admin server is optional. See OSM System Administrator's Guide for details on stopping managed servers.
Build the cartridge PAR file using Design Studio.
Do the following to deploy the cartridge PAR file with XMLIE:
1. Change the directory to the directory where XMLIE is installed. For example, cd /opt/osm_sdk/SDK/XMLImportExport.
2. Copy the config_sample.xml file located at $XMLImportExport/config to the config.xml file and edit it to specify the OSM DB schema connection information.
3. Run the EncryptPasswords.sh script to encrypt the password of the OSM DB schema.
```
./EncryptPasswords.sh config.xml -dbUser
```
4. Run the import.sh XMLIE script to deploy the cartridge PAR file:
```
./import.sh $cartridge.par config.xml
```
Deploy all the cartridges using the same approach and then start the servers.

Note:

For a solution cartridge, the solution PAR file already contains all the PAR files of the components of the cartridges. Deploy only the solution PAR file. Do not deploy PAR files of the individual components.

Online Cartridge Deployment

You can deploy cartridges to your OSM running instance while orders from a cartridge that you deployed earlier are still being processed. When you deploy cartridges in online mode, OSM availability is uninterrupted and ongoing orders continue to react to new incoming messages. This is achieved by shutting down and restarting the OSM managed servers sequentially. OSM leverages WebLogic Zero Downtime Patching to deploy cartridges without any loss of service.

Online cartridge deployment is built on top of WebLogic's Zero Downtime framework. This framework imposes certain pre-requisites:

WebLogic Node Manager must be configured and running on all the hosts where OSM servers exist (configured during domain creation).
"Machines" must be configured in the WebLogic domain, and hosts must be assigned to these machines during domain creation.
The Proxy Server (if used) and Managed Servers must be started with Node Manager, not via other mechanisms such as scripts. The Admin Server should also be started via Node Manager.
Admin Server cannot run on the same host as any Managed Server.

For complete control, ensure that each machine runs exactly one managed server. While it is possible to assign two or more managed servers to the same machine, it affects the overall availability of OSM as all managed servers on a given machine undergo maintenance at the same time.

The OSM cluster must have at least two functioning managed servers for online cartridge deployment to work.

The following cartridge deployment operations are supported in an online deployment mode:

Deployment of the first version of a new cartridge
Deployment of a new (updated) version of an existing cartridge

Note:

To redeploy an existing version of a cartridge, use the regular deployment mechanism via Design Studio. You can also use the Cartridge Management Tool (CMT) to redeploy an existing version of a cartridge.

During the deployment process, the cluster is reduced by one managed server (the one that is actively restarting), while at least one other managed server (the one that just finished restart) is still warming up to full capacity. To avoid transient resourcing issues, it is strongly recommended to perform online cartridge deployment during a low order volume period. The processing of in-progress orders with undelivered incoming messages is paused while the operating managed server undergoes a restart. The processing of the in-progress orders resumes automatically once the restart of that managed server is complete. The processing of in-progress orders without undelivered incoming messages is not interrupted.

To deploy cartridges while OSM is still running:

Deploy each cartridge PAR file that needs to be added to OSM. Also, fast-undeploy each cartridge version that needs to be removed.
To deploy a cartridge PAR file:
1. Change the directory to the directory where XMLIE is installed. For example, cd /opt/osm_sdk/SDK/XMLImportExport.
2. Copy the config_sample.xml file located at $XMLImportExport/config to the config.xml file and edit it to specify the OSM DB schema connection information.
3. Run the EncryptPasswords.sh script to encrypt the password of the OSM DB schema.
```
./EncryptPasswords.sh config.xml -dbUser
```
4. Run the import.sh XMLIE script to deploy the cartridge PAR file in online mode:
```
./import.sh $cartridge.par config.xml online
```
Note:
For a solution cartridge, the solution PAR file already contains all the PAR files of the components of the cartridges. Deploy only the solution PAR file. Do not deploy PAR files of the individual components.
Perform rolling restart of the managed servers using WebLogic Admin Console or WLST.

About Performing a Rolling Restart of Managed Servers

After running the XMLIE script to deploy the cartridge, you must restart all the managed servers in the OSM cluster in a sequence. The completion of the restart of one managed server should trigger the restart commencement of the next. The WebLogic Zero Downtime Rolling Restart capability (part of the Zero Downtime Patching functionality) provides this mechanism for online cartridge deployment. This rolling restart can be triggered and monitored either using the WebLogic Console or using WLST.

For details on how to configure the rolling restart workflow, see Oracle Fusion Middleware Administering Zero Downtime Patching Workflows available at: https://www.oracle.com/pls/topic/lookup?ctx=en/middleware/fusion-middleware/weblogic-server/12.2.1.4&id=WLZDT108.

While configuring rolling restart in WebLogic Admin Console, specify the value for Shutdown Timeout to 120. This is the grace period for orderly shutdown. Tune this timeout value to ensure that your managed servers can shutdown gracefully. In general, the more activity on the server, the longer it takes to shutdown. Monitor how long it takes for your managed server to shutdown normally and use that as the basis for this setting. For instructions about performing rolling restart, see Oracle Fusion Middleware Administration Console Online Help for Oracle WebLogic Server 12.2.1.4.0.

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 "Managing Project Dependencies" in Modeling Basics.

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 15-2 lists the orchestration entities that are currently validated.

Table 15-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."