A dedicated message queue for interacting with the Object APIs CRUD operations. The Object API supports both, JSON and XML payloads. We recommend using JSON where possible.

Queue ID	Format	Active MQ Name
objectapi	JSON/XML	P360_OBJECT_API

The object api consumer only supports Version 2 of the REST Object API

Request & Response Headers

Please see Message Queue API for details about generic message headers. This table will list only additional headers specific for this queue.

Header name	Type	Stored in	Values	Value example	Purpose
`Operation`	specific	JMS Property	CREATE READ UPDATE DELETE	CREATE	Defines which method, or operation should or has been performed with the object. This header is also included in the response message

Response Headers

Please see Message Queue API for details about generic response headers. There are no additional response headers for the object api responses

Parameters

The parameters for the CRUD operations are documented on the REST Object API Read V2 and REST Object API Write pages. Meaning and syntax are identical to the message queue based object api.

The following sections will provide examples of the payloads for JSON as well as XML

Create Operation

Request Body

Parameters

Parameter Name	Datatype	Mandatory	Default	Description
`_entity`	`String`	`true`		The identifier of the root entity
`_updateIfExists`	`boolean`	`false`	`false`	Based on this parameter an already existing entity item will be updated. In order for this to work, the identifier and container (if the entity requires one) must be part of the `_data` element
`_mimeValueArchive`	`String`	`false`		The unique ID of the uploaded mime archive file as returned from the REST File API
`_container`	`String`	`false`		Optional parameter which will set or override the container as it is defined in the JSON payload. In case of an Item, this would be a ENTITY_ITEM Syntax of a catalog, as the Catalog is the container entity of Item. This parameter is especially useful in testing scenarios in which the same payload needs to be processed repeatedly for different containers.
`_data`		`true`		The _data element contains the entity items data. Please see REST Object API Write and Payload Examples for details on the syntax.

Examples

Create Item in TestCatalog, do not update if exists (XML)

<create>
	<_entity>Article</_entity>
	<_container>'TestCatalog'</_container> 
	<_updateIfExists>false</_updateIfExists> 
	<_data>
		<identifier>identifier-1</identifier>
		<gtin>40532130000011</gtin>
		<manufacturerName>her father’s de</manufacturerName>
		<orderUnit>
			<_code>RK</_code>
		</orderUnit>
		<lang>
			<_qualification>
				<language>
					<_code>deu</_code>
				</language>
			</_qualification>
			<descriptionShort>receive no other answer, and, after a s</descriptionShort>
		</lang>
	</_data>
</create>

Create item in TestCatalog, do not update if exists (JSON)

{
  "_entity": "Article",
  "_container":"'TestCatalog'",
  "_updateIfExists": false,
  "_data" : {
    "identifier" : "identifier-1",
    "gtin" : "40532130000011",
    "manufacturerName" : "her father’s de",
    "orderUnit" : {
      "_code" : "RK"
    },
    "lang" : [ {
      "_qualification" : {
        "language" : {
          "_code" : "deu"
        }
      },
      "descriptionShort" : "receive no other answer, and, after a s"
    } ]
  }
}

Response Body

The response contains always the status code and if possible all needed information to identify the object which has been created/modified/deleted. This includes it's repository entity identifier, entityItem object, the external identifier, the container. Additionally to that, the response also contains a protocol element which contains all errors or warnings which came up during validation and persistence.

Success Response

Succeessful Response (XML)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<_writeResult>
	<_status>201</_status>
	<_entity>Article</_entity>
	<_entityItem>
		<_internalId>54991@3599</_internalId>
		<_entityId>1000</_entityId>
		<_externalId>'identifier-1'@'TestCatalog'</_externalId>
	</_entityItem>
	<_identifier>identifier-1</_identifier>
	<_container>
		<_internalId>3599</_internalId>
		<_entityId>7000</_entityId>
		<_externalId>'TestCatalog'</_externalId>
	</_container>
	<_protocol>
		<infoCounter>0</infoCounter>
		<warningCounter>0</warningCounter>
		<errorCounter>0</errorCounter>
		<entries/>
	</_protocol>
</_writeResult>

Error Response

Error Response in case the item already exists and updateIfExsits is set to false

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<_writeResult>
	<_status>400</_status>
	<_entity>Article</_entity>
	<_protocol>
		<infoCounter>0</infoCounter>
		<warningCounter>0</warningCounter>
		<errorCounter>1</errorCounter>
		<entries>
			<entry>
				<severity>ERROR</severity>
				<category>UNIQUENESS</category>
				<property></property>
				<message>The entity item already exists and can't be created twice. Provide 'updateIfExists=true' query parameter in case the object should be updated when already there: "'identifier-1'[Article]@'TestCatalog'[SupplierCatalog]" </message>
			</entry>
		</entries>
	</_protocol>
</_writeResult>

Read Operation

Request Body

Parameters

Parameter	Required	Default	Datatype	Parameter description	Example
`_entity`	yes	`none`	String	The identifier of the root entity	`<_entity>Article</_entity>`
`_entityItem`	yes, multiple entity items allowed	none	String	A list of entity items in the P360 Service API's ENTITY_ITEM syntax. If more than one item is requested, all items will be returned in a single response object.	`<_entityItem>'identifier-1'@'MASTER'</entityItem>` `<_entityItem>'identifier-2'@'MASTER'</entityItem>`
`_entityFilter`	no, multiple filters are supported!	none	`String`	A list of entity identifiers which should be part of the result. If omitted, the full object with all data is returned. We recommend to provide a list of entities which are required in order to gain performance. Note: In case an `entityFilter` is provided, also the root entity is a filter value. So by only providing the root entity as filter value, only the fields of the root level are returned in the data.	Only return the root fields: `<_entityFilter>Article</entityFilter>` Json Example: `"_entityFilter":["Article"]` Only return the root fields, and the sales prices (two _entityFilter elements!) `<_entityFilter>Article</_entityFilter><_entityFilter>ArticleLang</_entityFilter>` Json Example: `"_entityFilter":["Article", "ArticleLang"]` Only return the language specific data like Short and Long Description `<_entityFilter>ArticleLang</_entityFilter>`
`_qualificationFilter`	no, multiple filters are supported!	none	`String`	This parameter allows to restrict the output to certain qualifications. One example would be a filter so that only Euro and US-Dollar prices for the customer Informatica are returned. The filter is a list of qualification settings. A qualification setting is a qualification name followed by a comma-separated list of values which are put into parentheses. The qualification name is defined in the repository and is included in the Meta-API. See also REST List API Read for Sub Entities	Example for prices in Euro and US-Dollar and customer Informatica: `<_qualificationFilter>currency(EUR,USD)</_qualificationFilter>` `<_qualificationFilter>customer(Informatica)</_qualificationFilter>` Json Example: `"qualificationFilter":["currency(EUR,USD)","customer(Informatica)"]`
`_revision`	no	root	`ENTITY_ITEM`	The revision for which the data should be retrieved (Note that "root" is the identifier of the Working Revision, aka Head revision. The internal ID of this revision is 1)	`<_revision>'root'</_revision>` `<_revision>1</_revision>` `<_revision>'myRevisionIdentifier'</_revision>` `Json Example:` `"_revision": "'root'"`
`_includeLabels`	no	`false`	`boolean`	If set to true, the returned document will contain _label elements for all fields or qualifications which have an enumeration. The label will be returned in the locale of the request like this: `"orderUnit"` `: {` `"_current"` `: {` `"_key"` `: {` `"_entityId"` `: 3100,` `"_internalId"` `:` `"932",` `"_externalId"` `:` `"'C62'"` `},` `"_code"` `:` `"C62",` `"_label"` `:` `"piece"` `}` `}`	`<_includeLabels>true</_includeLabels>` `<_includeLabels>false</_includeLabels>`
`_includeIds`	no	`false`	`boolean`	If set to false, the payload avoids to contain any internal ids which might be system specific. This specifically applies to the ENTITY_ITEM datatype which will then no longer contain the "_internalId" element, only the "_externalId". Also the "_entityId" element will be replaced by an "entity" element which then holds the alphanumeric identifier of the entity and not it's numeric id. While reading and writing to the same Product 360 environment, we always recommend to include the ids since write performance is increased as no internal lookup needs to be done. However, when reading from one system and applying to another P360 system (different database schemas!), includeIds should be set to false, otherwise the write operation might fail since the internal ids do not match to the target system. In case the object is read for a 3rd party system, you might very well disable the internalIds to further reduce the response size!	`<_includeIds>true</_includeIds>` `<_includeIds>false</_includeIds>`
`_includeMimeValueArchive`	no	`false`	`boolean`	If set to true a ZIP Archive will be provided on the server which can be downloaded using the File API. This archive will contain all MIME_VALUE binaries of all objects which have been returned by the call to the object API. Is the single item read request is used, only the mime values for this single item are part of the archive. In case the multi-item read request is used the archive will contain the values for all items.

Examples

Read two article objects with all their data, XML

<read>
  <_entity>Article</_entity>
  <_entityItem>'identifier-1'@'TestCatalog'</_entityItem>
  <_entityItem>'identifier-2'@'TestCatalog'</_entityItem>
</read>

Read two article objects, filtered for ArticleLang sub-entity. XML

<read>
  <_entity>Article</_entity>
  <_entityItem>'identifier-1'@'TestCatalog'</_entityItem>
  <_entityItem>'identifier-2'@'TestCatalog'</_entityItem>
  <_entityFilter>ArticleLang</_entityFilter>
</read>

Read two article objects, filtered for ArticleLang sub-entity. JSON

{
    "_entity": "Article",
    "_entityItem": [
        "'identifier-1'@'TestCatalog'",
        "'identifier-2'@'TestCatalog'"
    ],
    "_entityFilter": [
        "ArticleLang"
    ]
}

Response Body

Examples

Response of 2 items, XML

<root>
	<_document>
		<_entity>Article</_entity>
		<_entityItem>
			<_entity>Article</_entity>
			<_externalId>'identifier-1'@'TestCatalog'</_externalId>
		</_entityItem>
		<_revision>
			<_entity>Revision</_entity>
			<_externalId>'root'</_externalId>
		</_revision>
		<_container>
			<_entity>SupplierCatalog</_entity>
			<_externalId>'TestCatalog'</_externalId>
		</_container>
		<_data>
			<identifier>identifier-1</identifier>
			<noCUperOU>1.0000</noCUperOU>
			<gtin>40532130000011</gtin>
			<currentStatus>
				<_code>NEW</_code>
			</currentStatus>
			<manufacturerName>BMW</manufacturerName>
			<catalog>
				<_code>TestCatalog</_code>
			</catalog>
			<quantityMin>1.0000</quantityMin>
			<mainSupplier>
				<_code>Heiler Product Manager</_code>
			</mainSupplier>
			<priceQuantity>1.0000</priceQuantity>
			<kitComponent>false</kitComponent>
			<quantityInterval>1.0000</quantityInterval>
			<kitParent>false</kitParent>
			<orderUnit>
				<_code>RK</_code>
			</orderUnit>
			<soldOnlyInKits>false</soldOnlyInKits>
			<lang>
				<_qualification>
					<language>
						<_code>deu</_code>
					</language>
				</_qualification>
				<descriptionShort>receive no other answer, and, after a s</descriptionShort>
			</lang>
			<log>
				<_qualification>
					<channel>
						<_code>HPM</_code>
					</channel>
				</_qualification>
				<modificationDate>2022-06-09T17:43:23.370Z</modificationDate>
				<creationUser>
					<_code>rest</_code>
				</creationUser>
				<modificationUser>
					<_code>rest</_code>
				</modificationUser>
				<creationDate>2022-06-09T17:15:20.560Z</creationDate>
			</log>
			<ownLog>
				<modificationDate>2022-06-09T17:43:23.383Z</modificationDate>
			</ownLog>
		</_data>
	</_document>
	<_document>
		<_entity>Article</_entity>
		<_entityItem>
			<_entity>Article</_entity>
			<_externalId>'identifier-2'@'TestCatalog'</_externalId>
		</_entityItem>
		<_revision>
			<_entity>Revision</_entity>
			<_externalId>'root'</_externalId>
		</_revision>
		<_container>
			<_entity>SupplierCatalog</_entity>
			<_externalId>'TestCatalog'</_externalId>
		</_container>
		<_data>
			<identifier>identifier-2</identifier>
			<noCUperOU>1.0000</noCUperOU>
			<gtin>40532130000011</gtin>
			<currentStatus>
				<_code>NEW</_code>
			</currentStatus>
			<manufacturerName>her fatherâ€™s de</manufacturerName>
			<catalog>
				<_code>TestCatalog</_code>
			</catalog>
			<quantityMin>1.0000</quantityMin>
			<mainSupplier>
				<_code>Heiler Product Manager</_code>
			</mainSupplier>
			<priceQuantity>1.0000</priceQuantity>
			<kitComponent>false</kitComponent>
			<quantityInterval>1.0000</quantityInterval>
			<kitParent>false</kitParent>
			<orderUnit>
				<_code>RK</_code>
			</orderUnit>
			<soldOnlyInKits>false</soldOnlyInKits>
			<lang>
				<_qualification>
					<language>
						<_code>deu</_code>
					</language>
				</_qualification>
				<descriptionShort>receive no other answer, and, after a s</descriptionShort>
			</lang>
			<log>
				<_qualification>
					<channel>
						<_code>HPM</_code>
					</channel>
				</_qualification>
				<creationUser>
					<_code>rest</_code>
				</creationUser>
				<creationDate>2022-06-09T18:03:44.880Z</creationDate>
			</log>
			<ownLog>
				<modificationDate>2022-06-09T18:03:44.910Z</modificationDate>
			</ownLog>
		</_data>
	</_document>
</root>

Response of two articles with only their ArticleLang sub-entity data, XML

<root>
	<_document>
		<_entity>Article</_entity>
		<_entityItem>
			<_entity>Article</_entity>
			<_externalId>'identifier-1'@'TestCatalog'</_externalId>
		</_entityItem>
		<_revision>
			<_entity>Revision</_entity>
			<_externalId>'root'</_externalId>
		</_revision>
		<_container>
			<_entity>SupplierCatalog</_entity>
			<_externalId>'TestCatalog'</_externalId>
		</_container>
		<_data>
			<lang>
				<_qualification>
					<language>
						<_code>deu</_code>
					</language>
				</_qualification>
				<descriptionShort>receive no other answer, and, after a s</descriptionShort>
			</lang>
		</_data>
	</_document>
	<_document>
		<_entity>Article</_entity>
		<_entityItem>
			<_entity>Article</_entity>
			<_externalId>'identifier-2'@'TestCatalog'</_externalId>
		</_entityItem>
		<_revision>
			<_entity>Revision</_entity>
			<_externalId>'root'</_externalId>
		</_revision>
		<_container>
			<_entity>SupplierCatalog</_entity>
			<_externalId>'TestCatalog'</_externalId>
		</_container>
		<_data>
			<lang>
				<_qualification>
					<language>
						<_code>deu</_code>
					</language>
				</_qualification>
				<descriptionShort>receive no other answer, and, after a s</descriptionShort>
			</lang>
		</_data>
	</_document>
</root>

Read two articles, filtered for only the ArticleLang sub-entity, JSON

{
	"_document": [
		{
			"_entity": "Article",
			"_entityItem": {
				"_entity": "Article",
				"_externalId": "'identifier-1'@'TestCatalog'"
			},
			"_revision": {
				"_entity": "Revision",
				"_externalId": "'root'"
			},
			"_container": {
				"_entity": "SupplierCatalog",
				"_externalId": "'TestCatalog'"
			},
			"_data": {
				"lang": [
					{
						"_qualification": {
							"language": {
								"_code": "deu"
							}
						},
						"descriptionShort": "receive no other answer, and, after a s"
					}
				]
			}
		},
		{
			"_entity": "Article",
			"_entityItem": {
				"_entity": "Article",
				"_externalId": "'identifier-2'@'TestCatalog'"
			},
			"_revision": {
				"_entity": "Revision",
				"_externalId": "'root'"
			},
			"_container": {
				"_entity": "SupplierCatalog",
				"_externalId": "'TestCatalog'"
			},
			"_data": {
				"lang": [
					{
						"_qualification": {
							"language": {
								"_code": "deu"
							}
						},
						"descriptionShort": "receive no other answer, and, after a s"
					}
				]
			}
		}
	]
}

Update Operation

Request Body

Parameters

Name	Datatype	Default	Description
`_entity`	String		The entity which should be updated
`_entityItem`	ENTITY_ITEM		Entity Item to be updated (see above)
`_createIfMissing`	`boolean`	`true`	Based on this parameter a missing entity item will be created with the given identifier. In order for this to work, the `externalId` must be used for the `entityItem` parameter. In case the `internalId` is used and the object is not in the system a 404 code will be returned.
`_mimeValueArchive`	`String`		The unique ID of the uploaded mime archive file as returned from the REST File API

Examples

Simple request body to update the manufacturer name of an item

Update Request, JSON

{
  "_entity": "Article",
  "_entityItem": "'identifier-1'@'TestCatalog'",
  "_createIfMissing": false,
  "_data" : {
    "manufacturerName" : "BMW"
  }
}

Update request, XML

<update>
  <_entity>Article</_entity>
  <_entityItem>'identifier-1'@'TestCatalog'</_entityItem>
  <_createIfMissing>false</_createIfMissing>
  <_data>
    <manufacturerName>BMW</manufacturerName>
  </_data>
</update>

Response Body

Examples

Success Response

Success Response, JSON

{
	"_status": 200,
	"_entity": "Article",
	"_entityItem": {
		"_internalId": "54992@3599",
		"_entityId": 1000,
		"_entity": null,
		"_externalId": "'identifier-1'@'TestCatalog'"
	},
	"_identifier": "identifier-1",
	"_container": {
		"_internalId": "3599",
		"_entityId": 7000,
		"_entity": null,
		"_externalId": "'TestCatalog'"
	},
	"_protocol": {
		"infoCounter": 0,
		"warningCounter": 0,
		"errorCounter": 0,
		"entry": [
		]
	}
}

Success Response, XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<_writeResult>
	<_status>200</_status>
	<_entity>Article</_entity>
	<_entityItem>
		<_internalId>54992@3599</_internalId>
		<_entityId>1000</_entityId>
		<_externalId>'identifier-1'@'TestCatalog'</_externalId>
	</_entityItem>
	<_identifier>identifier-1</_identifier>
	<_container>
		<_internalId>3599</_internalId>
		<_entityId>7000</_entityId>
		<_externalId>'TestCatalog'</_externalId>
	</_container>
	<_protocol>
		<infoCounter>0</infoCounter>
		<warningCounter>0</warningCounter>
		<errorCounter>0</errorCounter>
		<entries/>
	</_protocol>
</_writeResult>

Error Response

Error Response, XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<_writeResult>
	<_status>400</_status>
	<_entity>Article</_entity>
	<_entityItem>
		<_internalId>54992@3599</_internalId>
		<_entityId>1000</_entityId>
		<_externalId>'identifier-1'@'TestCatalog'</_externalId>
	</_entityItem>
	<_identifier>identifier-1</_identifier>
	<_container>
		<_internalId>3599</_internalId>
		<_entityId>7000</_entityId>
		<_externalId>'TestCatalog'</_externalId>
	</_container>
	<_protocol>
		<infoCounter>0</infoCounter>
		<warningCounter>0</warningCounter>
		<errorCounter>1</errorCounter>
		<entries>
			<entry>
				<severity>ERROR</severity>
				<category>RANGE</category>
				<property>Article_ArticleType.ManufacturerName</property>
				<message>Manufacturer: The text 'This is a way too long manufacturer Name as onl...' exceeds the maximum length; it can be a maximum of 50 characters long. (Currently: 90 characters)</message>
			</entry>
		</entries>
	</_protocol>
</_writeResult>

Delete Request

A request which can delete a single entity item. Equivalent to REST List API Delete

Request Body

Parameters

Name	Datatype	Default	Description
`_entity`	String		The entity of the object which should be deleted
`_entityItem`	ENTITY_ITEM		Entity Item to be deleted

Delete an object, JSON

{
    "_entity": "Article",
    "_entityItem": "'identifier-2'@'TestCatalog'"
}

Response Body

Example

Successful deletion response, JSON

{
	"_status": 200,
	"_entity": "Article",
	"_entityItem": {
		"_internalId": "54995@3599",
		"_entityId": 1000,
		"_externalId": "'identifier-2'@'TestCatalog'"
	},
	"_identifier": "identifier-2",
	"_container": {
		"_internalId": "3599",
		"_entityId": 7000,
		"_externalId": "'TestCatalog'"
	}
}

Successful deletion, XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root>
	<_status>200</_status>
	<_entity>Article</_entity>
	<_entityItem>
		<_internalId>55557@3599</_internalId>
		<_entityId>1000</_entityId>
		<_externalId>'identifier-2'@'TestCatalog'</_externalId>
	</_entityItem>
	<_identifier>identifier-2</_identifier>
	<_container>
		<_internalId>3599</_internalId>
		<_entityId>7000</_entityId>
		<_externalId>'TestCatalog'</_externalId>
	</_container>
</root>