Product Information Management API

Use

You use this application programming interface (API) to allow SAP applications to obtain data from product information management (PIM) systems.

PIM systems are third-party applications that centrally manage product data to provide consistent, up-to-date information to various channels, such as Web shops, point-of-sale (POS) systems at retail stores, mobile applications, and interaction centers. Examples of data contained in PIM systems include images, audio, video, product descriptions, and operating instructions.

By using the PIM API, you can allow SAP applications such as SAP Promotion Management for Retail or SAP Customer Relationship Management (SAP CRM) to access read-only data from the PIM system.

The PIM API includes a client API to access information from the PIM system, and a service provider interface to simplify interactions between the PIM system and the SAP applications. The PIM service provider exposes functions as OData services.

The following diagram shows how information from a PIM system is accessed in a multichannel scenario:

Figure 1: PIM Information Accessed in a Multichannel Scenario

Prerequisites

You have installed the PIM system in the same system landscape as the consuming SAP applications.
You have installed SAP NetWeaver Gateway (component SAP_GWFND) in the same system landscape as the PIM system and the consuming SAP applications.

Note
SAP NetWeaver Gateway does not have to be installed on the same SAP system as the PIM API. You can use the Customizing activity described in the next step to configure access to the component from another SAP system.
You have defined parameter values to control the general behavior of the PIM API. You do this in Customizing for Cross-Application Components under Processes and Tools for Enterprise Applications Define Parameter Values for PIM API .

Supported Technical Entities

When SAP applications access information from a PIM system, they are consuming technical entities. These entities can be abstract or concrete, and are characterized by their properties. The following figure shows the technical entities and properties that are supported by the PIM API:

Figure 2: Technical Entities and Properties Supported by PIM API

The Asset technical entity is an abstract type that represents PIM system content and provides the basis for all entities. The following properties belong to the Asset technical entity, and are common to all entity types, both abstract and concrete:

Property	Description
ID	This is the internal technical attribute of the OData model.
GTIN	This is the global trade item number. When queries include the GTIN along with the material number and unit of measurement, the GTIN is prioritized in the search results. The GTIN is part of the external key for a product. The maximum character length for this property is 40.
Country	This is the country for the PIM asset. The maximum character length for this property is 3.
Region	This is the region for the PIM asset. The maximum character length for this property is 3.
MaterialNumber	This is the alphanumeric key that uniquely identifies the material in the SAP system, as well as the PIM asset. In SAP systems, the material number and the unit of measurement are part of the external key for a product. The maximum character length for this property is 18.
UnitOfMeasurement	This is the unit of measurement in which the material is sold. In SAP systems, the material number and the unit of measurement are part of the external key for a product. The maximum character length for this property is 5.
CommunicationChannel	This attribute can be used to further characterize an asset. The semantics and valid values are not part of the API, but a convention between the application using the API, and the third-party PIM service provider. For example, a text asset could be valid for the following communication channels: mobile, Web shop, print, or default.
Campaign	This attribute can be used to further characterize an asset. The semantics and valid values are not part of the API, but a convention between the application using the API, and the third-party PIM service provider. For example, a text asset could be valid for the following campaigns: Christmas, back-to-school, store anniversary, or Hanukkah.
Language	This is the output language for the PIM assets. When specifying the language, use a 2–character code that supports SAP language rules and conforms to the ISO 639–1 standard, such as DE for German and FR for French.
AssetTypeSubType	This attribute can be used to further characterize an asset. The semantics and valid values are not part of the API, but a convention between the application using the API, and the third-party PIM service provider. For example, a text asset could have the following subtypes: product description, instructions, warranty, or nutrition facts.
ValidFrom	This is the date from which the PIM asset is valid. When specifying the date, you must use the YYYYMMDD format.
ValidTo	This is the date to which the PIM asset is valid. When specifying the date, you must use the YYYYMMDD format.

The supported concrete entity types are described in the following table:

Concrete Entity Type	Description
AudioAsset	Audio, such as an MP3 file
DocumentAsset	Document, such as a PDF or word processing file
ImageAsset	Image, such as a PNG file
TextAsset	Plain text, such as a product description
VideoAsset	Video, such as an MP4 file

PIM API Usage

SAP systems use the CL_PIM_API class as the entry point for accessing PIM systems. This class provides the following methods:

Method	Description
SEARCH_ASSETS	Accepts a set of product properties to be used as search and filter criteria. Returns a collection of assets that match the search and filter criteria.
SEARCH_ASSETS_BY_RANGE	Same as SEARCH_ASSETS, but uses an input range table to provide more complex search and filter criteria.
GET_PIM_SERVICE_STATUS	Returns information about the service provider for the PIM system, such as the availability of the service or corresponding error messages. As the PIM system is outside the ABAP stack, this method is required to help SAP applications verify the availability of the service provider.

Method

Description

SEARCH_ASSETS

Accepts a set of product properties to be used as search and filter criteria.

Returns a collection of assets that match the search and filter criteria.

SEARCH_ASSETS_BY_RANGE

Same as SEARCH_ASSETS, but uses an input range table to provide more complex search and filter criteria.

GET_PIM_SERVICE_STATUS

Returns information about the service provider for the PIM system, such as the availability of the service or corresponding error messages.

As the PIM system is outside the ABAP stack, this method is required to help SAP applications verify the availability of the service provider.

The properties provided by the IS_SEARCH_PARAM structure (in the SEARCH_ASSET method) or the IT_SEARCH_PARAM range table (in the SEARCH_ASSETS_BY_RANGE method) are used as filter criteria by the PIM API. The PIM API returns only those entities that match the filter criteria.

Example

The following example code shows how you can retrieve TextAssets and ImageAssets related to any product with the region defined as BY and the country as DE:

Figure 3: PIM API Example Code

Demo Data

The PIM API comes with the PIM_DEMO_DATA test data container (TDC). The TDC contains demo data for the CL_PIM_CLIENT_DEMO client in the PIMAPI package.

By default, you can use the TDC to test or show the functions of the PIM API without having to set up the full PIM environment. The only requirement is that the PIM API be installed and customized in an SAP system. When using the TDC, you can use the included demo data, or input your own data.