The Rest Revision API allows to create revisions and add entity items to them (this process is called "release to a revision" or a revision release job. The API is available with Version 8.1.0.01 of the product

Adding objects to a revision is a performance and database storage intensive process. Essentially the object will be copied including all the objects it references. Clients and Projects must always consider if the use case really needs the revision logic. Most times the audit trail feature is sufficient!

Schedule Revision Release Job

Schedules a revision release job to be executed as soon as possible and returns the job id for the scheduled job

URL Pattern	`/manage/revision`
Example	http:// localhost:1512/rest/V2.0/manage/revision
Method	`POST`
Content types	`application/json, application/xml`
Media types	`application/json, application/xml`
Result	HTTP-202 (accepted) and the job object of the scheduled revision release job

Please note that the Revision Process will also add all entity items which are referenced from the entity items specified by the report! For example: If you add a single Item to a revision, also it's variant will be added and also the structure group the item belongs to. So, the full dependency tree will be added to the revision. It can be compared with a snapshot. In case an object has already been added to the revision and it's content didn't change meanwhile, it will not be added a second time. In case the content did change, it will be overwritten in that revision. So there is always only one copy of any object within a revision.

Query Parameters

Parameter	Required	Default	Datatype	Parameter description
`workflowServiceEndpoint`	`no`		`String`	Informatica BPM callback parameter. Defines the name of the service endpoint which must be available in an attached Informatica BPM instance.
`workflowCorrelationId`	`no`		`String`	Informatica BPM callback parameter. An arbitrary id which is used by the Informatica BPM workflow to identify the correct workflow process.
`workflowCommunicationMode`	`no`	`REST`	`REST/QUEUE`	Informatica BPM callback parameter. Defines the communication mode which can be using JMS message queue and REST communication.
`workflowQueueId`	`no`	`First trigger queue id in server.properties`	`String`	Informatica BPM callback parameter. An queue id defined in the server properties in the message queue section which is used as response queue

Workflow Callback

If a revision job is scheduled with a workflowServiceEndpoint parameter, a callback is given to the Informatica BPM server.

This call will include data about the job itself

An example callback body to the service endpoint of Informatica BPM if a workflow service endpoint parameter has been specified.

Workflow Callback Example XML

<jobFinished>
 <jobId>35</jobId>
 <stateIdentifier>finished.info</stateIdentifier>
 <stateLabel>Finished</stateLabel>
</jobFinished>

Workflow Callback (since 10.0)

It is possible to add the query parameters workflowQueueServiceEndpoint and workflowQueueId and workflowCommunicationMode which allows to specify that the response is send via the message queue. The workflowServiceEndpoint is send back as JMS property P360TargetService which allows BPM to call workflow endpoints. The workflowQueueId parameter specifies a queue configured in the server.properties with syntax "queue.[queueId].name".

Content

The content has to be a JSON/XML object which includes the properties listed below.

Field	Required	Default	Datatype	Parameter description
revision	yes		EntityItem	The revision to add objects to. The revision will be created in case it does not already exist. Otherwise it will be used and the objects will be just added to it
entityReportQuery	yes		`EntityReportQuery`	An entity report query which allows to use the available reports like 'byCatalog', 'byItems'... (Since 8.0.03)

Entity Report Query

The items to be released into the revision must be defined by an entity report query. For this you can use all available entity reports of the system. What reports are available can differ from Product 360 to Product 360 installation and therefore are documented by the Service API itself. The documentation can be obtained using the List Info API.

The EntityReportQuery also allows to define an optional assortment.

Parameter	Required	Default	Datatype	Parameter description
identifier	yes		String	Identifier of the entity report
entityIdentifier	yes		String	The unique identifier of the root entity
parameterList	no		Parameter	A list of parameters, each having a key and the value. Which parameters are supported or required for which entity report can be obtained with the List Info API.
assortmentFilter	no		EntityItem	An entity item representation of an assortment. The assortment's item entity must match with the entity of the items the report returns. Additionally to that, also the item parent must match. For example, it's no allowed to query all items of a Catalog "Henri" and specifying an assortment which is bound to the master catalog. You will receive an appropriate error message in case the assortment does not fit.
updateAssortment	no	false	Boolean	This parameter works only in combination with the `assortment` parameter. If set to `true` the given assortment will be updated before it is used. Please note that updating an assortment might be a performance intensive task, so take care when using this parameter and think about it if you really need to have the assortment evaluated every time.

JSON Examples

Using byCatalog report query with an assortment

POST /rest/V2.0/manage/revision

{
 "revision": "'MyRevisionIdentifier'",
 "entityReportQuery": {
  "identifier": "byCatalog",
  "entityIdentifier": "Article",
  "parameterList": [{
   "key": "catalog",
   "value": "'Apparel'"
  }],
  "assortmentFilter": "4711",
  "updateAssortment": false
 }
}

Using byItems report query

Note: the items must have the same container, it is not possible to specify items from multiple catalogs

POST /rest/V2.0/manage/revision

{
 "revision": "'MyRevisionIdentifier'",
 "entityReportQuery": {
  "identifier": "byItems",
  "entityIdentifier": "Article",
  "parameterList": [{
   "key": "items",
   "value": "'Article1'@'CatalogIdentifier',123@1000"
  }]
 }
}

Using bySearch report query

Note: the items must have the same container, it is not possible to specify items from multiple catalogs

POST /rest/V2.0/manage/revision

{  
 "revision": "'MyRevisionIdentifier'",
 "entityReportQuery":{   
  "identifier":"bySearch",  
  "entityIdentifier":"Article",
  "parameterList":
   [{        
   "key":"query",  
   "value":"Article.EAN in ( \"1234\" , \"1235\" )" 
   },{
   "key":"catalog",  
   "value":"'TestCatalog'"
   }]  
} 

Example with the Rest Client API

Schedule revision of the full "TOOLS" catalog

Java Client API: Merge full

EntityItemReference catalog = EntityItemReferenceFactory.createByIdentifier( "TOOLS" );
ReportQuery reportQuery = new ReportQuery( "byCatalog" );
reportQuery.addParameterValue( "catalog", catalog );
 
RevisionRequest request = getRestClient().createRevisionRequest();
RevisionResult result = request.scheduleRevisionJob( "Article", reportQuery );

Result

A result object containing the entity item of the job

Field	Data type	Description
job	EntityItem	The job entity item

Example of the result in JSON

{
  "id": "20045",
  "label": "com.heiler.ppm.revision.jobType_20045"
}

Get Revision Job Information

Returns current job information about a revision job including the protocol of the job

URL Pattern	`/manage/revision/{jobId}`
Example	http://localhost:1512/rest/V2.0/manage/revision/20045
Method	GET
Content types	`application/json, application/xml`
Media types	`application/json, application/xml`
Result	HTTP-200 (ok) and the job information object about the current state of the release job
	HTTP-404 (not found) in case the job id does not exist or is not a revision release job

Result

Example of the result in JSON

{
    "id": 20045,
    "jobType": "com.heiler.ppm.revision.jobType",
    "jobGroup": "DataMaintenanceGroup",
    "user": "rest",
    "creationTime": "2018-01-05T15:07:35:920+0100",
    "modificationTime": "2018-01-05T15:07:36:470+0100",
    "scheduledAt": "2018-01-05T15:07:35:920+0100",
    "currentState": "finished.info",
    "progress": 100,
    "serverIdentifier": "pim-server1",
    "problemLogIdentifier": "com.heiler.ppm.revision.jobType_20046_20046",
    "protocol": {
        "infoCounter": 1,
        "warningCounter": 0,
        "errorCounter": 0,
        "entries": [
            {
                "objectType": "Item",
                "severity": "INFO",
                "category": "SUMMARY",
                "message": "1 objects released in 200 ms",
                "logDate": "2018-01-05",
                "logTime": "15:07:36"
            }
        ]
    }
}

Example of the result in XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<revisionJobInfo>
    <id>20045</id>
    <jobType>com.heiler.ppm.revision.jobType</jobType>
    <jobGroup>DataMaintenanceGroup</jobGroup>
    <user>rest</user>
    <creationTime>2018-01-05T15:07:35:920+0100</creationTime>
    <modificationTime>2018-01-05T15:07:36:470+0100</modificationTime>
    <scheduledAt>2018-01-05T15:07:35:920+0100</scheduledAt>
    <currentState>finished.info</currentState>
    <progress>100</progress>
    <serverIdentifier>pim-server1 (DEW1PC05KDRB IP: 10.43.104.101)</serverIdentifier>
    <problemLogIdentifier>com.heiler.ppm.revision.jobType_20046_20046</problemLogIdentifier>
    <protocol>
        <infoCounter>1</infoCounter>
        <warningCounter>0</warningCounter>
        <errorCounter>0</errorCounter>
        <entries>
            <entry>
                <objectType>Item</objectType>
                <severity>INFO</severity>
                <category>SUMMARY</category>
                <message>1 objects released in 200 ms</message>
                <logDate>2018-01-05T00:00:00+01:00</logDate>
                <logTime/>
            </entry>
        </entries>
    </protocol>
</revisionJobInfo>