Using APIs to Integrate SAP Entitlement Management (SEM) Interfaces

In SAP Entitlement Management, an API is needed to make an interface work because it enables communication and data exchange between SAP Entitlement Management and other systems or applications. APIs define and implement inbound and outbound interfaces in SAP Entitlement Management.

Interfaces in SAP Entitlement Management refer to the mechanisms and communication protocols that facilitate the exchange of data between the entitlement management and external systems.

External APIs in SAP Entitlement Management are named so because they are designed to provide a standardized interface for interacting with the entitlement management system. These APIs serve as a bridge between the entitlement management system and other external systems, allowing for the exchange of data and communication through a defined set of programming interfaces.

Let’s explore the different types of APIs and interfaces that support entitlement management.

In SAP Entitlement Management, an inbound interface is a mechanism that allows external systems to send data and information into the SAP application. It can include information related to entitlement data, customer details, product information, and more. The inbound interface provides a way for external systems to communicate with SAP Entitlement Management and update or synchronize relevant data in the system.

Multiple APIs are available to define the inbound interface. These include:

• Configurations APIs
• Master Data APIs
• Entitlement APIs
• Consumption APIs
• User Management APIs (One API is available)
• Provisioning APIs (One API is available)

An outbound interface in SAP Entitlement Management refers to a mechanism that allows SAP Entitlement Management to send data and information to external systems involved in the fulfillment process.

Outbound interfaces send entitlements to the fulfillment system. Multiple APIs are available to define the outbound interface. These include:

• Configuration Response APIs
• Master Data Response and Request APIs
• Entitlement Response APIs
• Consumption Response APIs
• User Management Response APIs (One API is available)
• Event Notification API: When an event action is set to "Send Notification", once the event is triggered, the notification is sent out via the Event Notification API
• Background Job Records APIs (Two APIs are available)
• Provisioning APIs

APIs play a crucial role in facilitating the exchange of data and communication in both directions, enabling seamless integration with external systems and partners.

The Entitlement Generation API streamlines the process by transferring relevant data fields into the mapped entitlement, ensuring accurate and efficient entitlement management through a well-defined and automated system.

The payload of a generation API represents the value of the sales document from the upstream system. This API triggers the end-to-end process in SAP Entitlement Management. The value of this API is transferred to mapped entitlements via the Offering to Entitlement Mapping. Each mapped entitlement passes the matched generation rule with the configured rule set and is used to create a new entitlement or update existing entitlements in the system.

The payload of a generation API is configurable. Select the Explore APIs tile and select the ID for API Entitlement Generation v2. In the configuration page, you can add new fields to the predefined node Header or its child node Item. You can also add a sub node under Items.

Value of fields "Header.Document Type", "Header.Document Number", and "Item.Item Number" is transferred into "Reference Document Type", "Reference Document Number", and "Reference Item Number" on the mapped Entitlement. If the mapped Entitlement is used to create a new Entitlement, these values are saved as "Origination Document Type", "Origination Document Number", and "Origination Item Number" of the new Entitlement. If the mapped Entitlement is used to update an existing Entitlement, the values are saved with the same name in the update history of the existing Entitlement.

Value of fields "Offering ID" and "Offering system" will be used to find the corresponding "Offering to Entitlement Mapping" configuration.

Value of fields "Customer ID", "Customer System", "Offering ID", "Offering System", and "Source System" will be directly passed into the mapped Entitlement.

The value of "Source System" can be found in "customer system" or "offering system" maintained in master data. Otherwise, it must be maintained in Configure Entitlement Master Data Maintain Basic Configuration Entitlement Source System.

The field "Generation Method" has been deprecated. No matter what the value is in this field, the Entitlement attribute "Generation Method" is always auto if the Entitlement is generated via API.

The value of node "Contacts" under node "Item" is directly passed into the mapped Entitlement as the contact person assigned to the Entitlement. The system uses "Internal ID" to find the corresponding contact person in the system. If "Internal ID" is empty, the system uses "External ID" plus "Source System" to find the corresponding records.

Also note that the node Sales Document Entitlement under Item is used in standard integration content between SAP Entitlement Management and SAP Subscription Billing. It contains a list of entitlement numbers associated with the current sales document. This node can also be configured within a rule set to meet customer requirements.

The API returns the contact person information assigned to the generated or updated entitlement. You can set a value of the request header parameter x-ems-contacts to full.

To allow the API to return only the ID and the entitlement function of the contact person assigned to the generated or updated entitlement, set the value of the request header parameter x-ems-contacts to basic. This parameter also does not need to be added to the request header.

The value of the field Entitlement TimeZone at header level is directly passed into the mapped entitlement as the time zone of the entitlement.

For a single entitlement generation request, the system processes a maximum of 1000 entitlement creation or updates. If the number of created entitlements exceeds 1000, the system returns an error message.

The generation API allows you to create master data with a sales document according to the following rules:

• A user can add master data information for an order under the node MasterDataCreation. Master data includes the customer, offering, and contact person.
• Multiple master data records can be created. However, master data must appear in the sales document header or item, or it will be ignored by the system.
• A maximum of 10 master data records are allowed in the payload when sending a request in sync mode.
• A maximum of 1000 master data records are allowed in the payload when sending a request in async mode.

If the system detects records under the node MasterDataCreation, it will first filter out the master data records that do not appear in the sales document and create the master data. This API does not manage updating master data. If the master data to be created already exists, it will be ignored by the system.

Also, the system will not verify whether the specified master data value is the same as any existing master data record.

The master data creation process terminates when encountering any error during the process.