Configuring Field Squared for Pushing Data to a Third Party API

The Field Squared API can POST Field Squared objects to a third party API:

• whenever the object is created, updated or deleted (an "event" based request)
• on a schedule (example: every day at 2am)
• on request through an API request (example: by calling a URL you configure in our system)

Objects include things like Tasks, Assets, Contacts and Documents.

API calls that are made in response to events will send just the object that was saved to your API.

API calls that are made on a schedule, or on a request, will use a query to get data out of Field Squared (example: all tasks updated in the last 7 days) and will always respond with a list of objects, even if there is only one object in the results.

The structure for the data we send you for each object based on an event, schedule or API will always be the same, regardless of whether that data is in a list or a single object.

The data we send you through our API will match the custom fields and document controls you have configured inside Field Squared.

The shape of our API request will be the same regardless of how you have these configured.

The keys and values we send you in the Data property of each POST will match how you have each object configured.

Field Squared provides a preview API call function so that you can see what the shape of the API queries we'll send to you will look like.

The API call for each task type, asset type and document type will be different for each type, as the request we post will match your configuration inside Field Squared. We'll cover this in more detail below.

Sample Data Flows for an Event

Events trigger in response to things that happen in our apps (eg. on an iPad or in Web App). For example, say that a user saves an existing task on an iPad in the field:

1. The Task is saved in the field on an iPad to the local hard drive on the iPad
2. The Task is sent to the Field Squared API as part of the standard data synchronization process
3. The Field Squared API is configured with an event listener that is configured to listen for Task saves
4. The conditions on the task save event listener are evaluated to see if we should run this integration:
5. If the conditions are met, the API will run the integration in the background and send you a HTTP POST request in either JSON or XML to the URL that you provide to us.

Write to API using Universal Events Module

The Events module allows you to configure up when we'll send HTTP updates to your API.

You configure an event module to listen for events for a particular class of object (eg. Task, Asset, Document or Contact), and you then choose what actions trigger that event to run (eg. Creates, Updates, Deletes or any combination of them).

For Tasks, Assets and Documents, you also must select what type of task/asset/document to run the rule for. The Events module can only fire for a single type of task, document or asset save.

From there you can add additional filter conditions to your events module to control when you'll get API updates from our servers. For example:

• Did the task have a particular task status property
• Was the task scheduled or unscheduled
• Was the task assigned
• Did a property change values
• Did a property on the object have a particular value
• Was a property NULL when it should have had a value

Integration rules only run from saves that were made from Field Squared mobile devices or Web App. Saves made in response to integrations will not cause events to run.

HTTP POST requests sent to your API in response to events will always only contain a single object which was the object that triggered that event. For example, an Asset save for an asset with only a single custom field will look like the following:

{
   "Name": "My Fancy Boat",
   "ExternalId: "1234",
   "Type": "Boat",
   "Data": {
      "MY_FIELD": "testing"
   }
}

Scheduled and API Triggered Integrations

Integrations that are configured in response to a schedule (example: run this at 2am every morning) will work exactly like a single object save, but they will be configured to send the data as a list of objects in response to the query you assemble to run at the scheduled time.

An API Triggered integration will run any time you make a call to a URL you configure inside our system. It too will always respond with a list of objects, even if there is only a single object.

For example, if you run the integration at 2am and there is only one Asset in the response, we'll post the following to your API when the schedule is run.

[
  {
   "Name": "My Fancy Boat",
   "ExternalId: "1234",
   "Type": "Boat",
   "Data": {
      "MY_FIELD": "testing"
   }
  }
]

Structure of the data

How Custom Fields are Sent

The structure of the data that we send to you will closely match the configuration of your Tasks, Assets and Documents.http://docs.fieldsquared.com/knowledge-base/api-empty-null-properties/

For Tasks, Contacts and Assets you configure custom fields for each type that have a custom schema.

For example, if you configured a task type called Assign in App Builder like this:

Then these custom fields would appear in the API request as part of the Task like this:

{
  "Name": "My Task",
  "Type": "ASSIGN",
  "ExternalId": "1234",
  "ScheduledStartDate": "2016-11-16T22:00:00Z",
  "ScheduledEndDate": "2016-11-16T23:00:00Z",
  "Data": {
     "CREATEDBY": "Mark",
     "ASSIGN_DATE": "2016-11-16T11:00:00Z",
     "DOG": "Koda",
     "OWNER": "Jason"
  }
}

The structure of the API call therefore closely matches the structure of the objects configured in the Field Squared task configuration page. The values in Orange above closely match the configuration of the keys in Field Squared.

This same approach works for Task, Asset and Contact.

Note that the exact API call we send to your system is defined automatically for you.

A preview of the exact API call we'll POST to your API is available from the Field Squared configuration pages.

You can find these on the Task Type, Asset Type, Document Type and Integration Wizard configuration pages as a Preview POST button.

The rules for how to work with our external API are universal across our API calls, and the other related articles on them will be helpful to people building API's against our API calls. See the following articles for more information:

• Empty and NULL properties
• External ID's 
• Write Tasks to Field Squared for a description of how the Task object is structured when we send it to your API.
• Wring Assets to Field Squared for a description of how the Asset object is structured when we send it to your API.

How Documents are Structured

Documents Types are created/edited in App Builder from the 'Document' Tab.  Documents are configured by dragging 'Controls' into the document.  Each control is used to capture a data element.  A 'Binding' is configured for each control.

This 'Binding' defines the keys within the key/value pairs in the API output:

{
  "Name": "My Document",
  "Type": "WATER_TICKET",
  "ExternalId": "1234",
  "Data": {
     "DRIVER_NAME": "Mark Smith",
     "WATER_TICKET_NUM": "1234ABCD",
     "TRUCK_NUM": "76",
     "WORK_TICKET_NUM": "YIDKFKSE"
  }
}