A collection of small how to's and hints as how to work with the list api. This page also serves as a troubleshooting page which summarizes solutions we encountered during practical usage of the List API.

User and User Groups

Assigning User Groups to a User

Use the following REST API call to assign user groups to a user:

POST /rest/V1.0/list/User

{
    "columns": [{"identifier": "User.UserGroups"}],
    "rows": [{
            "object": { "id": "'restuser'" },
            "values": [ [ { "id" : "'InfaBPM'" }, { "id" : "'Categorization'" } ] ]
        }]
}

In this example the user restuser gets the user groups InfaBPM and Categorization assigned.

To add just one user group no list element is needed. For example

{ "id" : "'InfaBPM'" }

would be sufficient to assign group InfaBPM to a user.

Characteristics

When searching for a string value which is in the entity proxy format like: characteristic('StringCharacteristic') = "'LookupValue'@'Lookup'", the value will still be interpreted as a lookup value and not as a string.
Please make sure when using the search that there is no leading whitespace in the URL: list/Article/bySearch?query= characteristic('23124123') is empty

Structure Groups

Query the list of items assigned to multiple structure groups of a structure

Use the following REST request to get a list of all items assigned to "SG_1" and "SG_2" of "Structure" structure.

Note: in this request, the "ArticleStructureGroupMap" (read-only) entity is used since there is one entry for each item - structure group mapping.

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=(not (ArticleStructureGroupMap.StructureProxy("Structure", "'SG_1'@'Structure'") is empty) ) and (not (ArticleStructureGroupMap.StructureProxy("Structure", "'SG_2'@'Structure'") is empty))&fields=Article.SupplierAID

Updating Product's Structure Group with Rest API

Use the following REST API call to change the structure group of a product:

POST /rest/V1.0/list/Product2G

{  
  "entityIdentifier": "Product2G",
  "rowCount": 1,
  "columnCount": 1,
  "columns": [  
    {  
        "identifier": "Product2GStructureMap.ManualMap(\"Brands\")"  
    }  
  ],  
  "rows": [{  
      "object": {  
        "id": "87534@1",  
        "label": "MGRTN0000003381699"  
      },  
      "values": [ "NEW BRAND" ]  
  }]  
}  

In this example the object with the id 87534@1 is assigned to the "NEW BRAND" structure group within the Brands structure system.

You have to specify the Manual Map fields as a list of Strings, not entity items. You need to set the actual string identifier of the structure groups, not using the entity item syntax with the internal ID's.

You can also use this approach to change structure groups of articles and variants.

Access to structure group fails

The following call fails:

GET http://<hostname>:1501/rest/V1.0/list/StructureGroup/byParentGroup?structureGroup=20153@17969&fields=StructureGroup.Level

with error:

ERROR [qtp2129920-124] [FragmentManager] execute: Error while initializing resp. executing fragments
java.lang.IllegalStateException: Couldn't find a column index for column identifier: com.heiler.ppm.structure.db.model.StructureGroupRevision.structureId
	at com.heiler.ppm.fragment.server.hql.FragmentHqlContext.getColumnIndex(FragmentHqlContext.java:238)

while the following succeeds:

GET http://<hostname>:1501/rest/V1.0/list/StructureGroup/byParentGroup?structureGroup=20153@17969&fields=StructureGroup.Level,StructureGroup.StructureProxy

StructureGroup levels

Query bySearch on an attribute which is based on an enumeration:

GET http://<hostname>:1501/rest/V1.0/list/Article/bySearch?query=Article.Channelkennzeichen contains "technisat"

A multi-selection should also be possible, e.g. “technisat.de, ekshop.de”
In general there is also the problem, that the data also has to be written. How could this be achieved? The DB contains comma separated values.

Filtering on structure group attribute

The following call for example returns the structure group attributes:

http://<hostname>:1501/rest/V1.0/list/StructureGroup/StructureGroupAttribute/bySearch?
 query=StructureGroup.Identifier%20=%20%221365663226877%22
 &structure=TechniSat
 &fields=StructureGroupAttributeValue.Value
 &qualificationFilter=language(de)

It would be helpful a filter on sub attributes could be added to the query, e.g.

StructureGroupAttribute.IsMandatory = false

however adding this filter to the query leads to an internal error:

java.lang.NullPointerException
 at com.heiler.ppm.search.server.internal.hql.exp.logicalkey.DefaultLogicalKeyGenerator.generateHQLCondition(DefaultLogicalKeyGenerator.java:97)

Not possible to search by Structure Group Attribute Value

The following call:

GET http://localhost:1501/rest/V1.0/list/StructureGroup/bySearch?metaData=true
  &structure=10024
  &query=StructureGroupAttributeValue.Value("Brand ID",en,DEFAULT) equals "TEST"
  &pageSize=1000&orderBy=0-ASC
  &fields=StructureGroup.Identifier  

leads to the following internal error:

ERROR [qtp461258525-162] [CoreExceptionMapper] Error while interpreting object "StructureGroupAttributeValue.Value("BrandID","en",DEFAULT) equals "TEST"":
Error while parsing condition 'StructureGroupAttributeValue.Value("Brand ID","en",DEFAULT) equals "TEST"': 
Unknown enum entry provided for enum-based field (StructureGroupAttributeValue.Value) - Entry for synonym 'TEST' not found!
com.heiler.ppm.std.core.dsl.DslParseException: Error while interpreting object "StructureGroupAttributeValue.Value("Brand ID","en",DEFAULT) equals "TEST"":
      at com.heiler.ppm.std.core.internal.dsl.ParseUtils.performParse(ParseUtils.java:53)
      at com.heiler.ppm.search.core.hsq.HSQParser.parseSearchQuery(HSQParser.java:62)

Media Assets

Get media asset document with attributes fails

The following call:

GET http://<hostname>:1501/rest/V1.0/list/MediaAsset/MediaAssetDocument/byItems?items=14&fields=MediaAssetDocument.Identifier,MediaAssetDocumentAttributes.Resolution

leads to an internal error:

java.lang.IllegalArgumentException: Sort settings at index = 0 specify a field path for which the list model doesn't have appropriate column
	at com.heiler.ppm.std.core.list.util.ListEntryComparator.<init>(ListEntryComparator.java:269)

The following call fails with: Entity 'MediaAssetDocumentAttributes' is not a direct child entity of entity 'MediaAsset'.

GET http://localhost:1501/rest/V1.0/list/MediaAsset/MediaAssetDocumentAttributes/byItems?items=14