The REST List API provides the possibility to set the values of several fields of a specific sub entity for a list of given objects. The request returns a protocol containing the updated resp. created objects and a list of errors and warnings. It is possible to create new objects by providing external identifiers instead of internal IDs. Processing is distributed over multiple threads to speed up processing.

Write values into fields of a certain sub entity

Writes the given values into fields of a one specified sub entity for a list of provided objects. All objects have to be of the same type.

URL Pattern	/list/{entity-identifier}/{sub-entity-identifier}
Method	POST
Parameters	formatData
Content types	application/json
Media type	application/json
Result	A protocol containing some statistical information like the number of errors and warnings, a list of all errors and warnings and the created resp. updated objects.

Parameters

Available parameters
	Parameter	Required	Default	Datatype	Parameter description
	formatData	no	false	Boolean	If set to true, language specific formatted values are expected.

Content

The expected content has the same format as the result of a read request (see also REST List API Read for Root Entities) but not all properties have to be filled. Not required properties are ignored. It is possible to use the output of a read request, modify some values and use the modified read output as content for a write request.

The expected content has the same format as the result of a report query, but not all properties have to be filled.

Required properties are

columns containing
- an array of objects. Each object must contain the property identifier which contains the qualified field identifier
rows containing
- the object id. If an external identifier is provided and a corresponding object does not exist, a new object is created.
- the qualification of the sub entity
- a list of new values for each object

Formatting of values

The values have to be provided as strings and formatted as described in REST Datatypes.
If an empty string is specified as value, the content of the field is cleared. If null is specified as value, the content of the field is left unchanged.
In case a field has the type ENTITY_ITEM either a string or an JSON object can be provided. In case a string is provided, the string is treated as label if the field has an enumeration, otherwise as external identifier. In case a JSON object is provided, only the property id is evaluated.

Result

A protocol is returned as result. The protocol consists of a list of counters (number of errors, warnings etc.), a list of single errors and warnings (in property entries) and a list of created and updated objects.

A detailed description can be found at REST List API Write for Root Entities

Examples

Setting values in sub entity ArticleLang

This example set values of the fields ArticleLang.DescriptionShort and ArticleLang.Keyword

curl -u rest:heiler -H "Accept: application/json" -X POST http://localhost:1501/rest/V1.0/list/Article/ArticleLang

The following JSON object is provided as content:

{
   "columns": [
        {
            "identifier": "ArticleLang.DescriptionShort"
        },
        {
            "identifier": "ArticleLang.Keyword"
        }
   ],
   "rows": [
        {
            "object":
          	{
                   "id": "'A1'@'MASTER'"
     		},
            "qualification" : { "language" : "en" },
            "values": [
                "An English short description",
                [ "EnglishKeyword1", "EnglishKeyword2" ]
            ]
        },
        {
            "object":
          	{
                   "id": "'A1'@'MASTER'"
     		},
            "qualification" : { "language" : "de" },
            "values": [
                "A German short description",
                ["GermanKeyword2", "GermanKeyword1" ]
            ]
        },
        {
            "object":
          	{
                   "id": "'A2'@'MASTER'"
		    },
            "qualification" : { "language" : "en" },
            "values": [
                "English short description for second item",
                null
            ]
        },
        {
            "object":
          	{
                   "id": "'A3'@'MASTER'"
		    },
            "qualification" : { "language" : "en" },
            "values": [
                "English short description for third item",
                []
            ]
        }
    ]
} 

Remarks:

In case of item A2, the content of the field ArticleLang.Keyword is cleared .
In case of item A3, the content of the fields ArticleLang.Keyword is left unchanged .

The following protocol is returned :

{
    "counters": {
        "errors": 0,
        "warnings": 0,
        "createdObjects": 3,
        "updatedObjects": 0,
        "objectsWithErrors": 0,
        "objectsWithWarnings": 0
    },
    "entries": [],
    "objects": [
        {
            "row": 0,
            "object": {
                "id": "120044@1",
                "label": "A1"
            },
            "status": [
                "CREATED"
            ]
        },
        {
            "row": 2,
            "object": {
                "id": "120045@1",
                "label": "A2"
            },
            "status": [
                "CREATED"
            ]
        },
        {
            "row": 3,
            "object": {
                "id": "120043@1",
                "label": "A3"
            },
            "status": [
                "CREATED"
            ]
        }
    ]
}

Setting values to subentity from root entity

This example maps a unit to a specific unit system. In detail, a unit with ID 7001 will be taken and mapped to a unit system with ID 1. Therefore the values of the fields UnitSystemSpecific.Code and UnitSystemSpecificLang.Name in english and german will be set for the specified unit system.

curl -u rest:heiler -H "Accept: application/json" -X POST http://localhost:1512/rest/V1.0/list/Unit

The following JSON object is provided as content:

{
  "columns": [
    {
      "identifier": "UnitSystemSpecific.Code(1)"
    },
    {
      "identifier": "UnitSystemSpecificLang.Name(1,9)"
    },
    {
      "identifier": "UnitSystemSpecificLang.Name(1,7)"
    }
    
  ],
  "rows": [
    {
      "object": {
        "id": "7001"
      },
      "values": [
        "ZzZ",
        "My unit name for this unit system",
        "Mein Name für die Einheit in diesem Einheitemsystem"
      ]
    }
  ]
}

The following protocol is returned :

{
    "counters": {
        "errors": 0,
        "warnings": 0,
        "createdObjects": 0,
        "updatedObjects": 1,
        "objectsWithErrors": 0,
        "objectsWithWarnings": 0
    },
    "entries": [],
    "objects": [
        {
            "row": 0,
            "object": {
                "id": "7001",
                "label": "Dose",
                "entityId": 3100
            },
            "status": [
                "UPDATED"
            ]
        }
    ]
}

Setting lookup value of an item

This example set values of the fields ArticleCharacteristicValue.LookupValue

curl -u rest:heiler -H "Accept: application/json" -X POST http://localhost:1512/rest/V1.0/list/Article/ArticleCharacteristicValue

The following JSON object is provided as content:

{
  "columns": [
    {
      "identifier": "ArticleCharacteristicValue.LookupValue"
    }
  ],
  "rows": [
    {
      "object": {
                "id": "3@1100"
      },
      "qualification": {
                "recordKey": "72f315fa2e73d20c:3964b945:16050a4147b:-79d4",
                "rootCharacteristic": {
                    "id": "49"
                },
                "parentRecordKey": "root",
                "characteristic": {
                    "id": "49",
                    "label": "Ingredient [Ingredient]",
                    "entityId": 8000
                }
      },
      "values": [
        [
                    {
                        "id": "163@111",
                        "label": "Egg",
                        "entityId": 7300
                    }
                ]
      ]
    }
  ]
}

The following protocol is returned :

{
    "counters": {
        "errors": 0,
        "warnings": 0,
        "createdObjects": 0,
        "updatedObjects": 1,
        "objectsWithErrors": 0,
        "objectsWithWarnings": 0
    },
    "entries": [],
    "objects": [
        {
            "row": 0,
            "object": {
                "id": "3@1100",
                "label": "AIW_6382437684",
                "entityId": 1000
            },
            "status": [
                "UPDATED"
            ]
        }
    ]
}

Setting MIMEValues for SubEntity

To set MIMEValue to perticular column, first we have to upload Zip file containing MIMEValue we want to attach using File API. While uploading File using File upload API, user will get id and originalFileName object. After that object has to set to 'mimeValueArchives' as shown in example. User cann't reuse Filerefernce of uploaded file.

curl -u rest:heiler -H "Accept: application/json" -H 'Content-Type: application/json' -X POST http://localhost:1512/rest/V1.0/list/LookupValue/LookupValueLang

The following JSON object is provided as content:

 {
   "columns": [
        {
            "identifier": "LookupValueLang.MIMEValue"
        }
   ],
 "rows": [
        {
             "object": {
				"id": "31@27"
            },
            "qualification": {
                "language": "German"
            },
            "values": 
                [
                    {
                        "relativeFilePath": "17/8/32/fishstick.jpg"
                    }
                
            ]
        },
        {
             "object": {
                "id":"29@27",
                "label": "Netflix",
                "entityId": 7300
            },
			"qualification": {
                "language": "German"
            },
              "values":
                [
                    {
                    "label": "img1.jpg",
                    "mimeType": "image/jpeg",
                    "relativeFilePath": "18/1/img1.jpg"
                    }
            ]
        },
                {
             "object": {
                "id": "32@27",
                "label": "Skype",
                "entityId": 7300
            },
			"qualification": {
                "language": "German"
            },
                        "values":
                [
                    {
                    "mimeType": "image/jpeg",
                    "relativeFilePath": "18/1/img1.jpg"
                    }
            ]
        }
   ],
   "mimeValueArchives":[
{
    "id": "1f66a149-937f-4401-a3e5-737a05c35a25",
    "originalFilename": "uploadMime.zip"
}
]
}

The returned protocol looks like:

 {
    "counters": {
        "errors": 0,
        "warnings": 0,
        "createdObjects": 0,
        "updatedObjects": 3,
        "objectsWithErrors": 0,
        "objectsWithWarnings": 0
    },
    "entries": [],
    "objects": [
        {
            "row": 0,
            "object": {
                "id": "31@27",
                "label": "Amazon",
                "entityId": 7300
            },
            "status": [
                "UPDATED"
            ]
        },
        {
            "row": 1,
            "object": {
                "id": "29@27",
                "label": "Netflix",
                "entityId": 7300
            },
            "status": [
                "UPDATED"
            ]
        },
        {
            "row": 2,
            "object": {
                "id": "32@27",
                "label": "Skype",
                "entityId": 7300
            },
            "status": [
                "UPDATED"
            ]
        }
    ]
}

Remarks:

If the object Netflix exists already, they are updated.

Example 2: If mimeValueArchives fileRefernces is invalid or used earlier then User will get "400: Bad Request" in Response. As shown in bellow:

{
   "columns": [
        {
            "identifier": "LookupValueLang.MIMEValue"
        }
   ],
 "rows": [
        {
             "object": {
				"id": "31@27"
            },
            "qualification": {
                "language": "German"
            },
            "values": 
                [
                    {
                        "relativeFilePath": "17/8/32/fishstick.jpg"
                    }
                
            ]
        },
        {
             "object": {
                "id":"29@27",
                "label": "Netflix",
                "entityId": 7300
            },
			"qualification": {
                "language": "German"
            },
              "values":
                [
                    {
                    "label": "img1.jpg",
                    "mimeType": "image/jpeg",
                    "relativeFilePath": "18/1/img1.jpg"
                    }
            ]
        },
                {
             "object": {
                "id": "32@27",
                "label": "Skype",
                "entityId": 7300
            },
			"qualification": {
                "language": "German"
            },
                        "values":
                [
                    {
                    "mimeType": "image/jpeg",
                    "relativeFilePath": "18/1/img1.jpg"
                    }
            ]
        }
   ],
   "mimeValueArchives":[
{
    "id": "25f7856b-b185-4c4a-8130-cc6d157d3334",
    "originalFilename": "uploadMime.zip"
}
]
}

The response will look like:

images/download/attachments/166823801/image2019-1-3_14-52-11.png