In general, most common list-based read access will be utilized on root entity level, e.g. Products or StructureGroups, whereas fields can be requested on demand and need to be fully qualified (see REST Field Qualification) in case they belong to a sub entity of the requested root entity.

Executing a specific report
Execute a specific report for root entities for MIME values
- Examples for MIME values
- Rest Java Client Example for MIME values

Executing a specific report

URL Pattern	`/list/{entity-identifier}/{report-name}`
Method	`GET`
Parameters	Common list parameters are supported. Additional parameters of an entity report are report specific and can be obtained from the report service itself.
Media types	`application/json, application/xml`
Result	A list model which is optimized for fast transmitting and big item counts

Parameters

Beneath the query dependent parameters there are general parameters which can be passed to control the number of rows or the the specific columns which should be included in the query's result

General list query parameters
Parameter	Required	Default	Datatype	Parameter description
startIndex	no	0	Integer	0-based index within the total list of results. The result list provided for that request will start from that index (paging the results). An integer value in the range between 0 and totalSize-1.
pageSize	no	100	Integer	Number of entries which should be provided with that request (paging the results). The list starts a the given start index (see above) and leads to the end index (startIndex + pageSize). If the results totalSize is less than the requested pageSize or if totalSize - startIndex is less than pageSize the number of entries provided is less that the requested pageSize. You can use `-1` to obtain all items in one request - please note that this might cause serious performance problems on the client side, since the number of items can be quite large.
fields	no		String	Comma-separated list of fields to be provided as result. Please see the REST Field Qualification as well as REST Transition Fields for details on the syntax of this parameter.
metaData	no	false	Boolean	A Boolean parameter. If set to true the meta data of the requested fields (given in the parameter fields see above) are provided. As part of the meta data the language dependent name of the data fields is provided. The locale used by the HTTP request (see the Accept-Language http request-header field) is used to identify the language requested. If the locale can not be resolved or no language dependent name is available for the given locale the field's unique name is provided at this place.
formatData	no	false	Boolean	A Boolean parameter. If set to true the values having a locale/language dependent formatting (like date/time, numeric, etc.) returned are formatted corresponding the given locale used by the HTTP request (see the Accept-Language http request-header field). Also fields with an enumeration will be returned with the label of the enumeration's entry instead of it's key. In case the parameter is omitted or set to false, the data will be formatted in an easy to parse, locale neutral format. See the data type representation section for details.
includeLabels	no	true	Boolean	A boolean parameter. If set to true, columns of the data type ENTITY_ITEM also contain the human readable label of the entity item. For compatibility reasons this parameter is by default `true` for performance reasons clients should set it to `false`.
orderBy	no	0-ASC	String	The field(s) used to sort the result set can be specified by the this parameter. A 0-based index referring to the list of fields as given in the parameter fields has to be provided plus the ordering direction given by ASC (order ascending) or DESC (order descending). The syntax is as follows: `n-ASC/DESC` where `n` is the 0-based column index and either `ASC` or `DESC` has to be provided ("1-ASC" defines to sort ascending by the second field provided in the parameter fields). Multiple columns for ordering can be provided as a comma separated list ("1-ASC,0-DESC" sort by the second column ascending , then descending by the first column). If not necessary for the client to process the rows in a sorted way, he should not provide this parameter. If not given the order of the rows is not defined - even if they look sorted. This might just be a coincidence because of internal processing algorithms. You can only rely on a sort order if the orderBy parameter is provided.
assortmentFilter	no	none	EntityItem	An entity item representation of an assortment. The assortment's item entity must match with the entity of the items the query 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 Mastercatalog. 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 in the query. Please note that updating an assortment might be a performance intensive task, so take care when using this parameter and think about if you really need to have the assortment evaluated every time.
cacheId	no	-	String	See Caching for details
softDeleteMode	no	ALIVE_ONLY	String	The mode for loading soft deleted objects. Possible values: ALIVE_ONLY - Only include non-deleted objects in the result list. This is the default mode. DEAD_OR_ALIVE - Include both non-deleted and soft deleted objects into the result list. In terms of sub entity records, always the "newest" value is provided, meaning that if a non-deleted object for the current qualification exists, this one will be returned, and if only deleted objects exist, the one with the latest deletion time stamp will be returned, respectively.
revision	no	-	ENTITY_ITEM	The revision entity item for which the data should be retrieved

Result

The result of all List API service is always a list model. A list model is an object type independent data structure representing a list of results of a query. Basically it contains a list of list entries (rows). The list header provides general information on the number and type of list entries. Optionally the requested data fields' meta information can be provided (columns).

Each list entry consists of identifying fields which allow to identify the object behind the list entry uniquely - the navigable. Additionally each list entry might contain a list of object type specific data fields. These fields can be requested flexibly by passing a list of unique field identifiers. Optionally the requested fields' meta information can be provided.

{
  "cacheId": "20130403_164441_0",
  "entityIdentifier": "Article",
  "totalSize": 88640,
  "startIndex": 0,
  "pageSize": 100,
  "rowCount": 100,
  "columnCount": 2,
  "columns": [
  ...
  ],
  "rows": [
  ...
  ]
} 

Header

The list header always contains the information about the total number of results. The result list is provided paged. The start index and the number of entries within the provided list model page are given in the list header information. The start index and the number of entries to be provided can be controlled by request parameters of the query (startIndex and pageSize). The actual number of returned list entries and colums within one request are stated with rowCount and columnCount. Paging of a result table in the web front-end or a virtual table functionality can be realized by this. The entity type of the entries of the result list is given as well generally in the list's header information.

List header
Field	Description
cacheId	The id of the used cache.
entityIdentifier	The entity of the HPM repository the list model contains entries of.
totalSize	The total number of results of the query.
startIndex	The 0-based index of first entry of the currently provided list model page within the whole result set.
pageSize	The number of requested entries per list model page.
rowCount	Number of entries contained in the currently provided list model page (can be smaller than requested page size).
columnCount	Number of colums contained in the returned list model page (as requested by the fields query parameter).

Columns

The data fields' meta information for client side presentation and validation can be provided with the search result optionally. The meta data ("columns") is added to the resulting list model in case the query passes the parameter metaData with true.

The language dependent name as defined in the repository server side is provided. The language requested is identified by the locale provided with the HTTP request-header field Accept-Language. In case the requested language is not available a fallback the the repositories default language is implemented.

The columns are provided in the same sequence as requested by the parameter "fields" (see above) and identified by the unique field identifier the column stands for. Additionally the field's data type is provided. In future further information might be added for enhanced client side validations of the fields' content (typical information could be the minimum/maximum string length, minimum/maximum value of a numeric field, etc.).

"columns": [
{
  "identifier": "Article.SupplierAID",
  "dataType": "STRING",
  "name": "Item No." 
},
...
]

Column
Field	Description
identifier	The unique field identifiers including qualification.
datatype	The data type of the field.
name	The language dependent display name of the field. The language used is controlled by the HTTP request-header field Accept-Language when the parameter formatData is provided with true.

Rows

Each record in the resulting list is represented by a list row. Each row consists of a set of identifying fields, the so called navigable, which allow to identify the object behind the entry uniquely.

Additionally each entry contains a list of values provided for the data fields requested by the parameter "fields". The sequence of the values corresponds to the sequence the data fields in the parameter "fields" were requested.

The number of rows provided as a result for the certain query is controlled by the request parameter pageSize. The index within the whole result set of the first entry in the list provided is controlled by the request parameter startIndex.

"entries": [
{
  "object":
     {
       "id": "3264@1",
       "label": "IT-12345"
     },
  "values": [
    "IT-12345",
    "Hübscher brauner Schuh",
    "Nice brown shoe",
    "Atlas",
    "1.00"
  ]
},
...
]

Entry

Field

Description

object

Entity Item Reference to the corresponding object within the PIM system.

values

A list of values provided per entry for the data fields requested by the parameter "fields" (a comma separated list of unique field identifiers including their qualifications). The sequence of the values corresponds to the sequence of the data fields in the parameter "fields" were requested. If no fields were specified the values element is an empty array.

The value is usually represented as a String except for fields with data type ENTITY_ITEM. In this case, the value is a JSON object with the properties id and label if the field has an upper-bound of 0 or 1. If the upper bound is greater than 1, the value is a JSON array of JSON objects with the properties id and label.

Data type	Upper bound	JSON type
ENTITY_ITEM	>1	Array of ProxyObjects (properties:`id` and `label`)
ENTITY_ITEM	<=1	ProxyObject (properties: `id` and `label`)
not ENTITY_ITEM		String (delimiter for multiple values is semi-colon)

Examples

Executing the report byCatalog for the catalog TOOLS

The parameters of the report have to be added to the URL as query parameters:

Rest Call

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1501/rest/V1.0/list/Article/byCatalog?catalog=TOOLS   

The following JSON object is returned:

{
    "cacheId": "20130403_164441_0",
    "entityIdentifier": "Article",
    "totalSize": 88640,
    "startIndex": 0,
    "pageSize": 100,
    "rowCount": 100,
    "columnCount": 0,
    "columns": [],
    "rows": [
        {
            "object": {
                "id": "86@1064",
                "label": "A1"
            },
            "values": []
        },
        ...
    ]
}

Rest Client Java Code

EntityItemReference catalog = EntityItemReferenceFactory.createByIdentifier( "TOOLS" );
 
ReportQuery reportQuery = new ReportQuery( "byCatalog" );
reportQuery.addParameterValue( "catalog", catalog );
 
EntityItemTable resultList = restClient.createListReadRequest().getRootItems( "Article", reportQuery );

Executing the report byCatalog for the catalog TOOLS and specifying a list of fields (parameter formatData is false)

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1501/rest/V1.0/list/Article/byCatalog?catalog=TOOLS&fields=Article.SupplierAID,Article.ManufacturerName,Article.MainSupplier,Article.QuantityMin
&formatData=false&metaData=true&startIndex=0&pageSize=50&orderedBy=0-ASC

The following JSON object is returned:

{
    "cacheId": "20130403_164441_0",
    "entityIdentifier": "Article",
    "totalSize": 88640,
    "startIndex": 0,
    "pageSize": 50,
    "rowCount": 50,
    "columnCount": 4,
    "columns": [
        {
            "identifier": "Article.SupplierAID",
            "dataType": "STRING",
            "name": "Item no."
        },
        {
            "identifier": "Article.ManufacturerName",
            "dataType": "STRING",
            "name": "Manufacturer"
        },
        {
            "identifier": "Article.MainSupplier",
            "dataType": "ENTITY_ITEM",
            "name": "Main supplier"
        },
        {
            "identifier": "Article.QuantityMin",
            "dataType": "DECIMAL",
            "name": "Minimum order quantity"
        }
    ],
    "rows": [
        {
            "object": {
                "id": "1304@1",
                "label": "A1"
            },
            "values": [
                "A1",
                "Test Supplier 1",
                {
                    "id": "3",
                    "label": "Heiler Product Manager"
                },
                "1"
            ]
        },
        ...
    ]
}

Rest Client Java Code

EntityItemReference catalog = EntityItemReferenceFactory.createByIdentifier( "TOOLS" );
 
ReportQuery reportQuery = new ReportQuery( "byCatalog" );
reportQuery.addParameterValue( "catalog", catalog );
EntityItemTable resultList = restClient.createListReadRequest()
                                            .setFields( "Article.SupplierAID", "Article.ManufacturerName", "Article.MainSupplier", "Article.QuantityMin" )
                                            .setOrderBy( "0-DESC" )
                                            .setFormatData( false)
                                            .setMetaData( true )
											.setPageSize(50)
                                            .getRootItems( "Article", reportQuery );

Executing the report byCatalog for the catalog TOOLS and specifying a list of fields (parameter formatData is true)

Finally the additionally required parameters to control the result have to be added:

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1501/rest/V1.0/list/Article/byCatalog?catalog=TOOLS&fields=Article.SupplierAID,Article.ManufacturerName,Article.MainSupplier,Article.QuantityMin
&formatData=true&metaData=true&startIndex=0&pageSize=50&orderedBy=0-ASC

The following JSON object is returned:

{
    "cacheId": "20130403_175512_0",
    "entityIdentifier": "Article",
    "totalSize": 88640,
    "startIndex": 0,
    "pageSize": 50,
    "rowCount": 50,
    "columnCount": 4,
    "columns": [
        {
            "identifier": "Article.SupplierAID",
            "dataType": "STRING",
            "name": "Item no."
        },
        {
            "identifier": "Article.ManufacturerName",
            "dataType": "STRING",
            "name": "Manufacturer"
        },
        {
            "identifier": "Article.MainSupplier",
            "dataType": "ENTITY_ITEM",
            "name": "Main supplier"
        },
        {
            "identifier": "Article.QuantityMin",
            "dataType": "DECIMAL",
            "name": "Minimum order quantity"
        }
    ],
    "entries": [
        {
            "object": {
                "id": "1304@1",
                "label": "A2"
            },
            "values": [
                "A2",
                "Test Supplier 1",
                {
                    "id": "3",
                    "label": "Heiler Product Manager"
                },
                "1.0000"
            ]
        }
    ]
}

Searching for root entity objects

In order to search for objects matching a specific criteria, a generic bySearch report is available for all root entities. The search criteria can be specified by providing a search expression in the query parameter. The search expression language to be used is documented in REST Search Query Language. The catalog parameter can be used to specify in which catalog to look for (default is Master catalog).

Search for all items of the master catalog which contain "4711" in their GTIN number

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1501/rest/V1.0/list/Article/bySearch?catalog=MASTER&query=Article.EAN contains "4711"

Rest Client Java Code

EntityItemReference testCatalogRef = EntityItemReferenceFactory.createByIdentifier( "TOOLS" );
 
ReportQuery reportQuery = new ReportQuery( "bySearch" );
reportQuery.addParameterValue( "query", "Article.EAN contains \"4711\"");
 
EntityItemTable resultList = restClient.createListReadRequest()
                                            .getRootItems( "Article", reportQuery );

Search for all items of the master catalog which are ordered in boxes, with German gross weight between 10 and 30 kg

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1501/rest/V1.0/list/Article/bySearch?query=Article.OrderUnit equals "Box" AND ArticleLogistic.GrossWeight(Germany) >= 10.00 AND ArticleLogistic.GrossWeight(Germany) <= 30.00

Search for tasks assigned to specific supplier

To request the list of tasks which are assigned to a supplier use following request:

Tasks bySupplier

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1501/rest/V1.0/list/Task/bySupplier?supplier=SUPPLIER_FOR_TASKS

NOTE: This report returns single (standard) tasks and workflow tasks. No task groups will be returned in the result. Only workflow tasks which have items (count > 0) will be returned

Parameters
Parameter	Required	Default	Datatype	Parameter description
supplier	yes		EntityItem	Entity item representation of supplier (supplier proxy) for which the tasks should be provided. NOTE: supplier proxy should be represented using an internal ID or using supplier name (not identifier)
includeCompleted	no	false	Boolean	Indicates if completed tasks should be also provided in the result or not. Default value is false => completed tasks will be not provided in the result as default
catalogs	no		List of EntityItems	List with entity item presentations of catalogs (catalog proxies) which will restrict the list of provided in the result tasks. Optional patameter. If given, then only tasks which have content from requested supplier catalogs or empty tasks will be provided in the result. Useful e.g. for the Broker user.

Execute a specific report for root entities for MIME values

URL Pattern	`/list/{entity-identifier}/mimes/{report-name}`
Method	`GET and POST`
Parameters	The parameters `pageSize`, `startIndex, fields` and `qualificationFilter` are supported. Other List Read for sub entities parameters are ignored. Additional parameters of an entity report are report specific and can be obtained from the report service itself.
Media types	`application/octet-stream`
Result	A zip stream with MIME files including the folder structure from target system.

Examples for MIME values

Execute the report byLookup and retrieve the MIME files referenced by lookup "Apps" using GET

Rest Call

 curl -u rest:heiler -H "Accept: application/octet-stream" -X GET http://localhost:1512/rest/V1.0/list/LookupValue/byLookup?lookup=Apps&fields=LookupValue.MIMEValue

Execute the report byLookup and retrieve the MIME files referenced by LookupValue by specifying the field using POST

Rest Call

 curl -u rest:heiler -H "Accept: application/octet-stream" --data "lookup=Apps&fields=LookupValue.MIMEValue" http://localhost:1512/rest/V1.0/list/LookupValue/byLookup

Rest Java Client Example for MIME values

Following code retrieves first 100 MIME values including the empty ones from the lookup "Apps".

Usage example for the client API

//Create and login to the client...
RestClient restClient = new RestClient();
 
 
//Create and parameterize the report query you want to execute...
ReportQuery reportQuery = new ReportQuery( "byLookup" ).addParameterValue( "lookup", "Apps" );
 
 
//Create and parameterize the list request
ListReadRequest mimeZipRequest = restClient.createListReadRequest();
InputStream mimeZipStream = mimeZipRequest.setPageSize( 100 )
                                          .setStartIndex( 0 )
                                          .setFields( "LookupValue.MIMEValue" )
                                          .getRootMIMEs( "LookupValue", reportQuery );