2 Modeling Orders and Permissions

This chapter describes how to model orders and permissions in an Oracle Communications Order and Service Management (OSM) solution.

Modeling OSM Orders

The order specification is the cornerstone model entity in Oracle Communications Design Studio; most other specifications among cartridges are tied, directly or indirectly, to the order specification to control order execution. Figure 2-1 shows the entities that relate to an order specification and the content you can configure in order specifications.

Figure 2-1 Order Specification Configuration and Related Entities

Description of "Figure 2-1 Order Specification Configuration and Related Entities"

In the order specifications you can define:

• The order template, which specifies the elements and structures of the order data that OSM receives from incoming orders and from other fulfillment systems.

• Order priority in conjunction with the priority defined on an order as detected by the order recognition rule. See "Modeling Order Recognition" for more information about order priority.

• Various order-level notifications. See "Modeling Jeopardy and Notifications" for more information about notifications you can configure in the order specification.

• Whether the order is amendable. See "Modeling Changes to Orders" for more information.

• Fallout data and fallout groups that define data and groupings of data that can potentially trigger a fallout exception on tasks that are associated with the fallout data or data groups. Fallout exceptions trigger amendment processing. See "About Modeling Fallout Exceptions" for more information.

• Permissions that associating roles to query tasks. Query tasks define what data can be displayed to a user associated with a specific role (whether a human user or a user account associated to automated tasks). See "Modeling Roles and Setting Permissions" for more information.

• Rules that to determine when notifications should run, when various process flow decisions or actions should occur, within decomposition rule to determine when order items should decompose to an order component, and so on. You can use rules in various OSM entities.

In the order specification, you must do the following:

• You must designate creation task data that defines the internal OSM order data, elements and structures that OSM generates as part of order processing (such as control data that OSM uses to generate orchestration plans), and any elements and structures generated by external fulfillment systems in response to messages from OSM. A creation task is a manual task that is not part of a process flow where you define data elements and structures in the Task Data tab.

• You must designate an order life-cycle policy that the order uses to determine valid states and state transitions for the order. Order states define sequential states through which an order passes and the transactions it undergoes from the time it is received in OSM until the time it is completed. For example, an order can be in progress, not started, suspended, and so on. You can enable multiple states in the order life-cycle policy and define what transitions can occur between states. For example, you can configure an order to be able to transition from in progress to cancelled. For more information about order life-cycle policies, see "Modeling Order Life-Cycle Policies".

• You must define whether OSM triggers an orchestration process or a standard process. An orchestration process causes OSM to generate an orchestration plan. An orchestration plan orchestrates order items into order components that trigger a series of standard processes. Most OSM orders require orchestration.

You can use the following OSM Web Service operations to submit orders:

• CreateOrderBySpec In this operation, you must specify the cartridge and order type so that OSM understands which Order entity to use to process the order. Also, the incoming order payload has to be in XML format as defined in the cartridge.

• CreateOrder This operation accepts arbitrary payload in XML for the incoming order. You specify an order recognition rule to recognize the payload, and transform it to the format as defined in the cartridge. There is no need to specify the cartridge or order type in the operation.

  The target order specification runs if the CreateOrder request includes the StartOrder=true parameter and value in the order header.

See OSM Developer's Guide for more information about CreateOrderBySpec and CreateOrder.

With either operation, when the order is created in OSM, it is tied to the order type in the cartridge. OSM relies on that cartridge and any the dependent cartridges to determine how to display and execute the order. This means, as long as the order resides in the OSM server and is not purged, the cartridges must remain in the run-time OSM environment.

You can use Java Message Service (JMS) or HTTP or HTTPS to send orders to OSM. Use JMS on production systems, because it provides quality-of-service guarantees not available from HTTP or HTTPS. Use HTTP or HTTPS on development and test systems (see OSM Installation Guide for more information).

About OSM Orders Without Orchestration

For orders that do not require an orchestration plan for fulfillment (called process-based orders), the OSM runs a single process and any subprocesses defined within the process, which includes tasks such as Activate_DSLAM. When a process-based order is submitted to OSM, the following occurs:

1. OSM starts the process.

2. The process can start subprocesses that run sequentially or in parallel.

3. After the last task has completed, the order transitions to the Completed state.

Figure 2-2 shows the process flow for a process-based order.

Figure 2-2 Process-Based Order

Description of "Figure 2-2 Process-Based Order"

About OSM Orders With Orchestration

For orders that require an orchestration plan for fulfillment, (called orchestration-based orders), OSM runs an Orchestration process. When a orchestration-based order is submitted to OSM for processing, the following occurs:

1. OSM starts the orchestration process.

2. OSM generates the orchestration plan which includes run time order components that run processes with tasks.

3. After the last task has within each order component completes, the order component completes.

4. After the last order component completes, the order transitions to the Completed state.

Figure 2-3 shows the process flow for an orchestration-based order.

Figure 2-3 Orchestration-Based Order

Description of "Figure 2-3 Orchestration-Based Order"

Modeling Roles and Setting Permissions

You use roles to control what operations can be performed and what data can be viewed by OSM user that you associated with the roles. You create roles then apply the roles to OSM entities in Design Studio. For example, roles are used in the following OSM entities:

• Order specifications: You define what order data users with specific roles can view in the OSM web clients by defining this data in query tasks and assigning the query tasks to roles within orders specifications. The OSM web client uses the query tasks to determine what data to display to users. The role applied to a query task determines the data that users associated to the role can retrieve. For more information about query tasks, see "Modeling Query Tasks for OSM Clients". You also define filters that specify whether orders with specific values can be displayed to users with the defined roles, and flexible header that define custom searchable data fields.

  Figure 2-4 shows roles defined in an order specification in Design Studio. In this example, members of BillingUpdateRole are allowed to view orders for customers in the 408 and 510 area codes.

  Figure 2-4 Roles Defined in an Order Specification

  
  Description of "Figure 2-4 Roles Defined in an Order Specification"

• Order life-cycle policy: You define what transactions can be performed by users associated with the roles assigned to each transition. For example, you may want to a standard role to handle normal order processing from the Not Started state through to Completed state. You may also want to assign a role for fallout management operations or amendment processing work. For more information, see "About Modeling Transition Permissions".

• Tasks: You define what tasks can be performed by users associated with the roles assigned to each task. For example, you may want a role that can run normal processing tasks, another for tasks during amendment processing, and another for tasks during fallout management. You define what data is available for each role associated to these tasks functions using query tasks. For more information about query tasks, see "Modeling Query Tasks for OSM Clients".

• Order, task, and process notification: You define what notifications are sent to which group of users by assigning roles to specific notification instances in the Order editor, a Task editor, or a process activity or flow.

• Order components: You define what data users with specific roles can view by applying those roles to query tasks and assigning the query tasks to components. OSM web clients uses the query tasks to specify which what data to display to users. The role applied to a query task determines the data that task will retrieve. For example, you may define a ProvisioningRole for a provisioning order component that allows OSM client users to view certain data.

  Figure 2-5 shows roles used in an order component. In this example, members of ProvisioningRole can perform queries based on ProvisioningFunctionTask and view the data in both the summary and detail views in the Order Management web client.

  Figure 2-5 Roles Used in an Order Component Specification

  
  Description of "Figure 2-5 Roles Used in an Order Component Specification"

• Order item specification: You can associate roles with corresponding query tasks from the Order Item Specification Permissions tab. The method of applying roles in an order item specification is identical to the method of applying roles in an order component specification. For more information about query tasks, see "Modeling Query Tasks for OSM Clients".

In addition to associating roles with OSM entities, you can also configure permissions for various actions on the roles. Figure 2-6 shows a role defined in Design Studio. In this example, users assigned to this role can generate online reports, search for orders, and access the Task web client Worklist display.

Figure 2-6 Role Defined in Design Studio

Description of "Figure 2-6 Role Defined in Design Studio"

Table 2-1 shows the actions that can be assigned to roles in Design Studio.

Table 2-1 Functions Assigned to Roles

Function	Description
Create Versioned Orders	Enables users to create orders for different versions of cartridges. If not granted this permission, users can create orders only for the default version of the cartridge.
Exception Processing	Enables users to alter the flow of a process by applying exception statuses at any time throughout the process.
Online Reports	Enables users to view summarized reports on all orders and tasks on the system.
Order Priority Modification	Enables users to modify the priority of a task in an order.
Reference Number Modification	Enables users to modify the reference number of an order.
Search View	Enables users to access the order Query function. See "Specifying Which Data to Display in the OSM Web Clients" for more information.
Task Assignment	Enables users to assign tasks to others.
Worklist Viewer	Enables users to display the worklist in the Task web client.

Because roles are defined globally in OSM, roles specified in one cartridge can be applied to any other cartridge, and roles used in one order can also be used in any other order. If you want to further restrict certain operations in an order, you must do so in the Design Studio entities that the roles are associated with, such as the life-cycle policy transaction or the task execution modes.

You associate roles with OSM user accounts using the OSM Order Management web client. Roles are called workgroups in the OSM Order Management web client. Each user account can belong to as many workgroups as are available on the OSM server. For more information, see OSM Order Management Web Client User's Guide.

About Order Types

Figure 2-7 shows OSM orders in different order processing scenarios and how OSM receives them. These scenarios include:

• Customer orders, service orders, and technical orders that are sent to OSM systems running in the central order management (COM), service order management (SOM), and technical order management (TOM) roles. For more information, see "About Determining the OSM Functionality to Implement".

• Revision orders sent to change an in-progress order. For more information, see "Modeling Changes to Orders".

• Order update performed either manually through the Task web client or through an automation task automator plug-in that sends an UpdateOrder request. For more information, see "About Order Updates".

• Job orders performed either manually through the Order Management web client or through the OSM CreateOrder Web Service operation. For more information, see "Using a Job Control Order to Manage Multiple Orders".

See "Modeling OSM Data" for more information about how orders and order items are structured.

Figure 2-7 Order Types and Order Processing

Description of "Figure 2-7 Order Types and Order Processing"

About Order Updates

You can update order data within customer, service, and technical orders that have already been created in OSM. OSM defines the following contexts where you can update order data:

• Order context: This context defines an overall view of OSM data. Although you can update order data in this context, doing so may compromise the integrity of order data, especially if the data you update may be subject to amendment processing. If you know that the data you want to update in the order context should never trigger amendment processing, you can mark the data as not significant (see "About Data Significance" for more information).

• Task context: This context defines a task specific view of OSM data. You typically use tasks to communicate with external fulfillment systems or manual task users that make changes to the data define in the task. Updating order data within the task context ensures the data integrity, especially when the data you update may be subject to amendment processing. See "About Order-Level and Task-Level Compensation Analysis" for more information about how tasks ensure data integrity during amendment processing.

You can update order data on orders and tasks in following ways:

• XML API UpdateOrder

  After receiving a JMS response message from an external system at an automation task automator plug-in, you can use the XML API UpdateOrder to update data or add any new data to the order. For example, you can use UpdateOrder to update any status notification data returned from an external system or another instance of OSM (see Figure 2-7). Oracle recommends that you run the XML API only from within the task context.

• OSM Java API methods

  After receiving a JMS message from an external system at an automation task automator plug-in, you can use various OSM Java API methods to update data or add any new data to the order. Oracle recommends that you run these Java API methods from within the task context.

• Web Service UpdateOrder

  You can use the OSM Web Service UpdateOrder operation to update order data outside of the Task web client and the automation framework. However, OSM Web Service operations can only access the overall order data context and do not have direct access to the task context. Use caution because doing so can compromise order integrity.

• Task web client

  Personnel can update task data manually, by opening and editing an order using the Task web client order query. Changes to task data in the Task web client are within the task context.

See OSM Developer's Guide for more information about updating order data using the XML API UpdateOrder, the OSM Web Service UpdateOrder operation, and the OSM Java API methods. See OSM Task Web Client User's Guide for more information about using the Task web client to update order data.

Update orders can:

• Update a complete order. The existing order is updated (elements are added, changed, or deleted) to match the supplied order. Order-level order updates are typically sent in the context of order-level notifications, jeopardy notifications, or event automation automators. See "Modeling Jeopardy and Notifications" for more information about update order transactions used in the context of jeopardies, notifications, and events.

• Update nodes in an order. Elements can be added or changed. Deleting nodes are not performed using the update node functionality. The nodes are supplied in the format of the existing order and are typically sent as part of task-level automation automators.

• Add, delete, or change element data values that are typically sent as part of task-level automation automators.

Using a Job Control Order to Manage Multiple Orders

Job control orders enable you to efficiently apply changes to many orders at the same time. You can use job control orders to apply the same set of OSM Web Service operations or OSM Order Management web client actions to multiple orders. For example, you could model a job control order using a CreateOrder OSM Web Service operation that selects multiple orders, suspends each of them, updates order data on all the orders, and then resumes each orders.

You can specify how many OSM Web Service operations or Order Management web client actions OSM can process at the same time. You can specify a failure threshold for job control order operations that, if crossed, causes the entire job control order to enter the suspended state. In addition, job control orders support a variety of counters that track job order progress.

To use job control orders:

1. Ensure that the JobControl_Solution portal archive (PAR) file has been deployed on the OSM server. This PAR file can be deployed either when OSM is first installed or manually. For manual deployment instructions follow the instructions in the readme file that is in the OSM_home/ProductCartridges/install directory. more information about deploying the job control order cartridge, see OSM Installation Guide. The PAR file packages the following OSM projects that you can see in the Design Studio Cartridge Management editor when you query an OSM server for cartridge information:

   • BatchJobCommonResources: Contains the job control order system configuration file that defines default job control order settings.

   • JobControl: contains the OSM Design Studio cartridge that enables the job control order functionality.

   • JobControl_Solution: contains the solution cartridge that packages the BatchJobCommonResources and JobControl cartridges.

   Note:

   You can only view these cartridges when you query OSM for cartridge information. Oracle does not provide access to the actual Design Studio projects.

2. In the OSM WebLogic server, create a new user account or use an existing user account and associate it with the OMS_ws_api group.

   Note:

   You can also associate the user account to the OMS_client group to give the user access to Order Management web client and Task web client.

3. In the Order Management web client, associate the user account with the JCO_UserRole or the job control order functionality in the JCO_SuperUserRole workgroups (roles). For more information, see "About Job Control Order Permissions".

4. Ensure that all orders to be managed by job control orders have roles associated with the default oms-automation OSM user account.

5. Model job control orders using the CreateOrder OSM web service operation and the following syntax:

   <?xml version="1.0" encoding="UTF-8"?>
   <ord:CreateOrder xmlns:ord="http://xmlns.oracle.com/communications/ordermanagement">
     <CreateJob xmlns="http://oracle.communications.ordermanagement.cartridge/job">
     <FailureThreshold>threshold</FailureThreshold>
     <ConcurrentOperationsAmongOrdersInJob>degree</ConcurrentOperationsAmongOrdersInJob>
      <Priority>priority</Priority>
      <RequestedDeliveryDate>requestedDeliveryDate</RequestedDeliveryDate>
       <Selection>
           byOrderCriteria 
           or 
           bySelectionCriteria
       </Selection>
       <Operations>
           operations
       </Operations>
     </CreateJob>
   </ord:CreateOrder>
   

   where:

   • threshold: (Optional) The number of operations that must fail before the job control order automatically transitions to the Suspended state. Valid values are percentages from 1% to 99%, absolute values, such as 10, 15, and so on, or 0 which specifies no threshold. If specified, this value overrides the default value specified in the batch_job_cfg.properties file (see "About Job Control Order System Configuration Files").

   • degree: (Optional) The number of executable components created for each operation in the job. If specified, this value overrides the default value specified in the batch_job_cfg.properties file (see "About Job Control Order System Configuration Files").

   • priority: (Optional) The priority of the job control order (see "Modeling Order Priority").

   • requestedDeliveryDate: The date and time when the job control order is to begin (for example, 2014-08-01T03:10:00Z). For more information about requested delivery dates, see "Modeling Order Scheduling".

   • byOrderCriteria: The orders to which the job control order operations apply. For example:

           <Orders>
             <OrderId>1</OrderId>
             <OrderId>2</OrderId>
             etc...
           </Orders>
     

   • bySelectionCriteria: The selection criteria that OSM uses to match corresponding orders to. For example:

         <ord:SelectBy>
           <ord:OrderState>lifecyclestate</ord:OrderState>
           <ord:Cartridge>
              <ord:Name>cartridgename</ord:Name>
              <ord:Version>1.0.0.0.0</ord:Version>
            </ord:Cartridge>
          </ord:SelectBy>
     

     The job control order selection criteria is identical to the SelectBy option of the FindOrder OSM Web Service operation. See OSM Developer's Guide for more information. The number of orders returned using the selection criteria is limited by the FindOrderMaxOrderThreshold oms-config.xml parameter. The default value is 1000. For information about modifying the default FindOrderMaxOrderThreshold parameter, see OSM System Administrator's Guide.

   • operations: One or more OSM Web Service operations listed in "About Job Control Order Operations" according to the permissions listed in "About Job Control Order Permissions". For example:

           <ord:SuspendOrder>
             <ord:Reason>Job Test</ord:Reason>
           </ord:SuspendOrder>
           <ord:UpdateOrder>
             <ord:View>CreationView</ord:View>
             <ord:DataChange>
               <ord:Update Path="/account_information/amount_owing">444</ord:Update>
             </ord:DataChange>
           </ord:UpdateOrder>
     

About Job Control Order Operations

You can run combinations of the following web service operations as a part of a job control order:

• SuspendOrder: Causes OSM to stop all processing on the orders specified in a job control order. The orders transition from the In Progress or Not Started state to the Suspended State.

• ResumeOrder: Causes OSM to resume processing all orders specified in a job control order that are in the Suspended state. The orders transition from the Suspended state to In Progress state.

• CancelOrder: Causes OSM to cancel all orders specified in the job control order. All applicable order components and tasks are undone. The orders transition to the Cancelling state while order components and tasks are running in the undo mode. After all order components and tasks complete, the order transitions from the Cancelling state to the Cancelled state.

• AbortOrder: Causes OSM to abort all orders specified in the job control order. The orders transition to the Aborted state.

• FailOrder: Causes OSM to fail all orders specified in the job control order. The orders transition to the Failed state.

• ResolveFailure: Causes OSM to revert all orders specified in the job control order to the previous order state before the orders failed.

• RetryOrder: Causes OSM to retry an order or a collection of order components for a given order. All failed tasks in the order or within the order components are retried and transitioned from the failed execution mode back to the normal execution modes such as do, redo and undo.

• UpdateOrder: Causes OSM to update order data on all orders specified in the job control order.

Operations run in the sequence they appear in the job control order. You must ensure that the sequence is logical. For example, you can suspend, update, and then resume an order, but you cannot resume, suspend, and update an order. You must also ensure that order life-cycle policies of the orders that the job control order interacts with supports the use of the operations you want to be available to a job control order.

For more information about the transitions associated with job control order and the roles that can run these transitions, see "About Job Control Order Permissions". For more information about OSM Web Service operation syntax, see OSM Developer's Guide.

About Job Control Order Permissions

The job control order solution cartridge contains the JCO_UserRole and the JCO_SuperUserRole workgroups (roles) with different permissions configured for each. You associate user accounts with workgroups using the Order Management web client. For more information about associating user accounts with workgroups, see OSM Order Management Web client User's Guide.

Table 2-2 shows the permissions available to each role.

Table 2-2 Permissions for JCO_SuperUserRole and JCO_UserRole

Permission	JCO_SuperUserRole	JCO_UserRole	Description
Version Orders	Yes	No	Allows users to create orders for different versions of cartridges. If not granted this permission, users can create orders only for the default version of the cartridge.
Exception Processing	Yes	No	Allows users to alter the flow of a process by applying exception statuses at any time throughout the process.
Order Priority Modification	Yes	Yes	Allows users to modify the priority of a task in an order.
Reference Number Modification	Yes	Yes	Allows users to modify the reference number of an order.
Task Assignment	Yes	Yes	Allows users to assign tasks to others.
Modifications to configuration parameters in order data	Yes	Yes	Allows users to modify default configuration parameters for job control orders.
Modifications to other order data	Yes	No	Allows users to modify order data in operations.
Suspend State Transaction	Yes	Yes	Allows users to suspend or update a job control order in the In Progress state. Job control orders automatically enter the Suspended state when the job control order passes the jobFailedOperationsThreshold threshold. Users can also manually suspend a job control order by sending a SuspendOrder web service operation.
Resume State Transaction	Yes	Yes	Allows users to resume a suspended order. When a Suspended order is resumed, it returns to the state it was in prior to the Suspended state (for example, In Progress or Not Started).
Abort State Transaction	Yes	No	Allows users to Abort an order. All transitions to the aborted state occur after the grace period expires.
Cancel State Transaction	Yes	No	Allows users to Cancel a job control order. Canceling a job control order stops all further processing of the job control order. The cancel order does not reverse job operations that have already run.
Create Job Control Order	Yes	Yes	Allows users to create a job control order.
Transition to Complete State	Yes	Yes	The job control order enters the Completed state when all operations on all orders have completed, whether successfully or unsuccessfully.
Transition to Failed State	Yes	Yes	The job control order may transition to the Failed state. However, job control orders do count all failed operations.

About Job Control Order System Configuration Files

Table 2-3 shows the job control order configuration file parameters that manage all job control orders. Parameter values specified directly in a job control order override the job control order configuration file parameters.

Table 2-3 Parameters for the batch_job_cfg.properties File

Parameters	Description	Default
Concurrent Operations among Orders in Job	The number of executable components created for each operation in the job.	1
Failure Threshold	The number of operations that must fail before the job control order automatically transitions to the Suspended state. Valid values are percentages from 1% to 99%, absolute values, such as 10, 15, and so on, or 0, which specifies no threshold.	0

Viewing Orders in OSM Web Clients

You can view orders in the following ways:

• You can display the orchestration plan, and the order components and order items included in it, in the Order Management web client. For more information, see OSM Order Management Web Client User's Guide.

• You can display current and historical information about tasks in the Task web client. For more information, see OSM Task Web Client User's Guide.

Specifying Which Data to Display in the OSM Web Clients

You can choose the data to display in the OSM web clients using the following methods:

• Use task data to specify which data to display in the Task web client for manual tasks.

• Use behaviors to specify how OSM displays the task data within a manual task; for example, to hide or show task data or to make data read only. See "Modeling Behaviors" for more information.

• Use query tasks to specify which data to display in the Order Management web client Summary tab and Data tab. Query tasks are manual tasks that specify which data to display in the Order Management web client when opening an order. A query task is associated with a role that gives permission to view the order data that the particular role is allowed to view. For example, some users may only need to view billing related order data, while others may only need to view provisioning data. Some users may need to view the entire order. See "Modeling Query Tasks for OSM Clients" for more information.

Modeling Query Tasks for OSM Clients

Order management personnel can display orders in the Task web client and in the Order Management web client. You can specify which data is displayed by assigning query tasks to an order. The data that is specified in the query task is the data that is displayed.

You can select any task as the query task. You can also create special tasks whose only function is to specify which data to display.

Figure 2-8 shows the Permissions tab in the Design Studio Order editor. The upper screenshot shows the permissions for the provisioning role, with the provisioning function task as the query task. The lower screenshot shows the permissions for the billing role, with the billing function task as the query task.

Figure 2-8 Roles Assigned to Query Tasks

Description of "Figure 2-8 Roles Assigned to Query Tasks"

The Order Management web client uses the following types of views to display orders; a summary view in the Summary tab and a detailed view in the Data tab. When you model a query task, you can specify which of those views (either or both) to display the query task data in.

You can use multiple tasks as query tasks for an order. When you do so:

• For the summary view, all the data is displayed in the Order Management web client Summary tab.

• For the detailed view, the data from the query tasks appears as options in the Order Management web client Data tab View field; each option presents the OSM user with a different view, each containing a specific set of data.

You can use multiple query tasks in the Order Management web client when using an orchestration cartridge. For process-based cartridges, only the default query task is available in the Order Management web client. To display the query task in the Task web client, select the Default check box, as shown in Figure 2-8.

In addition to defining the data that can be displayed, you can specify who can see it by using roles. Each role that is associated with an order can be assigned different query tasks. For example, if your order management personnel includes a role for billing specialists, you can create query tasks that show data specific to their activities.