1. Modeling Guide
  2. Implementing an OSM Solution
  3. Modeling External REST Interactions using System Interaction (Cloud Native Only)

12 Modeling External REST Interactions using System Interaction (Cloud Native Only)

This chapter describes how to model external REST interactions using System Interaction.

Before reading this chapter, refer to "About REST APIs and System Interaction (Cloud Native Only)" in OSM Concepts.

Note:

System Interaction is supported for OSM cloud native deployments only.

The System Interaction specifications can be TMForum REST APIs used in fulfillment (such as TMF700 for shipping or TMF 641 for provisioning), but can also be non-TMF APIs expressed as OpenAPI specifications. Parsing technology is used to validate that the structure and syntax of imported REST specifications align with the OpenAPI Initiative v3.0.1.

About Importing the OpenAPI Document into Design Studio

The OpenAPI document involved in a system interaction, is owned by and must be provided by the external application serving the API. The OpenAPI describes the specific capabilities of that system including available operations, HTTP headers, path parameters, HTTP response codes, schema, server url and so on. When the document is a TMF OpenAPI it is likely that extensions have been made by applications. Therefore, care should be taken that the file imported to Design Studio, reflects the current, up-to-date capabilities and schema supported by the external system.

Note that the OpenAPI version information is carried in two locations - at the info:version and as part of the server:url. Design Studio must be able to determine the version number unambiguously, therefore these numeric values must be an exact match before being imported to Design Studio.

TMF APIs for BSS/OSS System Interactions

For convenience, OSM cloud native makes available a set of TMF OpenAPI specifications that would typically be used for system interactions, as a reference. These are in the OSM SDK in the TMFSchemas/ClientSpecifications subfolder.

The samples provided are good for reference and may be used as a development accelerator. However, before actual integration is attempted, the System Interaction Specification should be updated to reflect the actual OpenAPI provided by the external system.

Importing a System Interaction

OSM Order Components have a System Interaction tab where cartridge developers can select the OpenAPI for a particular external system. Design Studio will perform parsing and validation to align with OpenAPI Initiative 3.0.1.

The system interaction tab of an order component, also provides a field to enter the Target System. This should be a logical name for the Target System and should describe the function of the Target System rather than its specific location. For example, a logical name of "Wireless-Activation" would be appropriate, as opposed to "Test-ASAP", as the latter pins it down to a specific system. This is important to allow flexibility between cartridge design and solution deployment design. The cartridge developer can freely reference a logical target system, leaving it up to the deployment scripts and configuration to allocate an actual target for that logical system in the form of a specific URL, authentication, and so on.

This logical name should be obtained from or provided to the individual responsible for maintaining the OSM CNTK deployment scripts. The same value must be defined in the CNTK project and instance specification files.

OSM does not support some aspects of OpenAPI schema for use in a System Interaction specification. For more information about these known issues and their workarounds, refer to "Known Issues and Workarounds."

Updating a System Interaction Specification

System Interaction Specifications are version specific. If an updated version of the OpenAPI is provided by an external system, the expectation is that the specification will reflect the version change. The Order Component holding the SI must have the old specification removed and the new one re-added. A delete and re-import will cause Design Studio to re-generate the necessary supporting metadata.

If an attempt is made to deploy a cartridge (new deploy or re-deploy) that bundles a System Interaction Specification of the same version, but with content differences then the cartridge deploy will fail as the specification with that version already exists. All specification changes should be accompanied by a version increase.

System Interaction and OSM Order Components

When a system interaction specification is imported to Design Studio, the specific operations and events become available as configuration for automation plugins as shown in the image below.

Figure 12-1 SI Operations Dropdown


Description of Figure 12-1 follows
Description of "Figure 12-1 SI Operations Dropdown"

In order to populate this list, Design Studio looks at the OSM subprocess that holds this automation task, and then at the Order Component that contains this subprocess. The System Interaction registered with that order component provides the list of operations.

In the example below, the ShipOrderFunction holds the System Interaction for the Shipping System.

The ShipOrderSubProcess is defined on the ShipOrderFunction.

Therefore, all automation tasks found in the ShipOrderSubProcess will have a list of operations from the System Interaction Specification.

Figure 12-2 ShipOrderSubProcess


Description of Figure 12-2 follows
Description of "Figure 12-2 ShipOrderSubProcess"

Determining the Order Component

OSM supports multiple layers of Order Components as part of the orchestration plan. Typically the layers in sequence are Function, System and Granularity. In case there is only one layer (which would be the Functional Order Component), apply the System Interaction to that component. In the example below, the functional order component - ActivateServiceFunction - has the System Interaction Specification.

Figure 12-3 activationOrchPlan


Description of Figure 12-3 follows
Description of "Figure 12-3 activationOrchPlan"

In case there are multiple layers of order components, apply the System Interaction to the earliest layer such that all subsequent layers (and their fan-out) satisfy these conditions:
  • Same target system being contacted,
  • With the same REST API version,
  • And via the same subprocess.

In the next example, the system and granularity order components for the ProductProvisioning function (blue boxes) do not deviate from the above conditions, therefore the System Interaction can be imported to the functional order component - ProductProvisionOrderFunction.

Figure 12-4 digitaltv


Description of Figure 12-4 follows
Description of "Figure 12-4 digitaltv"

In a final example below, the Provisioning function cannot hold the System Interaction for two reasons:
  • There are multiple target systems.
  • The systems use a different version of the TMF 641 specification.

In this case, the System Interaction Specification is imported to the "system" order component.

Figure 12-5 Emulated SOM


Description of Figure 12-5 follows
Description of "Figure 12-5 Emulated SOM"

Figure 12-6 OSM SOM


Description of Figure 12-6 follows
Description of "Figure 12-6 OSM SOM "

About the OSM Gateway Functions

OSM Gateway performs the following functions for interactions with an external system using REST APIs:
  • With JMS integrations, automation plugin code would be responsible for managing correlation. When REST interactions are modeled using System Interaction, then OSM Gateway becomes responsible for managing correlation. A condition of any integration using System Interaction, is that external systems must honor the HTTP header used by OSM for correlation. External system sync responses much echo back the HTTP header X-Correlation-ID that is sent on the request.
  • In a REST exchange with an external system, OSM Gateway translates the XML payloads generated by automation plugins, into JSON payloads destined for the endpoint (and vice versa). System Interaction Specifications are therefore restricted to application/json content types.
  • Schema validation on the payload content. Tuning parameters for schema validation can be found in the CNTK deployment scripts. This controls the Gateway behavior when unknown data is part of an incoming or outgoing payload.
  • Resolves the logical target system name on the System Interaction against deployment artifacts to derive actual system connection details.
  • If automation plugins have registered for event notifications then OSM Gateway listens for incoming events and passes them on to the external receiver automation plugin.
  • Passes hard failures and unresolvable transient failures back to the automation plugin. New Automation APIs are available to emit fallout exceptions in the event that the order needs to be flagged in the Order Operations UI.

Considerations for OSM Cloud Native to OSM Cloud Native Integration using System Interaction

When an OSM instance hosting a TMF specification interacts with another OSM instance that also hosts a TMF specification, there are some additional considerations for the cartridge developer. These are:

  • You should take care to ensure OpenAPI version consistency between the two instances. The version of the downstream Hosted Specification should also be used for the upstream System Interaction specification. You cannot successfully integrate with two different versions.
  • If a 622 or 641 System Interaction specification is imported, then Design Studio injects additional HTTP header content in anticipation of an OSM/TMF to OSM/TMF integration. If the external system is not an OSM instance, then this information is benign.
The following HTTP Headers are provided for integrations with OSM:
  • X-VERSION: This is required for revisions. A GET call on the main resource (GET/serviceOrder) provides the caller with an HTTP header where X-VERSION reflects the version of the currently processing order. This value can then be incremented for any revision requests that are sent to downstream OSM.
  • X-Fulfillment-Mode: If the TMF cartridge in the downstream OSM instance uses a non-standard fulfillment mode, then plugins should specify the fulfillment pattern name using this header. This is not required for standard create requests (deliver), cancellations (cancel) or amendments.

Developing Automation Plugins

For information about developing automation plugins, refer to "Using Automation with a System Interaction (Cloud Native Only)" in OSM Developer's Guide.

Known Issues and Workarounds

OSM does not support some aspects of OpenAPI schema for use in a System Interaction specification. This section describes these aspects and offers workarounds:

  • Inline nested schema objects:

    While OpenAPI schema allows a nested schema object to be fully defined inline with its usage, OSM requires this to be done by reference instead. The inline schema must be extracted as an independent element definition and the nested element should reference this definition.

  • Open-ended properties using additionalProperties field:

    OpenAPI schema allows for partial specification of child elements by adding the additionalProperties field. OSM requires all child elements to be enumerated in the specification. This can be done by extending the OpenAPI schema to include all the child elements of interest.

  • Default value for schema object in specification:

    OpenAPI schema can contain default values to use for schema objects if they are not present in the payload document. OSM does not honour these defaults. The payload originator must ensure such values are part of the generated payload document if they are required to be present.