Reading and manipulating custom fields via the WebAPI

Some types of business objects support custom fields, including but not limited to Customer, Supplier and Product. These are fields that are not part of the default business object instances but are added as extra fields by the user.

Reading custom fields

Custom fields on business objects in the .NET API are accompanied by metadata like constraints that determine which values are allowed for the custom field. The metadata is not included when retrieving business objects from the WebAPI. Only the name of the custom field and its value are returned. If a custom fields does not have a value for some instance, an empty string is returned as a value for that custom field.

The following example shows the way custom properties are represented in json:

    
    GET api/MVL01001/Customer/1002

    {
        "customerId": "1002",
        /* more standard properties ... */

        "customProperties": {
            "RELATIE.KENTONSVAN": "Via andere klant",
            "RELATIE.INTERESSE": "Producten voor binnen",
            "RELATIE.OPRICHTINGSDATUM": "1987-01-01T00:00:00",
            "RELATIE.PRODUCTGROEP": "Planten"
        }
    }
	

Manipulating custom fields

Changing the value of a custom field is very straightforward, just change the value associated with the dictionary key of the custom field. It is impossible to remove a custom field from a business object because custom fields are not registered on a per-instance basis but for the entire type. Omitting one or more of the entries in the customProperties dictionary does not remove custom fields, in fact the omitted entry is ignored and the previous value of the field remains. To clear the value of a custom field, pass null or an empty string.

When updating (PUT) business objects it is not neccessary to send the collection of custom properties when no changed have been made to custom properties. If no custom properties dictionary is sent the custom properties of that business object will be unaffected.