Missing, Null and Empty Properties in API calls

When calling the Field Squared API to create or update an object, you can construct API calls that

• omit properties: you create an API call that includes some but not all of the available API properties
• includes null/empty properties: the properties are included in the API call but don't have a value

The API treats these in different ways.

In general, the Field Squared API will always ignore missing properties.

The API will treat included properties that are null or empty as an instruction to clear that property on the object for an update, or use the default value on a create.

Omitted Properties

If you omit a property from the API call, then

• During a create operation Field Squared will use the default value
• During an update, Field Squared will ignore updating that property and leave it at its existing value

The following example is an update request for Task with an external ID of 1234. This API request will update the Task record, but it will only update the Description field – the Name, Status and all the other fields will not be updated because they're not included in the message body of the POST request.

<ArrayOfTask>
  <Task>
    <Description>My comments about this task go here</Description>
    <ExternalId>1234</ExternalId>
  </Task>
</ArrayOfTask>

This assumes that record 1234 exists in Field Squared. If the record doesn't exist, it will be created and default values will be used for all properties (for example, Task Status will likely be set to Not Started).

Empty and Null properties

The rules for JSON elements and XML elements that are empty or null or omitted vary between XML and JSON.

In JSON, here's how updating a field like Due Date would work:

• A null property means that property will not be updated: Example: {"DueDate": null} – due date is not updated.
• An empty string property will clear out a property. Example: {"DueDate": ""} – due date is removed

In XML, here's how updating a field like Due Date would work:

• An self closed XML element means that property will be cleared: Example:<Task><DueDate/></Task> – due date is cleared out.
• An empty element means that property will be cleared: Example:<Task><DueDate></DueDate></Task> – due date is cleared out
• Specifying the <Task></Task> object without a DueDate element is the same as the missing example above – the property won't be modified by the API request.

Updating Child Arrays for Linked Objects

The above rules apply differently to things that are arrays of child elements, like <Users> and <Teams>.

If the list elements like Users, Teams, Assets, Contacts or Document properties are included in the API call and the child arrays have no elements, then the property will be cleared. If the child properties aren't included then the API request, then the child elements won't be cleared.

For example, let's say we are using JSON and want to remove the users from a task, we should send this API request:

[
  {
    "Name": "My Task",
    "ExternalId": "1234",
    "Users": []
  }
]

This would remove the assigned users on the task.

Let's say having done this, we want to assign the task to another user:

[
  {
    "Name": "My Task",
    "ExternalId": "1234",
    "Users": ["abcd"]
  }
]

This would find the user with external ID abcd and assign them to your task.

The last request would update the Name property of the same task, but would not unassign the task since the Users property is omitted:

[
  {
    "Name": "Renamed",
    "ExternalId": "1234"
  }
]