Syncing external systems with ExternalID

Field Squared can automatically insert or update a record as required whenever the API is called by using a field called External ID that cross references objects in Field Squared with ID's that are in your existing database of API.

If you call the Field Squared API to create or update a record and you specify the ExternalID property, then

• if the record doesn't exist, Field Squared will automatically create the record
• if the record does exist, Field Squared will update the existing record

The ExternalId property on Field Squared objects is the ID of that object in the source database.

External ID is used to uniquely identify a record from your system in our system.

The external ID is used to determine if Field Squared already has this record in its database:

• Whenever we receive a new task/asset/user/team (an "object") through the API, we look to see if our database already has that External ID present in the collection
  • if so, we update the record
  • If not, we create a new record using this External ID as well as our own internal ID
• External ID must be unique in the source data for each object
• If you omit the External ID property, all objects will be treated as "new" objects and will always be created.

The Field Squared API therefore acts just like the UPSERT or the CREATE OR UPDATE commands available in relational databases.

Example: always creating a record

The following example will create a new task every time since the External ID is not specified:

[
  {
     "Name": "My Task"
  }
]

And as XML to create a task every time:

<ArrayOfTask>
   <Task>
     <Name>My Task</Name>
   </Task>
</ArrayOfTask>

Example: create or update records as needed

The following  sample code will create a record the first time it's called. When the record is sent through a second time wth the same External ID, the record will be updated.

JSON Sample Create and update an Asset

First API call

[
  {
     "Name": "My New Boat",
     "Type": "BOAT",
     "ExternalId": "1234"
  }
]

Second API call – updates the record

[
  {
    "Name": "My Renamed Boat",
    "Type": "BOAT",
    "ExternalId": "1234"
  }
]

XML Sample Create and Update for Asset

First API Call creates a boat

<ArrayOfAsset>
   <Asset>
     <Name>My New Boat</Name>
     <Type>BOAT</Type>
     <ExternalId>1234</ExternalId>
   </Asset>
</ArrayOfAsset>

Second API call – updates the boat record

<ArrayOfAsset>
   <Asset>
      <Name>My Renamed Boat</Name>
       <Type>BOAT</Type>
       <ExternalId>1234</ExternalId>
    </Asset>
</ArrayOfAsset>

Diff Updates using the Last Updated Field

If your request to Field Squared includes the LastUpdated field, then Field Squared will only update the record in Field Squared if the record you send is newer than the record that Field Squared already has in the database. This is to ensure that records captured by technicians in the field aren't over-written by integration API calls. We call this Diff Updating the record – we only update the record if it's newer.

We highly recommend sending through LastUpdated if available

In the following example, we will only update work order record 1234 if the record in the Field Squared is older than Jan 27, 2016 at 5pm Mountain Standard Time, which is Jan 28, 2016 1am in Universal Coordinated Time UTC.

<ArrayOfTask>
   <Task>
     <Name>My Task That is newer</Name>
     <ExternalId>1234</ExternalId>
     <LastUpdated>2016-01-28T01:00:00Z</LastUpdated>
   </Task>
</ArrayOfTask>

If the task in Field Squared already was from Jan 27 at 8pm, then the record would not be updated. If the task in Field Squared was from Jan 1, then the task would be updated.