Provides the ability to retrieve field content of a sub entity without providing a full qualification. An example is a list of all attribute names and values for a set of objects retrieved by a report.

Execute a specific report for Read
- Examples
Execute a specific report of sub entities for MIME values

Execute a specific report for Read

URL Pattern	`/list/{entity-identifier}/{sub-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. At least one parameter has to be specified, otherwise the list of parameters for this report is returned.
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 have to be passed to control how the query's result has to be provided. These parameters are mostly the same as for root entities and therefore linked to the previous page.

General list query parameters
	Parameter	Required	Default	Datatype	Parameter description
	startIndex	no	0	Integer	see REST List API Read for Root Entities
	pageSize	no	100	Integer	see REST List API Read for Root Entities
	fields	no		String	see REST List API Read for Root Entities
	metaData	no	false	Boolean	see REST List API Read for Root Entities
	formatData	no	false	Boolean	see REST List API Read for Root Entities
	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). In case of a sub-entities, rows which belong to the same root item are always returned in a group of rows. There will be all rows for ItemA, followed by all rows for ItemD, followed by all rows for ItemB. The order of those groups is not defined, but it is guaranteed that rows belonging to the same root item are together. So when you loop over this table, you can be sure that this item is not coming again as soon as the entity item reference of the row differs to the one of the previous row (aka if the group changes). If an orderBy parameter is given, this basic principle for sub-entities does not change! The sorting will only be applied WITHIN the groups of rows for the same entity item! If not necessary for the client to process the rows in those groups in a sorted way, he should not provide this parameter.
	qualificationFilter	no		String	This parameter allows to restrict the output to certain qualifications. An example would a filter so that only Euro and Dollar prices for the customer Heiler are returned. The filter string is a comma-separated list of qualification settings. A qualification setting is a qualification name followed by a comma-separated list of values which is put into parentheses . The qualification name is defined in the repository and is included in the Meta-API. Example for prices in Euro and US-Dollar and customer Heiler: `qualificationFilter=currency(EUR,USD),customer(Heiler)`
	fieldFilter (since 10.1.0.02)	no		String	This parameter allows to restrict the output based on certain field filters. An example would be a filter so that only ArticleLang records are returned which have a certain keyword, or no keyword or any keyword. The filter string is a comma-separated list of filter settings. A filter setting is a field identifier followed by a comma-separated list of values which is put into parentheses. All REST Datatypes are supported for the parameters, except MIME_VALUE. Syntax: `fieldFilter= [not] <FieldIdentifier1>([Parameter1], ..., [ParameterN]),[not] <FieldIdentifierN>([Parameter1], ..., [ParameterN])` Multiple values for a single filter are interpreted as OR, so the row is returned if any of the given values equals the field value of the row. In case multiple field filters are defined, all of them must be met for the row to be returned. Multiple field filters are treated as AND. The value of the fieldFilter must match to the field's datatype. Fields with enumerations can also use any of the synonym strings of the enumeration's values. Example for ArticleLang with "MyMarker" as keyword: `fieldFilter=ArticleLang.Keyword("MyMarker")` Example for ArticleLang which has no "MyMarker as keyword `fieldFilter=not ArticleLang.Keyword("MyMarker")` Example for ArticleLang which has no keyword `fieldFilter=ArticleLang.Keyword()` Example for ArticleLang which has any keyword `fieldFilter=not ArticleLang.Keyword()` Please also find more examples on this parameter in the ListAPI postman collection. See the Examples section of REST List API.
	revision	no	-	ENTITY_ITEM	The revision entity item for which the data should be retrieved

Examples

Executing the report byCatalog and retrieve the values for short description and long description in all languages

Rest Call

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1501/rest/V1.0/list/Article/ArticleLang/byCatalog?fields=ArticleLang.DescriptionShort,ArticleLang.DescriptionLong

The following JSON object is returned:

{
    "cacheId": "20130404_115132_0",
    "entityIdentifier": "ArticleLang",
    "totalSize": 83,
    "startIndex": 0,
    "pageSize": 100,
    "rowCount": 83,
    "columnCount": 2,
    "columns": [
        {
            "identifier": "ArticleLang.DescriptionShort",
            "dataType": "STRING",
            "name": "Short description (Language selectable)"
        },
        {
            "identifier": "ArticleLang.DescriptionLong",
            "dataType": "STRING",
            "name": "Long description (Language selectable)"
        }
    ],
    "rows": [
        {
            "object": {
                "id": "1304@1",
                "label": "A1"
            },
            "qualification": {
                "language": "German"
            },
            "values": [
                "Kurzbeschreibung A1",
                "Detailbeschreibung A1"
            ]
        },
        {
            "object": {
                "id": "1304@1",
                "label": "A1"
            },
            "qualification": {
                "language": "English"
            },
            "values": [
                "Short description A1",
                "Long description A1"
            ]
        },
        {
            "object": {
                "id": "1315@1",
                "label": "A2"
            },
            "qualification": {
                "language": "German"
            },
            "values": [
                "Kurzbeschreibung A2",
                "Detailbeschreibung A2"
            ]
        },
        {
            "object": {
                "id": "1315@1",
                "label": "A2"
            },
            "qualification": {
                "language": "English"
            },
            "values": [
                "Short description A2",
                "Long description A2"
            ]
        },
		...
	]
}

Rest Client Java Code

ReportQuery reportQuery = new ReportQuery( "byCatalog" );
EntityItemTable resultList = restClient.createListReadRequest()
                                            .setFields( "ArticleLang.DescriptionShort", "ArticleLang.DescriptionLong" )
                                            .getSubItems( "Article", "ArticleLang", reportQuery );

Executing the report byCatalog for the MASTER catalog and retrieve the values for attribute name, attribute datatype and attribute value

Rest Call

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1501/rest/V1.0/list/Article/ArticleAttribute/byCatalog?fields=ArticleAttributeLang.Name,ArticleAttribute.Datatype,ArticleAttributeValue.Value&metaData=true

The following JSON object is returned:

{
    "cacheId": "20130404_134526_0",
    "entityIdentifier": "ArticleAttribute",
    "totalSize": 88640,
    "startIndex": 0,
    "pageSize": 100,
    "rowCount": 700,
    "columnCount": 3,
    "columns": [
        {
            "identifier": "ArticleAttributeLang.Name",
            "dataType": "STRING",
            "name": "Attribute name (Name selectable, Language selectable)"
        },
        {
            "identifier": "ArticleAttribute.Datatype",
            "dataType": "INTEGER",
            "name": "Attribute data type (Name selectable)"
        },
        {
            "identifier": "ArticleAttributeValue.Value",
            "dataType": "STRING",
            "name": "Attribute value (Name selectable, Language selectable, Identifier selectable)"
        }
    ],
    "rows": [
        {
            "object": {
                "id": "1143@1",
                "label": "A1"
            },
            "qualification": {
                "name": "Farbe",
                "language": "German"
            },
            "values": [
                "Farbe",
                "String",
                "rot"
            ]
        },
        {
            "object": {
                "id": "1143@1",
                "label": "A1"
            },
            "qualification": {
                "name": "Größe",
                "language": "German"
            },
            "values": [
                "Größe",
                "Number",
                "43"
            ]
        },
 
		...
 
    ]
}

Rest Client Java Code

ReportQuery reportQuery = new ReportQuery( "byCatalog" );
 
EntityItemTable resultList = restClient.createListReadRequest()
                                            .setFields( "ArticleAttributeLang.Name", "ArticleAttribute.Datatype", "ArticleAttributeValue.Value" )
											.setMetaData( true )
                                            .getSubItems( "Article", "ArticleAttribute", reportQuery );

Executing the report byItem for an item in SampleCatalog and retrieve the values for all characteristics

Rest Call

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1512/rest/V1.0/list/Article/ArticleCharacteristicValue/byItems?items='AIW_6382437688'@'SampleCatalog'&fields=ArticleCharacteristicValue.Characteristic

The following JSON object is returned:

{
    "cacheId": "20181109_113416_0",
    "entityIdentifier": "ArticleCharacteristicValue",
    "totalSize": 1,
    "startIndex": 0,
    "pageSize": 100,
    "rowCount": 7,
    "columnCount": 0,
    "columns": [],
    "rows": [
        {
            "object": {
                "id": "214@1200",
                "label": "AIW_6382437682",
                "entityId": 1000
            },
            "qualification": {
                "recordKey": "72f315fa2e73d20c:3964b945:16050a4147b:-7af4",
                "rootCharacteristic": {
                    "id": "78",
                    "label": "Sustainability Initiative [Sustainability]",
                    "entityId": 8000
                },
                "parentRecordKey": "root",
                "characteristic": {
                    "id": "78",
                    "label": "Sustainability Initiative [Sustainability]",
                    "entityId": 8000
                }
            },
            "values": [
                {
                    "id": "78",
                    "label": "Sustainability Initiative [Sustainability]",
                    "entityId": 8000
                }
            ]
        },
        {
            "object": {
                "id": "214@1200",
                "label": "AIW_6382437682",
                "entityId": 1000
            },
            "qualification": {
                "recordKey": "72f315fa2e73d20c:3964b945:16050a4147b:-7a03",
                "rootCharacteristic": {
                    "id": "78",
                    "label": "Sustainability Initiative [Sustainability]",
                    "entityId": 8000
                },
                "parentRecordKey": "72f315fa2e73d20c:3964b945:16050a4147b:-7af4",
                "characteristic": {
                    "id": "79",
                    "label": "Eco Footprint [Sustainability.EcoFootprint]",
                    "entityId": 8000
                }
            },
            "values": [
                {
                    "id": "79",
                    "label": "Eco Footprint [Sustainability.EcoFootprint]",
                    "entityId": 8000
                }
            ]
        }
		...
    ]
}

Executing the report byItem for an item in SampleCatalog and retrieve the values for Order

Rest Call

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1512/rest/V1.0/list/Article/ArticleCharacteristicValue/byItems?items='AIW_6382437688'@'SampleCatalog'&fields=ArticleCharacteristicValue.Order

The following JSON object is returned:

{
    "cacheId": "20181109_113931_0",
    "entityIdentifier": "ArticleCharacteristicValue",
    "totalSize": 1,
    "startIndex": 0,
    "pageSize": 100,
    "rowCount": 7,
    "columnCount": 0,
    "columns": [],
    "rows": [
        {
            "object": {
                "id": "214@1200",
                "label": "AIW_6382437682",
                "entityId": 1000
            },
            "qualification": {
                "recordKey": "72f315fa2e73d20c:3964b945:16050a4147b:-7af4",
                "rootCharacteristic": {
                    "id": "78",
                    "label": "Sustainability Initiative [Sustainability]",
                    "entityId": 8000
                },
                "parentRecordKey": "root",
                "characteristic": {
                    "id": "78",
                    "label": "Sustainability Initiative [Sustainability]",
                    "entityId": 8000
                }
            },
            "values": [
                "-32767"
            ]
        },
        {
            "object": {
                "id": "214@1200",
                "label": "AIW_6382437682",
                "entityId": 1000
            },
            "qualification": {
                "recordKey": "72f315fa2e73d20c:3964b945:16050a4147b:-7a03",
                "rootCharacteristic": {
                    "id": "78",
                    "label": "Sustainability Initiative [Sustainability]",
                    "entityId": 8000
                },
                "parentRecordKey": "72f315fa2e73d20c:3964b945:16050a4147b:-7af4",
                "characteristic": {
                    "id": "79",
                    "label": "Eco Footprint [Sustainability.EcoFootprint]",
                    "entityId": 8000
                }
            },
            "values": [
                "-32756"
            ]
        }
		...
    ]
}

Executing the report byItem for an item in SampleCatalog and retrieve the values for characteristics language specific data

Rest Call

curl -u rest:heiler -H "Accept: application/json" -X GET http://localhost:1512/rest/V1.0/list/Article/ArticleCharacteristicValue/byItems?items='AIW_6382437688'@'SampleCatalog'&fields=ArticleCharacteristicValueLang.Language

The following JSON object is returned:

{
    "cacheId": "20181030_121849_0",
    "entityIdentifier": "ArticleCharacteristicValue",
    "totalSize": 1,
    "startIndex": 0,
    "pageSize": 100,
    "rowCount": 14,
    "columnCount": 0,
    "columns": [],
    "rows": [
        {
            "object": {
                "id": "211@1200",
                "label": "AIW_6382437688",
                "entityId": 1000
            },
            "qualification": {
                "recordKey": "6bfe197e8d5135c4:-1dd34fd6:1604f0fd364:-7ef1",
                "rootCharacteristic": {
                    "id": "88",
                    "label": "Return Policy [ReturnPolicy]",
                    "entityId": 8000
                },
                "parentRecordKey": "root",
                "language": "Language independent",
                "characteristic": {
                    "id": "88",
                    "label": "Return Policy [ReturnPolicy]",
                    "entityId": 8000
                }
            },
            "values": [
                "Language independent"
            ]
        },
 
		...
 
    ]
}

Example with Field Filter

This example requests all ArticleLang sub entity records of all items of the "MySpplierCatalog" catalog and returns the Short Description and the Keyword fields. Only records which have "communicativeness" as a keyword will be returned.

curl --location --request GET 'http://localhost:1512/rest/V1.0/list/Article/ArticleLang/byCatalog?fields=ArticleLang.DescriptionShort,ArticleLang.Keyword&fieldFilter=ArticleLang.Keyword(%22communicativeness%22)&catalog=%27MySupplierCatalog%27' \
--header 'Accept: application/json' \
--header 'Authorization: Basic cmVzdDpoZWlsZXI='

Please find additional examples for the field filters in the ListApi postman collection.

Execute a specific report of sub entities for MIME values

URL Pattern	`/list/{entity-identifier}/{sub-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.

Parameters

The parameters used here are same as that of root entities.

Parameters valid for Article → ArticleCharacteristicValue entities only
includeUnavailable	no	false	Boolean	Allows to return MIME files for available AND unavailable characteristics. Default value is false and means that only available characteristics will be considered. Read more about Characteristic values in KnowledgeBase → Characteristics - Dynamic data model → Characteristic values

Note: Parameter fields is not used for Article → ArticleCharacteristicValue.

Examples

Execute the report byCatalog and retrieve the MIME files referenced by Article characteristic values for items of MASTER catalog using GET

Rest Call

curl -u rest:heiler -H "Accept: application/octet-stream" -X GET http://localhost:1512/rest/V2.0/list/Article/ArticleCharacteristicValue/mimes/byCatalog

Execute the report bySearch and retrieve the MIME files referenced by Article characteristic values for specific item using GET

Rest Call

curl -u rest:heiler -H "Accept: application/octet-stream" -X GET 
http://localhost:1512/rest/V2.0/list/Article/ArticleCharacteristicValue/mimes/bySearch?query=Article.SupplierAID = "ITEM_WITH_CHARACTERISTIC"

Execute the report byStructureGroup and retrieve the MIME files referenced by Article characteristic values qualified by characteristic record key using GET

Rest Call

curl -u rest:heiler -H "Accept: application/octet-stream" -X GET 
http://localhost:1512/rest/V2.0/list/Article/ArticleCharacteristicValue/mimes/byStructureGroup?structureGroup='GROUP_1_2'@'HeilerStandard'&qualificationFilter=recordKey("c003c0da0ca388f7:-2c5e83f8:1614649c74c:-7e9d")

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

Rest Call

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

Rest Java Client Example

You can find a short example on how to use the client below. The full example classes can be viewed as part of the SDK package in the folder examples\integration.

Example 1

Following code block is used for retrieving first 100 MIME values from masterCatalog for the Characteristics with identifiers "CharacteristicIdentifier1" and "CharacteristicIdentifier2".

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...
EntityItemReference masterCatalog = EntityItemReferenceFactory.createByIdentifier( "MASTER" );
ReportQuery reportQuery = new ReportQuery( "byCatalog" ).addParameterValue( "catalog", masterCatalog );
 
 
//Create and parameterize the list request
ListReadRequest mimeZipRequest = restClient.createListReadRequest();
InputStream mimeZipStream = mimeZipRequest.setPageSize( 100 )
                                          .setStartIndex( 0 )
                                          .setQualificationFilters( "characteristic('CharacteristicIdentifier1')",
                                                                    "characteristic('CharacteristicIdentifier2')" )
                                          .getSubMIMEs( "Article", "ArticleCharacteristicValue", reportQuery );

Example 2

Following code block retrieves the first 100 MIME values from the subentity LookupValueLang.MIME.

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( "LookupValueLang.MIMEValue" )
                                          .getSubMIMEs( "LookupValue", "LookupValueLang", reportQuery ))