PXH Export

The only available (configurable) near-real time (JSON) API for Contentserv:

  • Easy: Easy to use and extremely flexible.
  • API approach: Use a central near real-time API instead of building a specific export for every system.
  • Documentation: Automatically generates the up to data schema documentation of your API.
  • Performance: Great Performance to access your up to date product data.
  • No limit: Supports all Contentserv datatypes even those where other standard exports are at the limit.
  • One for all: Export Products as well as Channels or Assets with all the specifics.
  • Complex data models: Automatically embeds all needed related objects (tables, references, files) – if needed even in multiple levels with full control about every single attribute and format.
  • Push approach: Can be also used in a standard push mode to periodically push the latest product data to other systems.
  • Intelligent Delta: PXH Delta Extension also offers also a clever delta detection to return or push only if any of the related objects (also in embedded ones) contain any relevant change.

Push vs Pull approach

Defining Integrations you usually differentiate between a push or pull approach where the target system (e.g. a web shop) either has to pull the data (usually via API) or you push the latest version to them (usually via export files).
Both possibilities have advantages and disadvantages.

PXH is uniquely designed for the PULL API. But also all kind of PUSH approaches are possible out-of-the-box, e.g. using Hotfolders, FTP or even sending the content to a Webhook or a message bus.

Using the PXH Delta only a limited set of data for the real changes are offered to the system.

Push (file exchange) approach

Most Contentserv integrations are using a push approach: Product data required for the integrations are prepared / transformed for each system individually and then pushed to it – usually by exchanging files (send to a hook, hot folder, FTP, …).

As accessing data can be tricky the Contentserv specialists are preparing the data, transform them to an aligned format and push the resulting file to an other system they need to know (with on demand or regular jobs).
With this approach you have heavy logic and effort within your Contentserv team as they are responsible and have to integrate all your company interfaces to your PIM.
Your teams have to intensively align on all interfaces upfront and do all steps (incl. testing) together.
If you are increasing the amount of interfaces such an approach can get slower the more interfaces you have to manage centrally, you have to hire external specialists or you have to train everybody being a Contentserv interface specialist in the hope that they all can deal with your data model / your business rule. If there are potential future changes everybody needs to adjust the interfaces.
Overall with such an approach you are super coupled within all your systems.

If needed you can configure a PUSH approach in PXH combining a JSON API Export with a script which pushes the results to a target system or target file at any point in time.
There is already an ActiveScript available which is ready to use within Contentserv.

PXH approach

With the API approach you increase your flexibility and decouple your architecture.

You define one or multiple API endpoints exposing your data. Your integrated systems can access those APIs at any point in time (either on a daily sync or even if the application just needs specific product data real time).

PXH especially the PXH JSON API enables you for such a process.

If an additional system needs to be integrated, you can check whether any of the existing endpoints can be reused. You just have to grant your integration team access and point them to the automatically generated API documentation and the API endpoint(s). Maybe your PXH / Contentserv team just has to add a more fields for them.
Then they are ready to integrate.
If you don’t have a fitting API yet, your team can configure all required fields for this new use cases usually within one hour.

With this scenario both teams do not need to know the insights of the other system. They just use and talk with an API modeling the company business object world.

In some cases the integration should not be done via REST API. You can reuse your exports for any kind of Push approach, e.g. storing the data in a file which can be accessed via hot folder. Out-of-the-box it is also possible to push data directly by calling configurable web hooks in case of changes.

Benefits of PXH JSON

There are already plenty of possibilities to extract data (also JSON) from Contentserv:

  • Contentserv REST API
  • Contentserv Dataflow Exports
  • Contentserv Export DB
  • Contentserv Excel Export

They all have advantages and disadvantages. Most of the approaches are perfect for simple Product data. As soon as you have more complex data types it is getting more and more tricky to access the proper data. Especially if you want to access more than one level in a normalized Contentserv datamodel, you have to built multiple exports and combine the data afterwards.

The PXH had been designed with 10+ years of experience and and knowledge of the typical edge cases the flexibility of Contentserv can bring with its superpower related to exporting the data. PXH offers out of the box support for all those cases and even more. All standard Contentserv datatypes with their variations are properly handled. There is a possibility to integrate even special project specific data types if needed.

Some examples of what all is possible:

  • full access to references – especially also relation attributes
  • full access to tables as embedded objects
  • embed multiple levels, e.g.
    • references with subtables
    • references with other references
    • references with other references containing information of connected Assets, …
  • handle multiple languages with one export
  • define whether to expose formatted or unformatted value (or even the External Key for Selections)
  • multi value selections are embedded as an array
  • access number with suffix properly by internally separating them
  • default values are properly applied
  • you can rename fields
  • you can transform the values
  • apply business rules to e.g. filter out specific objects for each level
  • … and much more

Overall you can configure with the Schema configurator your own API for each different use cases. You can also create bigger Schema and your interfaces access share them and use the common data they are specifically interested in.

Export Formats

At the moment PXH offers 3 different JSON types for different user groups:

  • Simple JSON Format: This is a super lightweight format. It does not contain any context and is great if you have clearly specified interfaces.
  • Generic JSON Format: This format is made for standard interfaces, where the integrators do not know Contentserv concepts and want to build an interface just with Standard object oriented data models and prefer to have included meta information about the available objects and types.
  • Contentserv JSON Format: This format was inspired by the standard Contentserv REST API. It is useful if your consumers are familiar with Contentserv and want to have a very verbose Schema.

The examples below are modeling following Contentserv object model:
Products (with ID, Label and Device as Attributes)
– Price table of the Product with ID, the Cross selling price and an Amount
– Cross Selling Reference relation of the Product (with ID, Label and Price and ValidFrom / Valid To dates)
– Variants Table of the Cross Selling Reference Products (with ID and ExternalKey, …)

Simple JSON Format

The Simple JSON is a lightweight format:

  • It contains the Object type. Then it contains the ID of the Products and then all values as Name => Value pairs. All other meta data is not visible
  • There is no differentiation between Standard Attributes, Attributes, Tables and References. All are just Name -> Value pairs directly in the object
  • Tables (Prices) are embedded as sub objects
  • References are embedded as sub objects (relation attributes and other attributes as sub sub objects)
  • Number with Suffix data can be combined or will be divided into two entries

Generic JSON Format

The Generic JSON is the best, if your Integration teams do not know Contentserv and need more verbose information about data and types than the Simple JSON can provide. It is a combination of the Contentserv and the simple format generalizing the wording and minimizing the file size.

  • It contains the generic Object type (Product).
  • Then it contains the ID of the Product, the Type („Object“ or „Collection“) and all Values.
  • Like SimpleJSON there is no differentiation between Standard Attributes, Attributes, Tables and References. All are just Key -> Value pairs directly in the Values.
  • Every Value contains a PropertyHash (reference for the field definition) or directly embedded Properties,
    a Type and then configurable Value, Formatted, UnFormatted and ValueExternalKey.
  • Tables (Prices) are embedded as sub objects with the Type „Collection“
  • References are embedded as sub objects with the Type „Collection“
  • Number with Suffix data can be combined or will be divided into two entries

At the end of the JSON there is a section Properties containing the definition of all used fields across the export with a lot of meta information. This is an extract of what you get with the Automatic Documentation.

Contentserv JSON Format

The Contentserv JSON is structured like Contentserv objects internally:

  • Standard attributes (ID, Label, State) are separated and embedded directly into the object
  • Attributes contain all their Meta data (Name, Label, Section, Type, …) as well as Value, UnFormatted, Formatted and ValueExternalKey
    –> to simplify your export, you can configure for each of those attribute values centrally in the export whether it should be included in the export
  • Tables are outside of Attributes in a separate element
  • References are outside of Attributes in a separate element
  • Number with Suffix data types contain the complete value including suffix in Formatted and the Number in Unformatted and the Unit in an Unit element.

It is a good choice, if your integration partner speaks your Contentserv language. But in most cases it is recommended to use Simple JSON or Generic JSON Format

PXH Delta Export Extension

PXH has a clever delta update detection. With the delta mode the consuming systems can request a delta to any previous call. It does not matter where there had been a change (in the data, in translations, a new field in the schema, a change in an embedded object, …), PXH will detect it and return the related objects as changes.

The „new“ section contains all objects, which had been created since the requested old version. An object is fully added to the „changed“ section, if it was existing before, but has any change.
In case an object was deleted the previous historical version is added to the „removed“ section.

There is also an alternative mode to keep the original JSON format and just return all „new“ or „changed“ objects since your reference call.

Changes can be also automatically pushed to e.g., a web hook or a message broker.

Automatic Documentation

Documentation is very important when offering APIs to other systems. A documentation is usually outdated as soon as you write it. Therefore PXH offers a call to the API to retrieve the API documentation for the REST Service.

It is available for the Contentserv and the Generic JSON format. Where both formats optionally can embed already some information in the standard output, the Schema returns all available information.

You receive:

  • All Fields which could be available in the Export in all levels are returned with a Sample Value
  • All information about the Fields, e.g.:
    • Label
    • ExternalKey
    • Pane
    • Section
    • Description
    • Type
    • Tags
    • Sort Order
    • Language Dependency information
    • Numbers: Amount of Decimals and Decimal separator, Minimum / Maximum value (if defined)
    • Date: Date format
    • Text: Amount of characters or a regular expression (if defined)
    • In the case of Selections an Enum with all available Values