ORD Introduction

🎦 There is also an ORD Introduction video, based on this article.

Why ORD?

• Need for consistent technical documentation how applications and services can be integrated with and developed against.
• Companies and their customers need to understand actual system landscapes, reflecting customizations and extensions.
• Need to provide more automation and a better development experience for integrating SAP products with each other, the BTP SAP ecosystem and side-by-side extensions.
• Many AI and Analytics use-cases rely on consistent and standardized metadata to deliver value or scale well.

Metadata integration without alignment

Without alignment on metadata standards and how they are discovered, all metadata integration between providers and consumers happens on a point-to-point basis. This not only means a lot of integrations, but also that the integrations may need to be implemented differently.

This is a similar situation when there was no standardization on charging cable adapters. It was difficult or sometimes impossible to connect various devices and led to high efforts and waste for everyone.

Metadata integration with ORD alignment

We can tackle this problem by introducing two concepts: First, use aligned standards for metadata description and discovery. Second, use a central aggregator, which can read metadata from all providers and can serve the information to all consumers.

ℹ Read the Why ORD? article for more background.

Metadata Discovery Protocol

Open Resource Discovery (ORD) is a protocol that allows applications and services to self-describe their exposed resources and capabilities. It can be used to describe static documentation, but can also reflect tenant specific configuration and extensions (at run-time).

By adopting ORD, an application will implement a single-entry point (Service Provider Interface) that can be used to discover and crawl the relevant information / metadata.

ℹ Please note that ORD does not replace already established standards to describe resources in detail. For example, plain REST APIs could be described via OpenAPI. ORD will enable the discovery of this fact and can pass along the relevant detailed metadata documents.

More Detail: How ORD helps with Self-Description

In the picture above, the center is an application or service describing itself. They typically have multiple resources and capabilities that are outward facing and are of interest for external consumers.

Typically, ORD is used to describe APIs and Events, but it also supports higher-level concepts like Entity Types (Business Objects) and Data Products (beta). With Integration Dependencies the (potential) use of external resources can be stated, too. In case that the standardized concepts or attributes are not sufficient, there are extensibility attributes and Capabilities.

ORD standardizes how those information can be automatically discovered and aggregated. Please note that ORD is no replacement for detailed resource definition standards like OpenAPI. Instead, it describes a bigger context with shared, high-level information, taxonomy and relations between the described resources. It also standardizes the publishing and discovery related interfaces and behaviors, to ensure a high degree of automation that allows us to keep in sync with reality. The same ORD implementation can be used to both describe the tenant-specific customer landscape and the static reference landscape view to an API Catalog.

When ORD information get combined by a central ORD aggregator and integrated with other, central metadata sources, we can realize a connected (customer) system landscape metadata view. This gives both SAP and our customers better introspection about the actual system landscape. This enables or improves many meta-data driven use-cases (like low-code/no-code).

The specification provides a shared contract and alignment point for the ecosystem, spanning various consumers and providers. This allows to have one aligned standard instead of a wild growth of specific point-to-point alignments and integrations.

Data Model Overview

The most typical resources to describe are APIs and Events. But ORD can also be used to describe higher-level concepts like Entity Types (Business Objects) and Data Products. With Integration Dependencies it is possible to also describe how external resources are or can be be used. In case that the standardized concepts or attributes are not sufficient, there are extensibility attributes and Capabilities.

The mentioned concepts can be grouped by different concerns via Packages and Consumption Bundles and various taxonomy attributes. Additionally, relations between the concepts can be expressed (e.g., which APIs and Events share the same Entity Types?).

ORD Architecture at SAP

Below is a simplified overview of how ORD has been adopted at SAP:

We need to make a distinction between describing and understanding:

• Customer System Landscape: Describes a real system landscape as it actually exists, e.g. for a customer ("as-is view").
  • SAP uses the Unified Customer Landscape (UCL) as central aggregator, that will discover and combine ORD information and re-expose them as a (customer specific) system landscape metadata view.
• Reference Landscape: Describes a static, generic catalog of what is offered ("could-be view").
  • SAP publishes static documentation to the SAP Business Accelerator Hub

ORD Consumers have now the convenience to get a holistic, pre-aggregated and connected picture and can use the aggregators for documentation and fetching the metadata via ORD Service APIs.

ORD Providers can now use the same protocol to publish the metadata to both perspectives and aggregators that has been aligned to work for various ORD Consumer use cases.

ORD by Examples

ORD Reference Application

Have a look at the ORD Reference Application to see a live example.

More Explanation on the ORD Reference Application

The ORD Reference Application shows a simple application, which offers a few APIs and Events. Some of the APIs are public and are of interest for outside consumers to learn about.

The flow to crawl the application for relevant metadata is the following:

• Execute an HTTP GET request on the .well-known/open-resource-discovery entry point.
  • With a successful response we now know that ORD is supported, where to find the actual information (documents.url) and how to access them (documents.accessStrategies)
• Execute an HTTP GET request on the first ORD document, we discovered from the previous step.
  • Here we now find the actual information, like the APIs and Events the application exposes, but also taxonomy like information like what product it is or how the information are structured into packages.
• For a particular API, we find out that it's a plain REST API, described with OpenAPI v3 in JSON format. We also learn how and where to download its OpenAPI resource definition.

SAP Business Accelerator Hub

The SAP Business Accelerator Hub is an ORD aggregator that uses static information to present generic documentation. This perspective is very important, as it describes technical aspects of products without the need to first own and provision the system.

More UI examples with annotations

Unified Customer Landscape

Unified Customer Landscape (UCL) is a set of technical services that also offers the system landscape metadata (incl. ORD information) to other applications and services. While the SAP Business Accelerator Hub focuses on the static perspective of a product, the UCL can provide the actual system tenant metadata - including possible customer extensions and customizations.

More UI examples with annotations and more details on UCL

The UCL offers information about the customer system landscape and managing integrations, as can be seen in the SAP BTP Cockpit in the System Landscape UI. Here customers can see their own systems and manage them e.g. grouping them via formations that enable trust and automatic integration between them for specific scenarios. Systems that are in the same formation usually need to get information about each other, some of which may be provided via ORD.

• The UCL automatically aggregates and consolidates all the information about the customer’s IT landscape into one unified machine-readable extensible graph-like landscape model. This model includes information about the customers SAP, Partner 3rd party and on-premise application (service) tenants as well as metadata about their API, event and connectivity-related requirements, existing integrations and their state. This includes amongst other things, also the ORD metadata of the systems.
• The automatically aggregated landscape model is then re-exposed for discovery and introspection to various SAP and Partner UIs and tools that customers use to oversee, manage and monitor their IT landscape. The metadata is also used to simplify development, e.g. for side-by-side extensions and Low-Code/No-Code tools. This is achieved by offering industry-standard GraphQL and OData APIs with rich querying capabilities.
• Provides the so called "managed by SAP" experience in the domain of integration lifecycle management** and therefore allow customers to focus purely on taking business decisions and not doing or caring about the actual technical wiring and integration setup underneath. This is achieved by providing active automation over the integrations based on already available metadata, specified by the Application Providers about what integrations are required and how they can be established. Leveraging the automated integration lifecycle management makes the life of both Customers and Application Providers much easier, as the day 2 operations, such as credentials rotation also happen automatically.

In the UI screenshot, the most notable concept is the ORD System Instance, which is usually a tenant. If ORD information are provided, the detail view can show them and they will be made available to other systems in the same formation or account context.

ORD in More Detail

ORD Information

ORD as a protocol standardizes both the information model and the behavior how the information are exchanged.

Typical questions that are addressed on ORD level are:

• Get an complete overview of the resources and capabilities
• What type of resource something is and how to access its metadata or the resource itself
• Where to find more information on the resource, e.g. links to machine-readable definitions (e.g. OpenAPI)
• Get overview documentation and find links to external human readable documentation
• How the resources fit into a global taxonomy
• How resources relate to each other (e.g. for navigation)

ORD Behavior

ORD can enable fully automated metadata discovery and exchange (after initial onboarding). by also standardizing how the information are discovered, transported and accessed. See ORD Transport Modes for an example.

ORD Roles Overview

In ORD there are three roles that systems can have. Depending on the role, only some parts of the specification are relevant and need to be implemented. One system can also have more than one role, e.g. an ORD Provider can also be an ORD Consumer.

ORD Provider Role

The ORD Provider is a system that describes itself via ORD, so it's metadata becomes available to interested ORD Consumers.

They have to implement one of the ORD transport modes (currently only a pull-based API is supported), so the ORD information and related metadata definitions can be discovered and fetched.

ORD Aggregator Role

The ORD Aggregator has the job to simplify the life of ORD Consumers. It will discover and connect to many ORD Providers and fetch their metadata. It may also integrate information from other (usually central) repositories. Since it builds an aggregated overview, here the decentralized information from many sources can come together and form a connected graph of metadata knowledge.

It's most notable feature is that it offers an ORD Service, which offers a high-quality API to ORD consumers. The information offered represent an aggregated, connected and consolidated metadata overview.

ORD Consumer Role

The ORD Consumer is interested in learning about the resources and capabilities of other systems.

An ORD consumer should get their information from an ORD Aggregator, where a complete overview is offered with a more consumer friendly ORD Service API

Don't forget to have a look at the Articles 📖 and Videos 🎦 that explain ORD related topics in more detail.