Managing the Integration Workflow

2 Managing the Integration Workflow

Learn about managing the OSM and SCD integration workflow that contains the end-to-end user journeys for designing, deploying, and managing solutions. This chapter covers the detailed processes for developing capabilities cartridges, integrating fulfillment models, managing solution lifecycle stages, and ensuring operational readiness in production environments.

See the following topics:

Role Definitions for End-to-end Solution Workflow

Use roles to control access and permissible operations in OSM and Solution Designer. Create user accounts and assign roles to grant access according to job responsibilities.

Table 2-1 lists the roles are required for the end-to-end solution workflow, along with their responsibilities and the applications they use.

Table 2-1 Roles for End-to-end Solution Workflow

Roles	Description	Applies To
OSM Developer	Create Capabilities Cartridge, new fulfillment patterns, fulfillment functions, and fulfillment systems. Package artifacts using new packaging process. Deliver packaged artifacts to OSM DevOps Admin.	Design Studio
Product Specialist	Select capabilities cartridge to model against initiative. Define and manage the product specifications. Define and manage product fulfillment model.	Solution Designer
Service Domain Specialist	Configure Product to Customer Facing Services mapping together with parameter mappings. Define the structure and models for customer services. Define how the services are designed and delivered to the customers.	Solution Designer
Fulfillment Specialist	Configure the fulfillment patterns. Configure Product to fulfillment pattern mapping. Define routing rules. Define execution level.	Solution Designer
Service Catalog Admin	Receive notification from OSM DevOps Admin regarding capabilities cartridge manifest. Import capabilities cartridge manifests into SCD. Manage workspace lifecycle. Publish initiative to Test or production workspace.	Solution Designer
OSM DevOps Admin	Configure OSM runtime instances. Communicate with service catalog admin regarding capabilities cartridge manifest. Load capabilities cartridges into OCA. Manage OSM runtime instance lifecycle. Configure CNTK instance specification. Deploy and undeploy cartridges.	OSM

End-to-end Solution Workflow

The end-to-end workflow of Solution Designer and OSM starting from creating a capabilities cartridge, to deploying the solution cartridge in the OSM run-time instance is as follows:

Create Capabilities Cartridge: The OSM Developer develops and tests the capabilities cartridge in Design Studio. See Creating Capabilities Cartridge for more information.
Package Capabilities Cartridge: The OSM developer packages artifacts in Design Studio. See Packaging Capabilities Cartridge for more information.
Deliver Artifacts to Administrators: The OSM developer delivers the capabilities cartridge to OSM DevOps Administrator. The OSM DevOps Administrator delivers the capabilities cartridge manifest to the service catalog administrator. See Delivering Artifacts to Administrators for more information.
Configure and Deploy to OSM Cartridge Assembler (OCA): The OSM DevOps administrator performs the following:
1. Configures the OSM instance with connectivity details for a single Solution Designer instance.
2. Loads the capabilities cartridge into OCA.
See Configuring and Loading to OCA for more information.
Import the Capabilities Cartridge in Solution Designer: The service catalog administrator imports the capabilities manifest into Solution Designer. See Importing Capabilities Cartridge into Solution Designer for more information.
Create the Product Fulfillment Model: In Solution Designer, a product specialist enriches the capabilities cartridge by defining the product fulfillment model. A Fulfillment Specialist defines the routing rules in the product fulfillment model. See Creating Product Fulfillment Model for more information.
Publish to Test Workspace: The service catalog administrator manages the initiative lifecycle and publishes it to a test workspace. When the initiative is published, SCD metadata is sent to the OCA. See Publishing the Initiative to Test Workspace for more information.
Assemble and Deploy the Solution: OSM Cartridge Assembler (OCA) then assembles and deploys the cartridge to the OSM instance. If the deployment is across the functional testing, acceptance testing, and production environments, the same major version is deployed to the database, although the final digit (representing the publish number) may vary between environments. An example of cartridge naming convention, for instance, employs a format such as '1.0.0.592', in which '1.0.0' signifies the version of the capabilities cartridge and '592' designates the publish number of the deployed cartridge. See Assembling and Deploying the Solution for more information.
Publish to Production Workspace: After the deployed solution is tested against OSM runtime, the service catalog administrator transitions the initiative through its lifecycle and finally, publish the initiative to the production workspace. After the publish operation is successful, the cartridge is deployed in the configured OSM production instance and OSM runtime processes new orders using the newly deployed solution. See Publishing the Initiative to Production Workspace for more information.

Creating Capabilities Cartridge

To create a capabilities cartridge:

Provision a dedicated OSM cloud native instance for testing to avoid overlaps with other environments. See Preparing for OSM Cartridge Assembler in OSM Cloud Native Deployment Guide for more information.
Develop the capabilities cartridge in Design Studio. You can include new fulfillment patterns, functions and system integrations as required by your solution. See Generating a Capabilities Cartridge Using the Wizard in Design Studio Modeling OSM Orchestration for more information. Add a test model to this in order to get a deployable solution cartridge to aid in cartridge development and testing.

Key activities include:
- Defining technical entities, behaviors, and orchestration logic.
- Implementing complex business rules and integrations.
- Defining a set of test data so that the orchestration logic can be validated through runtime order processing.
- Repeating the building and deployment cycle until testing confirms correct cartridge processing.
Test the solution cartridge by following the steps:
1. Deploy the solution cartridge to the OSM cloud native test instance.
2. Run unit and functional tests to validate expected behavior.
3. Diagnose and fix defects found during testing.
4. Iterate until the cartridge meets all technical and functional acceptance criteria.

Packaging Capabilities Cartridge

Package the capabilities cartridge after validation is complete. Use the packaging approach designed to enable business users to operate within Solution Designer. See Capabilities Cartridge Build in OSM Modeling Guide for information on generating the capabilities cartridge.

The following two key artifacts are generated in the capabilities cartridge:

.cpar file: An archive of reusable OSM content that is exposed in Solution Designer. This is not a deployable artifact and must be loaded in OCA that is configured with the connectivity details of the Solution Designer instance. The file is used to create an image that is loaded into the OSM Cartridge Assembler Microservice. See Installing OSM Cartridge Assembler (OCA) for Integration with Solution Designer in OSM Cloud Native deployment guide for more information on configuring the OCA and loading the .cpar file to OCA.
capabilitiesManifest.json file: Describes the reusable components that are made available in the .cpar file. This file must be imported into Solution Designer.

Delivering Artifacts to Administrators

The generated artifacts are delivered to the administrators:

The OSM developer delivers the .cpar file to the OSM DevOps administrator for OSM instance configuration per specification.
The OSM DevOps in turn deliver the capabilities cartridge (capabilitiesManifest.json) manifest to the Service Catalog administrator.

The OSM Developer must collaborate with the OSM DevOps administrator and Service Catalog administrator to resolve any questions or issues and confirm all dependencies are satisfied.

Configuring and Loading to OCA

To configure and load the capabilities cartridge to OCA, the OSM DevOps Administrator:

Creates a new cpar container image using the Image Builder tool based on the .cpar file. The details of the new image are then added to the project specification file for OSM cloud native. For more information, see Building the Capabilities Cartridge Image.
Configures the OSM instance with connectivity details for a single Solution Designer instance. For more information, see Configuring the Instance Specification.
Starts the OSM instance or upgrades it, if it is already running, to enforce the new .cpar file in OCA runtime.

Importing Capabilities Cartridge into Solution Designer

The Service Catalog administrator imports the capabilitiesManifest.json file into Solution Designer, which provides access to fulfillment entities, fulfillment patterns, fulfillment functions, fulfillment systems, order item properties, and granularities. In Solution Designer, you can build a fulfillment solution using the entities from a capabilities cartridge. See Importing Capabilities Cartridges in Solution Designer User's Guide for more details on importing capabilities cartridge into Solution Designer.

Creating Product Fulfillment Model

You can enrich the capabilities cartridge by creating a product fulfillment model and associating the model with an initiative. The fulfillment specialist creates the product fulfillment model in Solution Designer. This involves adding product specifications, mapping them to CFSs, providing parameter mapping, defining target fulfillment patterns, and creating routing rules for order decomposition. See Creating Product Fulfillment Models using Guided Mode in Solution Designer User's Guide for more information on creating a product fulfillment model.

Publishing the Initiative to Test Workspace

The product fulfillment model containing fulfillment patterns, fulfillment functions, fulfillment systems, and routing rules is associated with an initiative. After you complete the product fulfillment model, you must publish the associated initiative to the Test workspace to perform functional testing and then acceptance testing. When the initiative is published to OSM participant in the test workspace, in Solution Designer, the initiative contents are sent to OCA. OCA then uses the initiative content and the capabilities cartridge .cpar file (loaded in OCA) to generate an OSM Central Order Management (COM) cartridge, which is deployed to the OSM runtime automatically.

See Publishing Initiatives to OSM Participant in Solution Designer User's Guidefor information on how to publish the initiative to OSM participant.

Assembling and Deploying the Solution

When the service catalog administrator publishes the initiative to OCA, it also sends the metadata to OCA. OCA then assembles the initiative content and the capabilities cartridge .cpar file (loaded in OCA) to generate an OSM Central Order Management (COM) cartridge, which is deployed to the OSM runtime automatically. If the deployment is across the functional testing, acceptance testing, and production environments, the same major version is deployed to the database, although the final digit (representing the publish number) may vary between environments. An example of cartridge naming convention, for instance, employs a format such as 1.0.0.59, in which 1.0.0 signifies the version of the capabilities cartridge and 59 designates the publish ID of the solution cartridge.

Publishing the Initiative to Production Workspace

After functional testing and acceptance testing are successful, in Solution Designer, the Service Catalog administrator releases the initiative to the OSM participant in the production workspace. When the publish operation is successful, the initiative's status transitions to Released. OCA generates the production cartridge and deploys it in the OSM production instance. The OSM instance then processes new orders using the deployed solution.

See Publishing Initiatives to OSM Participant for information on how to publish the initiative to OSM participant.

Capabilities Cartridge Lifecycle Workflow

A capabilities cartridge is an important artifact that a OSM Developer develops and hands over to the DevOps admin for deployment. The lifecycle of a capabilities cartridge involves three key stages:

Create
Update
Retire

Creating Capabilities Cartridge

See Creating Capabilities Cartridge for information on creating capabilities cartridge.

Updating Capabilities Cartridge

The capabilities cartridge may need to be modified to reflect the changes in business requirements.

OSM Developer updates the content in Design Studio and generates updated capabilities artifacts. See Generating a Capabilities Cartridge Using the Wizard for more information.
The updated .cpar file is passed to OSM DevOps Administrator and the capabilities manifest JSON file is passed to the Service Catalog Administrator.
The OSM DevOps Administrator creates a new image based on the updated .cpar file. The CNTK specification file for the OSM cloud native instance is also updated with the details of the new image, replacing the previous version. See Building the Capabilities Cartridge Image for more information.
Service Catalog Administrator imports the updated JSON file (capabilities cartridge) in Solution Designer.

Retiring Capabilities Cartridge

You may need to retire a Capabilities Cartridge when it is no longer needed due to service deprecation or redundancy.

The DevOps admin removes all entries related to the retiring Capabilities Cartridge from the cloud native toolkit specification file for the OSM cloud native instance to decommission the cartridge.
The retired capabilities cartridge is no longer active in the OSM environment. Retiring the cartridge is essential to maintain a clean environment.

Solution Lifecycle Workflow

The lifecycle of the solution cartridge in an OSM environment involves multiple users in creating, updating, and deleting these cartridges. The detailed workflow includes:

Creating the Solution Cartridge
Updating the Solution Cartridge
Deleting the Solution Cartridge

Creating the Solution Cartridge

To create the solution cartridge, initiate the publish process in Solution Designer. The prerequisites are that the capabilities cartridge is created in Design Studio, loaded in OCA, imported into Solution Designer, enriched using product fulfillment model in Solution Designer.

Service catalog administrator initiates a publish in Solution Designer. See Publishing Initiatives to OSM Participant in Solution Designer User's Guide for information on publishing the initiative to OSM participant.

During the publish operation, Solution Designer sends the initiative content and the associated capabilities cartridge name with version appended with the publish operation ID to OCA. OCA creates the solution cartridge by merging the loaded capabilities cartridge .cpar file and the received initiatives content. OCA then deploys the solution cartridge into the OSM runtime environment.

For every publish operation, a new version of the solution cartridge is created and deployed to OSM environment. When you publish an initiative in Solution Designer, a unique publish number is generated which is used to identify the publish requests within the initiative.

Updating the Solution Cartridge

You may need to update the solution cartridge due to a business requirement such as the need to coordinate with a new type of downstream system (say, a work order management tool) for some types of products. Here you would need to code a new orchestration function to talk to the system. This would be worked into existing and, if needed, new fulfillment patterns.

Note:

The updated solution cartridge is effective only for new orders, and does not retroactively affect the in-progress orders.

OSM Developer implements the fulfillment pattern changes to address the identified production bug.

Generate a new version of the solution reflecting the fix.
OSM developer then packages the cartridge artifacts, the .cpar file, and the JSON file.
OSM DevOps Administrator loads the .cpar into OCA.
Service Catalog Administrator imports the new version of capabilities cartridge into Solution Designer.
Fulfillment specialist updates the fulfillment model with capabilities cartridge and fulfillment pattern.
Service Catalog Admin initiates the publish operation to OSM Participant. OSM participant sends the updated content to OCA which in turn generates the updated solution cartridge and deploys it in OSM instance. Record the new version of the solution cartridge.

Existing orders are not affected by the new solution cartridge version and any in-progress orders will continue to progress using their pre-existing cartridge versions. OSM does not apply changes retroactively; the updated fulfillment pattern affects only new orders.
The upstream System (Order Management system) resubmits the stuck in-progress orders after making any necessary adjustments so they are processed under the updated fulfillment pattern. Validate that the orders are processed correctly with the updated fulfillment pattern.

Deleting the Solution Cartridge

OSM DevOps Administrator can undeploy all or selected solution cartridges from the OSM environment using the product specification and the manage-cartridges.sh cloud native toolkit script. For more information, see Working with Cartridges.