The REST List API provides the possibility to set the values of several qualified fields 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 qualified fields

Writes the given values into qualified fields for one or more specified objects. All objects have to be of the same type.

URL Pattern	/list/{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.
	includeObjectsInProtocol	no	true	Boolean	If set to true, a list of created and updated objects are included in the protocol. To improve performance, this value should be set to false if the list of objects is not needed. This option is available since HPM 7.0.04.
	recreate	no	false	Boolean	If set to true, a sub entity item is always newly created (currently, only QualityStatusEntry objects are supported)

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.

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.
- a list of new values for each object.
mimeValueArchives containing
- File Reference id and originalFileName which is generated while uploading File using File upload API.
- Multiple FileReference id and originalFileName can be passed.
- This property is introduced to MIMEValue field only.

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 errors and warnings (members of the field entries) and a list of created and updated objects (members of the field objects). The list of created and updated objects is only included if the option includeObjectsInProtocol is set to true (default).

Properties of a `counters` element
	Field	Data type	Description
	errors	Integer	Total number of errors
	warnings	Integer	Total number of warnings
	createdObjects	Integer	Number of created objects
	updatedObjects	Integer	Number of updated objects
	objectsWithErrors	Integer	Number of objects with errors
	objectsWithWarnings	Integer	Number of objects with warnings

Properties of an `entries` element
	Field	Data type	Description
	row	Integer	The index of the row causing this error or warning. The first row has the index 0.
	objectType	String	The type of the object (language dependent label is used). Might be empty.
	object	EntityItem	The object the error or warning occurred in. Might be empty.
	severity	String	ERROR, WARNING or INFO
	category	String	Category of the error. Possible values are: SYSTEM, UNIQUENESS, DATATYPE, CARDINALITY, RANGE, CONSISTENCY, SECURITY, NOTE, SUMMARY
	propertyLabel	String	The field causing this error or warning (language dependent label is used). Might be empty.
	message	String	The message describing the error or warning.
	logDate	Date	Date when the error or warning occurred.
	logTime	Time	Time when the error or warning occurred.

Properties of an `objects` element
	Field	Data type	Description
	row	Integer	The index of the row which is responsible for creating or updating this object. The first row has the index 0.
	object	EntityItem	A reference to the updated or created object. Contains the id and the label of the object.
	status	List of Strings	The status of the object. Possible values are: CREATED, UPDATED, ERROR, WARNING

Examples

Setting non-formatted values

Sets values in the fields Article.ManufacturerName, Article.OrderUnit and ArticlePriceValueSales.Amount

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

The following JSON object is provided as content:

{
   "columns": [
        {
            "identifier": "Article.ManufacturerName"
        },
        {
            "identifier": "Article.OrderUnit"
        },
        {
            "identifier": "ArticlePriceValueSales.Amount(1,nrp,USD,US,2010-08-06,1.5)"
        }
   ],
   "rows": [
        {
            "object":
          	{
                   "id": "'A1'@'MASTER'"
		},
            "values": [
                "Heiler Software AG",
                {
                    "id": "39"
                },
                "12.34"
            ]
        },
        {
            "object":
          	{
                   "id": "'A2'@'MASTER'"
		},
            "values": [
                "Heiler Software AG",
                {
                    "label": "fifteen kg drum"
                },
                "NotANumber"
            ]
        },
        {
            "object":
          	{
                   "id": "'A3'@'MASTER'"
		},
            "values": [
                "",
                { },
                ""
            ]
        },
        {
            "object":
          	{
                   "id": "'A4'@'MASTER'"
		},
            "values": [
                null,
                null,
                null
            ]
        }
        
    ]
}
 

Remarks:

If the items A1, A2, A3 and A4 exists already, they are updated. Otherwise the items are newly created.
In case of item A2, an error occurs while setting the value. An error description is provided in the protocol.
In case of item A3, the content of the fields is cleared .
In case of item A4, the content of the fields is left unchanged .

The following protocol is returned :

{
    "counters": {
        "errors": 1,
        "warnings": 0,
        "createdObjects": 4,
        "updatedObjects": 0,
        "objectsWithErrors": 1,
        "objectsWithWarnings": 0
    },
    "entries": [
        {
            "row": 1,
            "objectType": "Item",
            "object": {
                "id": "120015@1",
                "label": "A2"
            },
            "severity": "ERROR",
            "category": "DATATYPE",
            "propertyLabel": "Price (from 1.0000)",
            "message": "Value 'NotANumber' could not be converted into type java.math.BigDecimal.",
            "logDate": "2013-04-04",
            "logTime": "11:59:46"
        }
    ],
    "objects": [
        {
            "row": 0,
            "object": {
                "id": "120014@1",
                "label": "A1"
            },
            "status": [
                "CREATED"
            ]
        },
        {
            "row": 1,
            "object": {
                "id": "120015@1",
                "label": "A2"
            },
            "status": [
                "CREATED",
                "ERROR"
            ]
        },
        {
            "row": 2,
            "object": {
                "id": "120013@1",
                "label": "A3"
            },
            "status": [
                "CREATED"
            ]
        },
        {
            "row": 3,
            "object": {
                "id": "120012@1",
                "label": "A4"
            },
            "status": [
                "CREATED"
            ]
        }
    ]
}

Setting formatted values

Sets the values which are provided in a German format

curl -u rest:heiler -H "Accept: application/json" -H "Accept-Language: de-DE" -X POST http://localhost:1501/rest/V1.0/list/Article?formatData=true

The following JSON object is provided as content:

{
   "columns": [
        {
            "identifier": "Article.ManufacturerName"
        },
        {
            "identifier": "Article.OrderUnit"
        },
        {
            "identifier": "ArticlePriceValueSales.Amount(1,nrp,USD,US,2010-08-06,1.5)"
        }
   ],
   "rows": [
        {
            "object":
                {
                   "id": "'A1'@'MASTER'"
                },
            "values": [
                "Heiler Software AG",
                {
                    "label": "15 kg-Fass"
                },
                "12,34"
            ]
        }
   ]
}

The returned protocol looks like:

    "counters": {
        "errors": 0,
        "warnings": 0,
        "createdObjects": 0,
        "updatedObjects": 1,
        "objectsWithErrors": 0,
        "objectsWithWarnings": 0
    },
    "entries": [],
    "objects": [
        {
            "row": 0,
            "object": {
                "id": "120033@1",
                "label": "A1"
            },
            "status": [
                "UPDATED"
            ]
        }
    ]
}

Setting MIMEValues for entity

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

The following JSON object is provided as content:

{
   "columns": [
        {
            "identifier": "LookupValue.MIMEValue"
        }
   ],
   "rows": [
        {
             "object": {
             	"id":"31@27",
                "label": "Amazon",
                "entityId": 7300
            },
            "values": 
                [
                    {
                    "relativeFilePath": "17/8/32/fishstick.jpg"
                    }
            ]
        },
        {
             "object": {
             	"id":"29@27",
                "label": "Netflix",
                "entityId": 7300
            },
                        "values": 
                [
                    {
                    "label": "img1.jpg",
                    "mimeType": "image/jpeg",
                    "relativeFilePath": "18/1/img1.jpg"
                    }
            ]
        },
                {
             "object": {
				"id": "32@27",
                "label": "Skype",
                "entityId": 7300
            },
                        "values": 
                [
                    {
                    "mimeType": "image/jpeg",
                    "relativeFilePath": "18/1/img1.jpg"
                    }
            ]
        }
   ],
   "mimeValueArchives":[
{
    "id": "b1f9e95f-f61e-4139-a429-efa16fbf4035",
    "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. Otherwise the items are newly created with MIMEValues if MIMEValue reference is set in 'mimeValueArchives'.

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": "LookupValue.MIMEValue"
        }
   ],
   "rows": [
        {
             "object": {
             	"id":"31@27",
                "label": "Amazon",
                "entityId": 7300
            },
            "values": 
                [
                    {
                    "relativeFilePath": "17/8/32/fishstick.jpg"
                    }
            ]
        },
        {
             "object": {
             	"id":"29@27",
                "label": "Netflix",
                "entityId": 7300
            },
                        "values": 
                [
                    {
                    "label": "img1.jpg",
                    "mimeType": "image/jpeg",
                    "relativeFilePath": "18/1/img1.jpg"
                    }
            ]
        },
                {
             "object": {
				"id": "32@27",
                "label": "Skype",
                "entityId": 7300
            },
                        "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/168441101/image2019-1-3_14-52-11.png