EntityManagerService
| Plug-in | com.priint.pubserver.entitydata.service.EntityDataService |
| Type | Service |
| Description | Implements a RESTful web interface to read data from entity manager within publishing server. |
1 Base URL
Given your publishing server exposes itself at address "pubserver.example.com".
And you installed it using default ports 80 for http and 443 for https, you can connect to the service using the following URLs:
Normal Connection
http://pubserver.example.com/EntityDataService/entitymanager
Secure Connection
https://pubserver.example.com/EntityDataService/entitymanager
2 Authentication
Every request needs to be authenticated.
Authentication should be done by BASIC_AUTH. The user has to have a valid user account within publishing server.
Send standard authorization header with your request.
GET https://pubserver.example.com/EntityDataService/entitymanager/KontosoModel/Bucket
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/xml
Content-Type: application/xml
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>
3 Getting data
Data can be retrieved via several GET endpoints. All these endpoints share the following characteristics:
- Entity model identifier must be given as part of the path
- Filtering by context properties e.g. language can be added by one or more the "context" query parameters. See the special section on "Specifying context".
- Filtering by search string - if supported by the connector - can be added by the "search" query parameter. See the special section on "Specifying search".
- Responses can be serialized as XML or JSON depending on the "Accept" header. Note: This documentation uses XML in all examples.
- Data responses are given as "data" objects defined in the XML namespace
com.priint.pubserver.plugin.entitydata/20131216. An XML schema file (xsd) for this namespace can be found in your publishing server stack folder/documention/resources/xsd. The "data" object is a simple wrapper for embedded "bucket", "cord", "text" etc. items. See the example in section "Example round-trip for getting data".
3.1 Getting buckets
Getting all root buckets
Pattern
GET /EntityDataService/entitymanager/{MODEL_ID}/Bucket?root=true
Example
GET /EntityDataService/entitymanager/KontosoModel/Bucket?root=true
Getting root buckets of special entity
Pattern
GET /EntityDataService/entitymanager/{MODEL_ID}/Bucket/{ENTITY_ID}?root=true
Example
GET /EntityDataService/entitymanager/KontosoModel/Bucket/Catalog?root=true
Getting bucket by identifier
Pattern
GET /EntityDataService/entitymanager/{MODEL_ID}/Bucket/{ENTITY_ID}/<BUCKET_ID>
Example
GET /EntityDataService/entitymanager/KontosoModel/Bucket/Category/98789124
Getting all child buckets
Pattern
GET /EntityDataService/entitymanager/{MODEL_ID}/Bucket/{PARENT_ENTITY_ID}/{PARENT_BUCKET_ID}/Bucket
Example
GET /EntityDataService/entitymanager/KontosoModel/Bucket/Category/98789124/Bucket
Child buckets of special entity
Pattern
GET /EntityDataService/entitymanager/{MODEL_ID}/Bucket/{PARENT_ENTITY_ID}/{PARENT_BUCKET_ID}/Bucket/{ENTITY_ID}
Example
GET /EntityDataService/entitymanager/KontosoModel/Bucket/Category/98789124/Bucket/Products
3.2 Getting content entities
Calls to content entities are analog to getChildBuckets - it is just another target type. We use Text as an example here. Calls to KeyValue, Price, TableData, MediaAsset are constructed the same way.
Getting all text children of a bucket
Pattern
GET /EntityDataService/entitymanager/{MODEL_ID}/Bucket/{PARENT_ENTITY_ID}/{PARENT_BUCKET_ID}/Text
Example
GET /EntityDataService/entitymanager/KontosoModel/Bucket/Products/98789124/Text
Getting specific text children of a bucket
Pattern
GET /EntityDataService/entitymanager/{MODEL_ID}/Bucket/{PARENT_ENTITY_ID}/{PARENT_BUCKET_ID}/Text/{ENTITY_ID}
Example
GET /EntityDataService/entitymanager/KontosoModel/Bucket/Products/98789124/Text/Description
If the PARENT_ENTITY_ID is unknown you can use the Wildcard * (asterisk) as in
GET /EntityDataService/entitymanager/KontosoModel/Bucket/\*/98789124/Text
This will iterate all bucket entities of the model and do a "get text children of bucket with id=98789124". This should only be done if you are sure that the identifier ranges of different entities do not overlap. This is e.g. true for entities from publishing hub db. This might not be true from others.
3.3 Getting cords
Cords are handled as a special kind of children of a bucket.
GET /EntityDataService/entitymanager/KontosoModel/Bucket/*/98789124/Cord
Corded buckets are also handled as special children of a bucket.
GET /EntityDataService/entitymanager/KontosoModel/Bucket/*/98789124/Bucket?corded=true
3.4 Specifying context
You can always add context in a special list of query params.
Supported context properties are: language, country, well, assortment, documentId, publication, targetGroup, market
Empty context properties can be omitted.
Here is an example:
GET /EntityDataService/entitymanager/KontosoModel/Bucket/category?context=language:deu&context=country:AT&context=well:Premium
3.5 Specifying search strings
You can always add a search string as query parameter.
Here is an example:
GET /EntityDataService/entitymanager/KontosoModel/Bucket/category/98789124/Text?search=Hello
How the search string is evaluated is connector specific. Please read the documentation for the connector.
3.6 Example round-trip for getting data
Here we read child buckets for the "ww1" category bucket. Children must be of the "product" entity.
Example Request
GET http://localhost:40080/EntityDataService/entitymanager/mymodel/Bucket/category/ww1/product
Accept: application/xml
Authorization: Basic \*\*\*\*\*\*\*
Example Response (abbreviated)
200
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dat:data xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" >
<dat:bucket entityBucketId="product" identifier="p0815" label="Null acht fuffzehn" sequence="0">
<dat:connectorEntity identifier="product" instance="mymodel"/>
<dat:context country="DE" />
</dat:bucket>
<dat:bucket entityBucketId="product" identifier="pMarkA" label="Whippet" sequence="1">
<dat:connectorEntity identifier="product" instance="mymodel"/>
<dat:context country="UK" />
</dat:bucket>
</dat:data>
4 Modifying data
Data can only modified via the entitymanager endpoints if the following requirement are met
- The content system allows for modification. Modification might be restricted to special user roles or IP addresses.
- The connector allows for modification and is configured appropriately. See documentation of the specific connector.
- The entity in entity model is configured appropriately. Per default at least deletion of data is NOT allowed. To enable this you must add specific tags to the entity using entity editor in ison. See next sections for details.
Data are send via variity of POST, PUT, DELETE calls.
The data formats for the different payloads are defined in the XML namespace com.priint.pubserver.plugin.entitydata/20131216. An XML schema file (xsd) for this namespace can be found in your publishing server stack folder /documention/resources/xsd.
4.1 Enable data modification in the entity model
To enable data deletion, in ison activate the following tags
em.crud:CHECK INTEGRITY OF DATA_YES- and
em.crud:DELETE_YES.
4.2 Manipulating single items
General rules
- The URI path for operations on single items always fully identify one item.
- The payload format always represents exactly one item, e.g. one
<dat:bucket/>or one<dat:keyValue/>. - The response object contains the same item in its state after the operation.
Set an item (insert or update)
PUT /EntityDataService/entitymanager/{MODEL_ID}/{ENTITY_TYPE}/{ENTITY_ID}/{RECORD_ID}
Path Parameters (required)
| Parameter | Description |
|---|---|
| MODEL_ID | Identifier of the entity model where data should be inserted or updated. |
| ENTITY_TYPE | Type of the entity that is to be inserted or updated. Any of "Bucket", "Cord", "ContentMetaData", KeyValue", "MediaAsset", "Price", "TableData", "Text". |
| ENTITY_ID | Identifier of the entity in the entity model. |
| RECORD_ID | Identifier of the actual item. Note: Identifiers containing a slash / are not supported. Also, slash is not allowed to be escaped as %2F in this case. |
Query Parameters - none -
Payload Payload must be a single item conforming to the entity data schema. E.g. <dat:bucket />
Status Codes
The call will return the following HTTP codes:
| Code | Description |
|---|---|
| 200 | Status 200 will be send on success. |
| 500 | Status 500 will indicate any problem. Details can be found in the server.log. |
Return Value The method will return the same item in its status after the operation. This is identical to updating an item.Actually PUT operates as an UPSERT method.
In the following example a text "t0815" of entity "description" will be added under bucket "p0815".
Example Request
PUT https://pubserver.example.org/EntityDataService/entitymanager/mymodel/Text/description/t0815
Content-Type: application/xml
Accept: application/xml
Authorization: Basic *******
<dat:text bucketId="p0815" entityTextId="description" identifier="t0815">
<dat:text>This is a new description under bucket p0815</dat:text>
</dat:text>
Example Response
200
Content-Type: application/xml
<dat:text bucketId="p0815" entityTextId="description" identifier="t0815" updatedOn="2019-05-23T17:54:34.195+02:00">
<dat:text>This is a new description under bucket p0815</dat:text>
<dat:connectorEntity identifier="description" instance="mymodel" />
<dat:context assortmentName="" country="" language="" wellName="" targetGroup="" marketName=""/>
</dat:text>
Update an item
PUT /EntityDataService/entitymanager/{MODEL_ID}/{ENTITY_TYPE}/{ENTITY_ID}/{RECORD_ID}
Payload must be a single item conforming to the entity data schema. E.g. <dat:bucket />
The method will return the status of the item after the operation.
This is identical to adding an item. Actually PUT operates as an UPSERT method.
For more details and for an example see previous section on "Set an item".
Delete an item
DELETE /EntityDataService/entitymanager/{MODEL_ID}/{ENTITY_TYPE}/{ENTITY_ID}/{RECORD_ID}
Path Parameters (required)
| Parameter | Description |
|---|---|
| MODEL_ID | Identifier of the entity model where data should be deleted. |
| ENTITY_TYPE | Type of the entity that is to be deleted. Any of "Bucket", "Cord", "ContentMetaData", KeyValue", "MediaAsset", "Price", "TableData", "Text". |
| ENTITY_ID | Identifier of the entity in the entity model. |
| RECORD_ID | Identifier of the actual item. Note: Identifiers containing a slash / are not supported. Also, slash is not allowed to be escaped as %2F in this case. |
Query Parameters - none -
Payload - none -
Status Codes The call will return the following HTTP codes:
| Code | Description |
|---|---|
| 200 | Status 200 will be send on success. |
| 403 | Status 403 will indicate that deletion is not allowed for the item. Most probably because it is not allowed for the entity in the model. |
| 409 | Status 409 will indicate that the item could not be deleted due to a conflict with other data. Most probable because it is still required by other data. |
| 500 | Status 500 will indicate any other problem. Details can be found in the server.log. |
Return Value The method will return a DeleteEntityStatus object unless HTTP 500.
Example Request Deleting text "t0815" of entity "description" under bucket "p0815".
DELETE https://pubserver.example.org/EntityDataService/entitymanager/mymodel/Text/description/t0815
Accept: application/xml
Authorization: Basic \*\*\*\*\*\*\*
Example Response
200
Content-Type: application/xml
<dat:text bucketId="p0815" entityTextId="description" identifier="t0815" updatedOn="2019-05-23T17:54:34.195+02:00">
<dat:text>This is a new description under bucket p0815</dat:text>
<dat:connectorEntity identifier="description" instance="mymodel" />
<dat:context assortmentName="" country="" language="" wellName="" targetGroup="" marketName=""/>
</dat:text>
4.3 Operating on multiple items at once
If you want to insert, update or delete more than one item in a single step this can be done via two special endpoints, the Data and the commit endpoint. Both use the <dat:push/> data representation as a general wrapper but they differ in which parts of the <dat:push/> are used and how the behavior can be controlled. The commit endpoint is the more modern and versatile option.
4.3.1 Posting to the "Data" endpoint
The "Data" endpoint is very similar to the endpoint of the connector specific "push" service. It takes <dat:data/> objects with embedded "bucket", "cord", "text" etc. items as input.
POST /EntityDataService/entitymanager/{MODEL_ID}/Data
Path Parameters (required)
| Parameter | Description |
|---|---|
| MODEL_ID | Identifier of the entity model where data should be deleted. |
Query Parameters - none -
Payload Payload is a <dat:data/> object. The items are given as embedded entitydata objects, e.g. <dat:bucket/> etc. See the example below.
The operation mode is always UPSERT for all items. It is strongly recommended that all items belong to one connector instance and even to one entity only. But this is not strictly required.
Status Codes The call will return the following HTTP codes:
| Code | Description |
|---|---|
| 200 | Status 200 will be send on success. |
| 500 | Status 500 will indicate any other problem. Details can be found in the server.log. |
Return Value The method will return a <dat:data/> object containing the values for all items after the operation.
Example Request Adding text "t0815" of entity "description" under bucket "p0815".
POST https://pubserver.example.org/EntityDataService/entitymanager/mymodel/Data
Content-Type: application/xml
Accept: application/xml
Authorization: Basic *******
<dat:data xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216">
<dat:text bucketId="p0815" entityTextId="description" identifier="t0815">
<dat:text>This is a new description under bucket p0815</dat:text>
</dat:text>
</dat:data>
Example Response
200
Content-Type: application/xml
<dat:data xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216">
<dat:text bucketId="p0815" entityTextId="description" identifier="t0815">
<dat:text>This is a new description under bucket p0815</dat:text>
</dat:text>
</dat:data>
4.3.2 Posting to the "commit" endpoint
The "commit" endpoint allows to send a data patch to the system. This "patch" may contain insert, update or delete commands in one transaction. Like the "Data" endpoint it takes
POST /EntityDataService/entitymanager/{MODEL_ID}/commit
Path Parameters (required)
| Parameter | Description |
|---|---|
| MODEL_ID | Identifier of the entity model where data should be changed. |
Query Parameters - none -
Payload Payload is a <dat:push/> object. The items are given as embedded <entityItem/> objects. See the example below. An operation mode MUST be given with each item.
Status Codes The call will return the following HTTP codes:
| Code | Description |
|---|---|
| 200 | Status 200 will be send on success. |
| 500 | Status 500 will indicate any other problem. Details can be found in the server.log. |
Return Value The method will return a <dat:push/> object containing the values for the items after the operation. Deleted items will of course not be part of the result.
Example Request The following example shows how to do four operations in one step:
- delete text record of entity "description" with id "t0815a"
- delete text record of entity "description" with id "t0815b"
- add a new text record of entity "description" for a parent bucket called "p0815"
- update the label of the "product" bucket of with id "0815"
Example Request
POST https://pubserver.example.org/EntityDataService/entitymanager/mymodel/commit
Content-Type: application/xml
Accept: application/xml
Authorization: Basic *******
<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216" createdOn="2019-05-23T17:54:33.811+02:00">
<entityItem command="DELETE" class="com.priint.pubserver.plugin.entitydata.Text"
entityIdentifier="description" identifier="t0815a"/>
<entityItem command="DELETE" class="com.priint.pubserver.plugin.entitydata.Text"
entityIdentifier="description" identifier="t0815b"/>
<entityItem command="INSERT" class="com.priint.pubserver.plugin.entitydata.Text"
entityIdentifier="description" identifier="t0815c">
<dat:text bucketId="p0815" entityTextId="description" identifier="t0815c">
<dat:text>This is a new description under bucket p0815</dat:text>
</dat:text><
</entityItem>
<entityItem command="UPDATE" class="com.priint.pubserver.plugin.entitydata.Bucket"
entityIdentifier="product" identifier="p0815">
<dat:patch>
<entry>
<key>label</key>
<value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Nullacht-Fünfzehn</value>
</entry>
</dat:patch>
</entityItem>
</dat:push>
Example Response
200
Content-Type: application/xml
<dat:push xmlns:dat="com.priint.pubserver.plugin.entitydata/20131216">
<entityItem command="INSERT" class="com.priint.pubserver.plugin.entitydata.Text"
entityIdentifier="description" identifier="t0815c">
<dat:context assortmentName="" country="" identifier="" language="" script="" wellName=""
publication="" documentId="" targetGroup="" marketName=""/>
<dat:text bucketId="p0815" entityTextId="description" identifier="t0815c"
updatedOn="2019-05-23T17:54:34.195+02:00">
<dat:text>This is a new description under bucket p0815</dat:text>
<dat:connectorEntity identifier="description" instance="mymodel" />
<dat:context assortmentName="" country="" language=""
wellName="" targetGroup="" marketName=""/>
</dat:text>
</entityItem>
</dat:push>
The response is a push object containing one text object (the inserted one) since after deletion two items should have disappeared from the source.
You can also see that the output contains more fields and elements since the connector may have added some defaults.
4.3.3 Posting to the "bulk-insert" endpoint
The "bulk-insert" endpoint allows to send a data patch to the system.
NOTE: It will only work for entities of Mua connector! The Mua entities have the best performance, therefore we propose to use them for performance critical import missions.
It takes <dat:push/> objects as input, but the content is not within the embedded "bucket", "cord", "text" etc. elements but within the "entityItem" elements - the same as in the case of the "commit" endpoint. The "command" attribute is ignored, it is always INSERT operation. The whole import is executed in the one db transaction, without checking whether entities exist or not. This is intended to import data for the new installation. The advantage of this approach is better performance than "commit" endpoint for inserting entities (without updating or deleting).
POST /EntityDataService/entitymanager/{MODEL_ID}/bulk-insert
Path Parameters (required)
| Parameter | Description |
|---|---|
| MODEL_ID | Identifier of the entity model where data should be changed. |
Query Parameters - none -
Payload Payload is a <dat:push/> object. The items are given as embedded <entityItem/> objects. See the example below.
Status Codes The call will return the following HTTP codes:
| Code | Description |
|---|---|
| 200 | Status 200 will be send on success. |
| 500 | Status 500 will indicate any other problem. Details can be found in the server.log. |
Return value:
None - because it is a one db transaction, status code should be checked. If it is 200, it means that all entities were imported, if not, none of them were.
4.3.4 Posting to the "bulk-upsert" endpoint
The "bulk-insert" endpoint is similar to the "bulk-insert" endpoint, but upsert operation is performed.
NOTE: It will only work for entities of Mua connector! The Mua entities have the best performance, therefore we propose to use them for performance critical import missions.
The "command" attribute is ignored, it is always UPSERT operation. The whole import is executed in the one db transaction. The advantage of this approach is better performance than "commit" endpoint for updating entities (without deleting).
POST /EntityDataService/entitymanager/{MODEL_ID}/bulk-upsert
Path Parameters (required)
| Parameter | Description |
|---|---|
| MODEL_ID | Identifier of the entity model where data should be changed. |
Query Parameters - none -
Payload Payload is a <dat:push/> object. The items are given as embedded <entityItem/> objects. See the example below.
Status Codes The call will return the following HTTP codes:
| Code | Description |
|---|---|
| 200 | Status 200 will be send on success. |
| 500 | Status 500 will indicate any other problem. Details can be found in the server.log. |
Return value:
None - because it is a one db transaction, status code should be checked. If it is 200, it means that all entities were imported, if not, none of them were.