PushService


Plug-in	`com.priint.pubserver.entitydata.service.PushService`
Type	Service
Description	Implements a RESTful web interface to import entity data objects via connector into the underlying data source. Currently PublishingHubDBConnector and MuaConnector can be used.

Base URL by example

http://pubserver.example.org:8080/EntityDataService/push

Authentication should be by BASIC_AUTH. The user must have a valid account for publishing server.

Data modifications methods use the following formats defined in PubServerSDK:

Input: ConnectorPersistRemote.PushData
Output: ServiceResult

Input and output will be serialized as XML.

In case of errors a ServiceResult object will be returned along with the HTTP status code (in most cases 500) containing exception details.

1 Use Cases

The typical use case for PushService is, when no connector for the content system exist, but the content system is able to push data to publishing server.

Instead PublishingHubDBConnector or MuaConnector will be used and data will be staged in PublishingHubDB on side of publishing server.

If data changes in content system the content system will trigger a RESTful call to publishing server. publishing server will then modify the data in PublishingHubDB accordingly.

The publishing project will use an EntityModel bound to an instance of PublishingHubDBConnector or MuaConnector.

The exact mechanism of triggering is outside the scope of this document. It depends on the content system and the project requirements.

You may think of a programmed database trigger directly calling the RESTful service.
You may also think of a service tier method exporting modified data into a hot folder in some file system; a small server app may watch the hot folder and start RESTful calls to publishing server on every file addition.

Many other scenarios are possible.

1.1 PushService versus Import

You may also import data via the UI of the publishing planner. Publishing planner allows to upload a file for an import job. Executing the import job will trigger the internal interface of the PushService or the PublishinghubDBConnector or MuaConnector directly to process the data.

In comparison to this kind of import the PushService Restful API is intended to be used by other machines automatically. Although the format allows to process huge data sets with the service it is best recommended to push only small bits of data through this service on each request.

1.2 PushService versus EntityManagerService

EntityManagerService is another alternative for pushing data to publishing server. It is also a RESTful interface but in comparison to PushService, it does not interact with the connectors directly but via the EntityManager. Both services use different methods on the connectors. PushService does not require an entity model already existing in the publishing server. PushService allows to push data for entities not already defined.

If possible use the EntityManagerService.

2 Base URL

Given your server DNS name is pubserver.example.com and you have a default installation using port 80 or 443, you can connect to the service using the following URLs:

Insecure Connection:

http://pubserver.example.com:80/EntityDataService/push

Secure Connection:

https://pubserver.example.com:443/EntityDataService/push

3 Authentication

Every request needs to be authenticated.

Authentication should be by BASIC_AUTH. The user must have a valid account within publishing server.

Send standard authorization header with your request.

GET http://pubserver.example.com:8080/EntityDataService/push/data
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/xml
Content-Type: application/xml

<push:data>...</push:data>

If login fails (e.g. credentials are wrong) you will get a 401 Status Code.

HTTP 401
WWW-Authenticate: Basic Realm="Pubserver"
Content-Type: application/xml

<serviceResult>...</serviceResult>

For compatibility reasons PushService still allows authentication via SessionId. This is deprecated since 4.1.6 and might by removed in the upcoming versions.

For authentication via SessionId you first have to login into the service. A successful login request will respond with a session id (as response body as well as within a cookie).

You then must send a cookie named PubServSessID containing the sessionId with every request (see Constants.PUBSERVER_SESSSION_NAME).

On end of the session you should logout from the service using the logout URL.

4 RESTful Methods

Recommended endpoint /data

Verb	Path	Query Arguments	Request Body	Response
POST	`/data`	instance, source	PushData object serialized as XML.	ServiceResult object serialized as XML
PUT	`/data`	instance, source	PushData object serialized as XML.	ServiceResult object serialized as XML
DELETE	`/data`	instance, source	PushData object serialized as XML.	ServiceResult object serialized as XML
GET	`/data`	instance, source	PushData object serialized as XML.	ServiceResult object serialized as XML

Other endpoints or methods Login, Logout are only used in conjunction with SessionID based authentication. The "/command" endpoint is supported for backward compatibility to earlier specifications.

Verb	Path	Query Arguments	Request Body	Response
GET	`/login`	user, password	n.a	ServiceResult object serialized as XML containing new session id
GET	`/logout`	-	n.a	ServiceResult object serialized as XML containing expired session id
POST	`/command`	instance, source, command	PushData object serialized as XML.	ServiceResult object serialized as XML
POST	`/clear-caches`	instance	empty	ServiceResult object serialized as XML

5 Input Parameters and Output

5.1 Input Parameters

There exist some common query parameters for most URLs.

Name	Description
instance	The instance of the connector. Default is "default" which is just fine for systems using only one publishing hub db. Parameter is set to entity only if instance is not set yet.
source	An arbitrary string identifying all data imported via this call. Typically a name for the system or process doing the pushes. E.g. "MyContentSystem-A" This can later be used to infer an entity model via ison or to do raw operations on the database.
command	Name of the command to be run: `INSERT`, `UPDATE`, `DELETE`. This is not needed if you use the standard HTTP verbs `POST`, `PUT`, `DELETE` on the `/data` endpoint. It refers only to the `/command` endpoint.
connector	MappedName of the connector. There are two options: `com.priint.pubserver.connector.jpa.api.PublishingHubDBConnector` or `com.priint.pubserver.connector.mua.MuaConnector`. `PublishingHubDBConnector` is the default. Please note, that for persisting Content Metadata the `MuaConnector` must be used.

5.2 Request Body - PushData Object

The request body (or payload) of the RESTful methods is always an XML document. This XML document contains the data items (Buckets, KeyValues, Prices etc.) that have to inserted, modified, or removed.

The entity data items are wrapped within a "push data" object. The XML format of entity data is defined by the following XML schema: com.priint.pubserver.plugin.entitydata_20131216.xsd The schema is available within every publishing server update zip. See document/resource/xsd within the zip.

If you are new to entity modelling within publishing server please read What is an Entity Model. Detailed descriptions of the fields supported by the entity items are given in the JavaDoc of PubServerSDK. You find the relevant classes in the package com.priint.pubserver.plugin.entitydata.

Example:

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216">
  <dat:bucket entityBucketId="Product" identifier="p123" label="MyProduct 1">
    <dat:context country="DE" language="deu" />
  </dat:bucket>
  <dat:bucket entityBucketId="Product" identifier="p234" label="MyProduct 2">
    <dat:context country="DE" language="deu" />
  </dat:bucket>
</dat:push>

Must all fields be set?

No. Most fields allow null values, i.e. they do not need to be set in the input.

For a bucket e.g. entityBucketId, identifier are technically required. Label is also recommended on all buckets.

For context only fields different from null or empty string are required.

The connector entity is normally not needed. For Mua and for PublishingHubDB the connector entity identifier equals the specific entityId (entityBucketId, entityKeyValueId etc.).

5.3 Response Body - ServiceResult Object

All PushService methods will respond with an XML document. These XML documents are instances of the ServiceResult object. The XML format for the ServiceResult is given in the appendix.

The content of the service result differs, typically it contains a list of the data objects affected by the command. On errors the service result contains an error code in the status attribute.

Example:ServiceResult in case of successful processing (HTTP status code: 200).

<serviceResult 
  xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" 
  xmlns:ent="com.priint.pubserver.entity/20131129" 
  xmlns:con="com.priint.pubserver.config.manager/20130620" 
  success="true">
  <entries>
    <entry>
      <key>0</key>
      <value 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:type="dat:bucket" entityBucketId="Product" groupIdentifier="" identifier="Bucket_6.1" label="MyProduct" origin="DemoPIM" 
        sequence="0" template="" timestamp="" version=""> 
        <dat:context assortmentName="" country="DE" identifier="deu-DE--" language="deu" script="" wellName="" createdBy="" updatedBy="">
      </value>
    </entry>
  </entries>
</serviceResult> 

Example: ServiceResult in case of failure (typically HTTP status code: 500)

<serviceResult 
  exception="com.priint.pubserver.plugin.exception.ConnectorException" status="300" success="false"
  xmlns:con="com.priint.pubserver.config.manager/20130620" xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216"
  xmlns:ent="com.priint.pubserver.entity/20131129">
  <value>CONNECTOR: com.priint.pubserver.plugin.entitydata.KeyValue|KeyValue_6.3 already exists!</value>
</serviceResult>

6 Example Roundtrips

As an example for a successful request see this raw HTTP protocol for an insert command.

Request

POST http://localhost:41080/EntityDataService/push/data?instance=default
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/xml
Accept: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1" label="MyProduct" >
    <dat:context country="DE" language="deu"/>
  </dat:bucket>
</dat:push>

Response

200
Date: Tue, 07 Jun 2016 07:35:21 GMT
Content-Length: 686
Content-Type: application/xml
Server: GlassFish Server Open Source Edition 3.1.2.2
X-Powered-By: Servlet/3.0 JSP/2.2 (GlassFish Server Open Source Edition 3.1.2.2 Java/Oracle Corporation/1.7)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<serviceResult xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" xmlns:ent="com.priint.pubserver.entity/20131129"
  xmlns:con="com.priint.pubserver.config.manager/20130620" success="true">
  <entries>
    <entry>
      <key>0</key>
      <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="dat:bucket" entityBucketId="Product" groupIdentifier="" identifier="Bucket_6.1" 
        label="MyProduct" origin="DemoPIM" sequence="0" template="" timestamp="" version="">
        <dat:context assortmentName="" country="DE" identifier="deu-DE--" language="deu" script="" wellName="" createdBy="" updatedBy=""/>
      </value>
    </entry>
  </entries>
</serviceResult>

As an example for a not successful request see this raw HTTP protocol for a login command.

Request

GET http://localhost:41080/EntityDataService/push/login?password=werk2admin&user=admin
Accept: application/xml

Response

401
Date: Tue, 07 Jun 2016 07:12:52 GMT
Content-Type: application/xml
Server: GlassFish Server Open Source Edition 3.1.2.2
Transfer-Encoding: chunked
X-Powered-By: Servlet/3.0 JSP/2.2 (GlassFish Server Open Source Edition 3.1.2.2 Java/Oracle Corporation/1.7)

<serviceResult exception="com.priint.pubserver.exception.InvalidSessionException" status="0" success="false">
<value>
Submitted credentials for token [com.priint.pubserver.auth.realm.PubServerAuthenticationToken - basic, rememberMe=true] did not match the expected credentials.
</value></serviceResult>

7 Methods in Detail

7.1 Insert Entity Data

Java Interface

public com.priint.pubserver.webservice.ServiceResult pushInsert(java.lang.String instance, java.lang.String source, com.priint.pubserver.plugin.interfaces.ConnectorPersistRemote.PushData
data) throws com.priint.pubserver.exception.PubServerException;

This will create (insert/persist) all entitydata from the data input that are not already existing in the connector data source.

URL by example

POST /EntityDataService/push/data?instance=default&source=MegaMarket

Request body is a push data object serialized as XML or JSON.

Parameters:

instance - Name of the connector instance. Different instances are typically associated with different data sources.
source - Name of originator of the data. Currently not in use.
connector - Optional, mappedName of connector, com.priint.pubserver.connector.jpa.api.PublishingHubDBConnector (default) or com.priint.pubserver.connector.mua.MuaConnector
data - Data to be processed. Will try to create all entitydata objects referenced by identifier.

Returns:

Returns a DataMap object.

Throws:

com.priint.pubserver.entitydata.service.ServiceException - If anything fails HTTP error 500 will be send. Exception data will be returned to the client in a PubServerExceptionInfo.
com.priint.pubserver.exception.PubServerException

7.2 Update Entity Data via Connector

Java Interface

public com.priint.pubserver.webservice.ServiceResult pushUpdate(java.lang.String instance, java.lang.String source, com.priint.pubserver.plugin.interfaces.ConnectorPersistRemote.PushData data) throws com.priint.pubserver.exception.PubServerException

Will update (merge) all entitydata from the data input that are already existing in the connector data source.

URL by example

PUT /EntityDataService/push/data?instance=default&source=MegaMarket

Request body is a push data object serialized as XML or JSON.

Parameters:

instance - Name of the connector instance. Different instances are typically associated with different data sources.
source - Name of originator of the data. Currently not in use.
connector - Optional, mappedName of connector, com.priint.pubserver.connector.jpa.api.PublishingHubDBConnector (default) or com.priint.pubserver.connector.mua.MuaConnector
data - Data to be processed. Will try to update all entitydata objects referenced by identifier.

Returns:

Returns a DataMap object.

Throws:

com.priint.pubserver.entitydata.service.ServiceException - If anything fails HTTP error 500 will be send. Exception data will be returned to the client in a PubServerExceptionInfo.
com.priint.pubserver.exception.PubServerException

7.3 Delete Entity Data via Connector

Warning: Since Payara 5 DELETE requests are not allowed to have a payload. Glassfish 3 allowed this. Therefore, the request will create 400 Bad Request ERROR on 4.1.5 and later priint:suite versions. Changing Payaras configuration setting the flag allow-payload-for-undefined-http-methods to true for the listener will help, but we cannot recommend this. Instead you might use the POST way described below in 7.4 or use DELETE with the EntityManagerService.

Java Interface

public com.priint.pubserver.webservice.ServiceResult pushDelete(
 java.lang.String instance, 
 java.lang.String source, 
 com.priint.pubserver.plugin.interfaces.ConnectorPersistRemote.PushData data
) 
throws com.priint.pubserver.exception.PubServerException

Deletes data from the connector's data source.

URL by example

DELETE /EntityDataService/push/data?instance=default&source=MegaMarket

Request body is a push data object serialized as XML or JSON. Serialized form can be sparse - only identifier attributes of buckets, texts, etc must be specified.

Parameters:

instance - Name of the connector instance. Different instances are typically associated with different data sources.
source - Name of originator of the data. Currently not in use.
connector - Optional, mappedName of connector, com.priint.pubserver.connector.jpa.api.PublishingHubDBConnector (default) or com.priint.pubserver.connector.mua.MuaConnector
data - Data to be processed. Will try to delete all entitydata objects referenced by identifier.

Returns:

Returns a PushData2 object. If case of success PushData2#isSuccess() attribute will be set to true. In case of failure PushData2#isSuccess() attribute will be set to false and PushData2#getErrorCode() and PushData2#getErrorMessage() attributes will contain information about the exception.

Throws:

com.priint.pubserver.entitydata.service.ServiceException
com.priint.pubserver.exception.PubServerException

For completeness a snippet from a changed domain.xml containing the flag allow-payload-for-undefined-http-methods:

<protocol name="http-listener-1">
  <http max-connections="250" default-virtual-server="server" allow-payload-for-undefined-http-methods="true">
    <file-cache enabled="true"></file-cache>
  </http>
</protocol>

7.4 Post Entity Data via Connector Controlled by Command Parameter

This is simply a second variant of the insert/update/delete interface that was described above. It implements the first public specification of the PushService interface and is still supported for backward compatibility.

Request Body and Response behave exactly the same way in both variants.

Insert

New: POST /EntityDataService/push/data?instance=:instance&source=:source Old: POST /EntityDataService/push/command?command=INSERT&instance=:instance&source=:source

Update

New: PUT /EntityDataService/push/data?instance=:instance&source=:source Old: POST /EntityDataService/push/command?command=UPDATE&instance=:instance&source=:source

Delete

New: - Old: POST /EntityDataService/push/command?command=DELETE&instance=:instance&source=:source

Upsert (update if already existing, otherwise insert). Since 4.1 (only supported using "old" interface)

New: - Old: POST /EntityDataService/push/command?command=UPSERT&instance=:instance&source=:source

7.5 GET Entity Data by Identifier

You can use this endpoint to read data from the system. Each data object must at least described by its identifier, its entity identifier, and its context.

POST /EntityDataService/push/command?command=SELECT&instance=:instance&source=:source

Instead of using this you should consider using the EntityManagerService.

This is only needed for session based authentication. Note: Authentication by BASIC_AUTH is preferred.

Java Interface

public javax.ws.rs.core.Response getLogin(java.lang.String user, java.lang.String password) throws com.priint.pubserver.exception.InvalidSessionException

URL by example

GET /EntityDataService/push/login?user=john&password=\*\*\*\*\*

Parameters:

user- login name
password - password

Returns:

sessionID wrapped as value within a ServiceResult object

Throws:

com.priint.pubserver.exception.InvalidSessionException

7.7 GET Logout

This is only needed for session based authentication. Authentication by BASIC_AUTH is preferred.

Java Interface

public javax.ws.rs.core.Response getLogout()

Logout the currently active user by form post returns HTTP 401 if user is not logged in

URL by example

GET /EntityDataService/push/logout

Returns:

sessionid (now invalidated)

7.8 POST Clear Caches

This will clear the internal cache of the underlying connector (if supported by the connector).

Java Interface

public ServiceResult clearCaches(String instance);

URL by example

POST /EntityDataService/push/clear-caches

No response body is needed. Returns: true on success.

8 Examples

8.1 Example - Inserting one bucket with context but no subentities or content

This should result in 1 bucket and 1 context being inserted.

URL

POST /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" command="INSERT" source="DemoPIM" >
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1" label="MyProduct" sequence="0">
    <dat:context country="DE" language="deu" />
  </dat:bucket>
</dat:push>

8.2 Example - Inserting 4 buckets with 2 contexts

Inserting 4 buckets with 2 contexts, where second reference to context uses different values. This should result in 4 bucket and 2 contexts being inserted. The values for the "context002" will be country="DE" language="deu" (not country="US" language="eng", since Bucket300 will be processed before Bucket400).

URL

POST /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" command="INSERT" source="DemoPIM" >
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1a.1" label="MyProduct" >
    <dat:context identifier="6.1a1" country="DE" language="deu" />
  </dat:bucket>
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1a.2" label="MyProduct" >
    <dat:context identifier="6.1a1" country="DE" language="deu" />
  </dat:bucket>
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1a.3" label="MyProduct" >
    <dat:context identifier="6.1a2" country="DE" language="deu" />
  </dat:bucket>
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1a.4" label="MyProduct" >
    <dat:context identifier="6.1a2" country="US" language="eng" />
  </dat:bucket>
</dat:push>

8.3 Example - Insert one MediaAsset linked to a bucket

Inserting 1 asset containing a context and one media object. Running on an empty data target, this should result in 1 asset, 1 contexts and one object being inserted.

URL

POST /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:mediaAsset bucketId="Bucket_6.1" entityMediaAssetId="ProductImage" identifier="MediaAsset_6.2" label="ProductImageFirst">
    <dat:context country="DE" language="deu" />
    <dat:mediaObject identifier="MediaAsset_6.2a" filename="ProductImageFirst.eps" path="C:/images" />
  </dat:mediaAsset>
</dat:push>

8.4 Example - Insert KeyValues with a RefKeyValue

Inserting 2 key values containing a context. The second key value references a refKeyValue.

Requires bucket 6.1 already existing.

This will result in 3 key values and 1 contexts being inserted.

URL

POST /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:keyValue identifier="KVUnit_6.3" key="inch" keyLabel="Inch" keySymbol="&amp;amp;quot;">
    <dat:context country="DE" language="deu" />
  </dat:keyValue>
  <dat:keyValue bucketId="Bucket_6.1" dataType="" entityKeyValueId="TechnicalAttribute" identifier="KeyValue_6.3" 
    key="length" keyLabel="Length" refKeyValueId="KeyValueUnit_6.3" value="10" keySymbol="l" >
    <dat:context country="DE" language="deu" />
  </dat:keyValue>
</dat:push>

8.5 Example - Inserting KeyValues with Metadata

Inserting 2 key values containing a context. The second key value references the first refKeyValue and contains 2 metaData.

Requires bucket 6.1 already existing.

This should result in 2 key values and 2 metadata being inserted.

URL

POST /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:keyValue identifier="KVUnit_6.4" key="inch" keyLabel="Inch" keySymbol="&amp;amp;quot;">
    <dat:context country="DE" language="deu" />
  </dat:keyValue>
  <dat:keyValue bucketId="Bucket_6.1" entityKeyValueId="TechnicalAttribute" identifier="KeyValue_6.4" 
    key="length" keyLabel="Length" refKeyValueId="KeyValueUnit_6.4" value="15" keySymbol="l" >
    <dat:context country="DE" language="deu" />
    <dat:metaData identifier="KVMeta_6.4a" key="additionalValue1" keyLabel="MetaData for TA" value="1000" />
    <dat:metaData identifier="KVMeta_6.4b" key="additionalValue2" keyLabel="MetaData for TA" value="2000" />
  </dat:keyValue>
</dat:push>

8.6 Example - Insert a bucket with media assets and keyvalue with refKeyvalue

Insert one bucket with two MediaAssets and a subbucket with one KeyValue. This requires that Bucket_6.1 and KeyValueUnit_6.3 are already existing in the system.

URL

POST /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.5" label="MyProduct">
    <dat:context country="DE" language="deu" />
    <dat:mediaAsset entityMediaAssetId="ProductImage" identifier="MediaAsset_6.5a" label="ProductImageFirst" >
      <dat:context country="DE" language="deu" />
      <dat:mediaObject filename="ProductImageFirst.eps" identifier="MediaObject_6.5a" path="C:/images" />
    </dat:mediaAsset>
    <dat:mediaAsset entityMediaAssetId="Logo" identifier="MediaAsset_6.5b" label="CompanyLogo" >
      <dat:context country="DE" language="deu" />
      <dat:mediaObject filename="logo.eps" identifier="MediaObject_6.5b" path="C:/logos" />
    </dat:mediaAsset>
    <dat:subBucket entityBucketId="Article" identifier="Bucket_6.5a" label="MyArticleOne">
      <dat:context country="DE" language="deu" />
      <dat:keyValue entityKeyValueId="TechnicalAttribute" identifier="KeyValue_6.5a" key="length"
        keyLabel="Length" refKeyValueId="KeyValueUnit001" value="10" keySymbol="l" >
        <dat:context country="DE" language="deu" />
      </dat:keyValue>
      <dat:mediaAsset entityMediaAssetId="ArticleImage" identifier="MediaAsset_6.5c" label="ArtcleImageOne" >
        <dat:context country="DE" language="deu" />
        <dat:mediaObject filename="ArticleImageOne.eps" identifier="MediaObject_6.5c" path="C:/images" />
      </dat:mediaAsset>
      <dat:mediaAsset entityMediaAssetId="ArticleImage" identifier="MediaAsset_6.5d" label="ArtcleImageTwo" >
        <dat:context country="DE" language="deu" />
        <dat:mediaObject filename="ArtcleImageTwo.eps" identifier="MediaObject_6.5d" path="C:/images" />
      </dat:mediaAsset>
    </dat:subBucket>
    <dat:subBucket entityBucketId="Article" identifier="Bucket_6.5b" label="MyArticleTwo">
      <dat:context country="DE" language="deu" />
      <dat:keyValue entityKeyValueId="TechnicalAttribute" identifier="KeyValue_6.5b" key="length"
        keyLabel="Length" refKeyValueId="KeyValueUnit_6.3" value="15" keySymbol="l" >
        <dat:context country="DE" language="deu" />
        <dat:metaData identifier="KVMeta_6.5a" key="additionalValue1" keyLabel="MetaData for TA" value="1000" />
        <dat:metaData identifier="KVMeta_6.5b" key="additionalValue2" keyLabel="MetaData for TA" value="2000" />
      </dat:keyValue>
    </dat:subBucket>
  </dat:bucket>
</dat:push>

8.7 Example - Insert bucket with child buckets and all type of content items

URL

POST /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- 
 Example 6.6
 Insert one bucket with two child Buckets, Cords, MediaAssets, Prices, Tables, Texts.
 Requires Bucket_6.1 and KeyValueUnit_6.3
 -->
<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216"
 command="INSERT" source="DemoPIM" identifier="6.6 Insert one bucket with two of each type of children" >
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.6" label="MyProduct_6.6 Äöüß ｶ ︽ || Ae oe ue ss [ff76] [fe3d]">
    <dat:context country="DE" language="deu" />
    <dat:subBucket entityBucketId="ForCords" identifier="Bucket_6.6a" label="ForCords_6.6a" />
    <dat:subBucket entityBucketId="ForCords" identifier="Bucket_6.6b" label="ForCords_6.6b" />
    <dat:mediaAsset entityMediaAssetId="ProductImage" identifier="MediaAsset_6.6a" label="ProductImageFirst Äöüß ｶ ︽ || Ae oe ue ss [ff76] [fe3d]">
      <dat:context country="DE" language="deu" />
      <dat:text identifier="Text_6.6a1" text="Front" />
      <dat:text identifier="Text_6.6a2" text="Detail" />
      <dat:mediaObject filename="ProductImageFirst_6.6a1.eps" identifier="MediaObject_6.6a1" path="C:/images/6.6a1" />
      <dat:mediaObject filename="ProductImageFirst_6.6a2.eps" identifier="MediaObject_6.6a2" path="C:/images/6.6a2" />
    </dat:mediaAsset>
    <dat:mediaAsset entityMediaAssetId="ProductImage" identifier="MediaAsset_6.6b" label="ProductImageFirst">
      <dat:context country="DE" language="deu" />
      <dat:text identifier="Text_6.6b1" text="Front" />
      <dat:text identifier="Text_6.6b2" text="Detail" />
      <dat:mediaObject filename="ProductImageFirst_6.6b1.eps" identifier="MediaObject_6.6b1" path="C:/images/6.6b1" />
      <dat:mediaObject filename="ProductImageFirst_6.6b2.eps" identifier="MediaObject_6.6b2" path="C:/images/6.6b2" />
    </dat:mediaAsset>
    <dat:price entityPriceId="Price" identifier="Price_6.6a" label="Price1" price="1.99" validFrom="2019-01-01T00:00:00+01:00">
      <dat:context country="DE" language="deu" />
    </dat:price>
    <dat:price entityPriceId="Price" identifier="Price_6.6b" label="Priceb" price="2.99" validFrom="2019-01-01T00:00:00+01:00">
      <dat:context country="DE" language="deu" />
    </dat:price>
    <dat:text entityTextId="Text" identifier="Text_6.6a" text="Text1" >
      <dat:context country="DE" language="deu" />
    </dat:text>
    <dat:text entityTextId="Text" identifier="Text_6.6b" text="Text2" >
      <dat:context country="DE" language="deu" />
    </dat:text>
    <dat:tableData identifier="TableData_6.6_1" entityTableDataId="TableData" >
      <dat:context country="DE" language="deu" />
      <dat:row identifier="TableRow_6.6_1.1" tableDataId="TableData_6.6_1">
        <dat:context country="DE" language="deu" />
        <dat:cell identifier="TableCell_6.6_1.1.1" tableDataId="TableData_6.6_1"/>
        <dat:cell identifier="TableCell_6.6_1.1.2" tableDataId="TableData_6.6_1"/>
      </dat:row>
      <dat:row identifier="TableRow_6.6_1.2" tableDataId="TableData_6.6_1">
        <dat:context country="DE" language="deu" />
        <dat:cell identifier="TableCell_6.6_1.2.1" tableDataId="TableData_6.6_1"/>
        <dat:cell identifier="TableCell_6.6_1.2.2" tableDataId="TableData_6.6_1"/>
      </dat:row>
    </dat:tableData>
    <dat:tableData identifier="TableData_6.6_2" entityTableDataId="TableData" >
      <dat:context country="DE" language="deu" />
      <dat:row identifier="TableRow_6.6_2.1" tableDataId="TableData_6.6_2">
        <dat:context country="DE" language="deu" />
        <dat:cell identifier="TableCell_6.6_2.1.1" tableDataId="TableData_6.6_2" >
          <dat:context country="DE" language="deu" />
        </dat:cell>
        <dat:cell identifier="TableCell_6.6_2.1.2" tableDataId="TableData_6.6_2" />
      </dat:row>
      <dat:row identifier="TableRow_6.6_2.2" tableDataId="TableData_6.6_2">
        <dat:context country="DE" language="deu" />
        <dat:cell identifier="TableCell_6.6_2.2.1" tableDataId="TableData_6.6_2"/>
        <dat:cell identifier="TableCell_6.6_2.2.2" tableDataId="TableData_6.6_2"/>
      </dat:row>
    </dat:tableData>
    <dat:cord entityCordId="Cord" identifier="Cord_6.6a" label="cord_6.6a" sourceBucketId="Bucket_6.6a" destinationBucketId="Bucket_6.6b">
      <dat:contentBucket entityBucketId="cordContent" identifier="ContentBucket_6.6a" label="ContentBucket_6.6a" />
    </dat:cord>
    <dat:cord entityCordId="Cord" identifier="Cord_6.6b" label="cord_6.6b" sourceBucketId="Bucket_6.6b" destinationBucketId="Bucket_6.6a">
      <dat:contentBucket entityBucketId="cordContent" identifier="ContentBucket_6.6b" label="ContentBucket_6.6b" />
    </dat:cord> 
    <dat:keyValue identifier="KeyValue_6.6_ref_a" entityKeyValueId="TechnicalAttribute" />
    <dat:keyValue identifier="KeyValue_6.6_ref_b" refKeyValueId="KeyValue_6.6_ref_a" entityKeyValueId="TechnicalAttribute" />
    <dat:keyValue identifier="KeyValue_6.6a" refKeyValueId="KeyValue_6.6_ref_b" entityKeyValueId="TechnicalAttribute" />
    <dat:keyValue identifier="KeyValue_6.6b" refKeyValueId="KeyValue_6.6_ref_b" entityKeyValueId="TechnicalAttribute" /> 
  </dat:bucket>
</dat:push>

8.8 Example - Updating bucket

Updating the buckets from the first two examples (new label, new sequence, new context).

URL

PUT /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1" label="MyProduct updated!!" sequence="999">
    <dat:context country="DE" language="deu" />
  </dat:bucket>
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1a.4" label="MyProduct updated!!" sequence="999">
    <dat:context country="DE" language="eng" />
  </dat:bucket> 
</dat:push>

8.9 Example - Removing two buckets and all subbuckets and content items

Removing two buckets by identifier and entity identifier.

URL

DELETE /EntityDataService/push/data?instance=default&source=MegaMarket

RequestBody

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:bucket identifier="Bucket_6.1" entityBucketId="Product" />
  <dat:bucket identifier="Bucket_6.4" entityBucketId="Product" />
</dat:push>

8.10 Example - Using UPSERT

Updating one bucket from the first two examples (new label, new sequence, new context) and inserting one new bucket.

URL

POST /EntityDataService/push/command?command=UPSERT&instance=default&source=MegaMarket

Request Body

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.1" label="MyProduct updated!!" sequence="999">
    <dat:context country="DE" language="deu" />
  </dat:bucket>
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.10" label="MyProduct inserted!" sequence="999">
    <dat:context country="DE" language="deu" />
  </dat:bucket> 
</dat:push>

Response Body Value will be "true" if update was processed correctly. Inserted items will be given in length.

<serviceResult success="true" xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216"
xmlns:ent="com.priint.pubserver.entity/20131129" xmlns:con="com.priint.pubserver.config.manager/20130620">
    <value>true</value>
    <entries>
        <entry>
            <key>0</key>
                <value xsi:type="dat:bucket" entityBucketId="Product" groupIdentifier="" identifier="Bucket_6.10" 
            label="MyProduct inserted!" origin="DemoPIM" sequence="0" template="" timestamp="" version="" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <dat:context assortmentName="" country="DE" identifier="deu-DE--" language="deu" script="" wellName="" 
                    createdBy="" updatedBy="" />
                </value>
        </entry>
    </entries>
</serviceResult>

8.11 Example - Using SELECT

Reading two buckets by identifier.

At least identfier, entity identifier and context must be specified for an item. Sub structures (child buckets or content entities) and all other properties will be ignored during processing.

URL

GET /EntityDataService/push/data?instance=default&source=MegaMarket``

Request Body

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" source="DemoPIM" >
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.11">
    <dat:context country="DE" language="deu" />
  </dat:bucket>
  <dat:bucket entityBucketId="Product" identifier="Bucket_6.11_not_existing">
    <dat:context country="DE" language="deu" />
  </dat:bucket>
</dat:push>

Response Body We suppose that the first is existing in the system and the second is not existing. This will lead to the result given below. Substructures (child buckets or content entities) will not be included into the results.

<serviceResult success="true" xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216"
xmlns:ent="com.priint.pubserver.entity/20131129" xmlns:con="com.priint.pubserver.config.manager/20130620">
    <entries>
        <entry>
             <key>Product:Bucket_6.11</key>
                 <value xsi:type="dat:bucket" entityBucketId="Product" groupIdentifier="" identifier="Bucket_6.11" label="MyProduct" 
            origin="DemoPIM" sequence="0" template="" timestamp="" version="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                 <dat:context assortmentName="" country="DE" identifier="deu-DE--" language="deu" script="" wellName="" createdBy="" updatedBy="" />
                     </value>
                        </entry>
                        <entry>
                             <key>Product:Bucket_6.11_not_existing</key>
                            <value />
                        </entry>
    </entries>
</serviceResult>

8.12 Example - Using MUA connector for inserting content metadata

URL

POST /EntityDataService/push/data?instance=default&source=MegaMarket&connector=com.priint.pubserver.connector.mua.MuaConnector

Request Body

<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" command="INSERT" >
    <dat:contentMetaData entityContentMetaDataId="myMetadata" identifier="metadata_Bucket_1.1-1" key="any key" value="any value" bucketId="Bucket_1.1"/>
    <dat:contentMetaData entityContentMetaDataId="myMetadata" identifier="metadata_Bucket_1.1-2" key="another key" value="another value" bucketId="Bucket_1.1"/>
</dat:push>

9 XML Schema for Service Result

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="serviceResult" type="serviceResult"/>
  <xs:complexType name="serviceResult">
    <xs:sequence>
      <xs:element name="entries">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="entry" minOccurs="0" maxOccurs="unbounded">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="key" minOccurs="0" type="xs:string"/>
                  <xs:element name="value" minOccurs="0" type="xs:anyType"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="value" type="xs:string" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="exception" type="xs:string"/>
    <xs:attribute name="method" type="xs:string"/>
    <xs:attribute name="status" type="xs:int"/>
    <xs:attribute name="success" type="xs:boolean"/>
    <xs:attribute name="uri" type="xs:string"/>
  </xs:complexType>
</xs:schema>

1 Use Cases​

1.1 PushService versus Import​

1.2 PushService versus EntityManagerService​

2 Base URL​

3 Authentication​

Deprecated: Connect via Session Cookie​

4 RESTful Methods​

5 Input Parameters and Output​

5.1 Input Parameters​

5.2 Request Body - PushData Object​

5.3 Response Body - ServiceResult Object​

6 Example Roundtrips​

7 Methods in Detail​

7.1 Insert Entity Data​

7.2 Update Entity Data via Connector​

7.3 Delete Entity Data via Connector​

7.4 Post Entity Data via Connector Controlled by Command Parameter​

7.5 GET Entity Data by Identifier​

7.6 GET Login​

7.7 GET Logout​

7.8 POST Clear Caches​

8 Examples​

8.1 Example - Inserting one bucket with context but no subentities or content​

8.2 Example - Inserting 4 buckets with 2 contexts​

8.3 Example - Insert one MediaAsset linked to a bucket​

8.4 Example - Insert KeyValues with a RefKeyValue​

8.5 Example - Inserting KeyValues with Metadata​

8.6 Example - Insert a bucket with media assets and keyvalue with refKeyvalue​

8.7 Example - Insert bucket with child buckets and all type of content items​

8.8 Example - Updating bucket​

8.9 Example - Removing two buckets and all subbuckets and content items​

8.10 Example - Using UPSERT​

8.11 Example - Using SELECT​

8.12 Example - Using MUA connector for inserting content metadata​

9 XML Schema for Service Result​

1 Use Cases

1.1 PushService versus Import

1.2 PushService versus EntityManagerService

2 Base URL

3 Authentication

Deprecated: Connect via Session Cookie

4 RESTful Methods

5 Input Parameters and Output

5.1 Input Parameters

5.2 Request Body - PushData Object

5.3 Response Body - ServiceResult Object

6 Example Roundtrips

7 Methods in Detail

7.1 Insert Entity Data

7.2 Update Entity Data via Connector

7.3 Delete Entity Data via Connector

7.4 Post Entity Data via Connector Controlled by Command Parameter

7.5 GET Entity Data by Identifier

7.6 GET Login

7.7 GET Logout

7.8 POST Clear Caches

8 Examples

8.1 Example - Inserting one bucket with context but no subentities or content

8.2 Example - Inserting 4 buckets with 2 contexts

8.3 Example - Insert one MediaAsset linked to a bucket

8.4 Example - Insert KeyValues with a RefKeyValue

8.5 Example - Inserting KeyValues with Metadata

8.6 Example - Insert a bucket with media assets and keyvalue with refKeyvalue

8.7 Example - Insert bucket with child buckets and all type of content items

8.8 Example - Updating bucket

8.9 Example - Removing two buckets and all subbuckets and content items

8.10 Example - Using UPSERT

8.11 Example - Using SELECT

8.12 Example - Using MUA connector for inserting content metadata

9 XML Schema for Service Result