Tasks API

Tasks API

Field Squared supports a RESTful API that handles both single object and list operations.

Tasks in Field Squared (also known as Work Orders or Jobs) are written to the API as either a single task or a list of task objects. For most integrations we recommend doing batch updates of tasks (create, update) as array operations.

For additional rules around API data types and data handling, please see the API Usage Notes article. All requests to our API must be authenticated with our authentication service. Please read our article on Authenticated HTTP headers and the correct HTTP methods.

Task Objects Payload

A task has the following structure by default. We'll explore the makeup of a task throughout this article.

{
   "Name": "Test Delivery Task for API",
   "Description": "Test Description for Task",
   "ExternalId": "bpaCIb5YwcmsLANcVU4lYAAAYA",
   "TaskType": "Delivery",
   "Priority": 3,
   "DueDate": "2017-01-28",
   "DesiredCompletionDate": "2017-01-16",
   "Lat":39.749911,
   "Lon":-105.000026,
   "StreetAddress": "1514 Blake St",
   "Unit": "Suite 200",
   "City": "Denver",
   "State": "CO",
   "Zip": "80202-1322",
   "ScheduleStart": "2017-01-27T20:00:00Z",
   "ScheduleEnd": "2017-01-27T20:45:00Z",
   "Status": "Not Started",
   "User": "940401b3-41f8",
   "Team": "cMwzpb7YY-KKMNyiQ935UwAAUw",
   "Asset": "j1SqRSBFpDSPd450NAZQCgAACg",
   "LastUpdated": "2017-02-02T21:16:46Z",
   "Created": "2017-01-27T19:09:48Z",
   "Data": {
      "MY_TEXT_FIELD": "Some sample text",
      "MY_NUMBER_FIELD": "1234",
      "MY_TIME_FIELD": "00:30:00",
      "MY_DATE_FIELD": "2017-01-23",
      "MY_DATE_TIME_FIELD": "2017-01-27T19:14:46Z",
      "SAMPLE_BARCODE_SCAN_FIELD": "234234esfs2"
    }
 }

Working with Single Tasks

For single task updates, Field Squared supports the HTTP methods GET, POST, and DELETE.

Methods Supported: GET|POST|DELETE
URL: https://api.fieldsquared.com/workspace/api/task/externalid

Where workspace is the unique company ID issued to your company and External Id is the ID of the record in your existing system. Callers to this API must be authenticated and use the X-Auth-Token in the HTTP headers or the request will be rejected by the Field Squared firewall.

Example 1
GET https://api.fieldsquared.com/10/api/task/1234
will retrieve the task 1234 from workspace 10. The structure of the Task returned will look like the payload above.

Example 2:
POST https://api.fieldsquared.com/10/api/task/4567
Creates or updates the task 4567 for workspace 10. Note that all required fields for the task must be populated for the create to be successful. The Task object sent to us should look like the payload above.

Example 3:
DELETE https://api.fieldsquared.com/10/api/task/4567
Removes task 4567 from workspace 10. The task is not deleted permanently and is moved to the archived objects collection and can be restored from the recycle bin.

Working with Lists of Tasks

For list/array operations (eg. bulk read and write), Field Squared supports GET and POST operations. DELETE is not supported for list operations.

Methods Supported: GET|POST
URL: https://api.fieldsquared.com/workspace/api/task

Where workspace is the ID we assign to your company

We support the following query parameters for GET operations:

  • modifiedsince – returns all records modified/edited/created within the Field Squared platform since a given date and time. Datse are an ISO-8901 format date string in UTC time.
  • status – returns all records that match status of the string value specified
  • startsbefore – returns all jobs scheduled before this date and time
  • startsafter – returns all jobs scheduled after this date and time
  • tasktypes – To filter on asset type, use the query parameter tasktypes and pass a comma separated list of types.

Each Task Type is extensible with custom fields (see below), therefore the API generation tool in App Builder should be used to create the exact API payload that is required for each task type.

The payload for a list of tasks is simply an array of Task objects like the example below.

[
  {
    "Name": "My Task",
    "ExternalId": "1234",
    "TaskType": "Install",
    "Status": "Not Started"
  },
  {
    "Name": "My Second Task",
    "ExternalId": "1235",
    "TaskType": "Install",
    "Status": "In Progress"
 }
]

Field Squared supports batch updates of multiple tasks, or sending through just a single task object in a request within a list. When updating or retrieving a list of tasks through our API, you must specify a single task type. It it not possible to bulk update tasks of different types, since each task type has its own schema.

Example 1
GET https://api.fieldsquared.com/10/api/task
This retrieves an array of task objects (see below) through the API. Query parameters for this API are supported to add filters to the request.

Example 2
POST https://api.fieldsquared.com/10/api/task
This example can bulk create or update tasks of type Install where each item in the request will be created/updated in the Field Squared database.

Setting up the Message Body

The rest of this article covers creating the Tasks message body that you POST to the URL defined in the previous section.

All the following examples use an array of tasks as the examples rather than a single task.

Task updates are made as a list of task objects you want to create or update in Field Squared.

JSON Sample to create two tasks:

[
  {
    "Name": "My First Task",
    "ExternalId": "1234",
    "TaskType": "Install"
  },
  {
    "Name": "My Second Task",
    "ExternalId": "2345",
    "TaskType: "Install"
  }
]

XML Sample to create two tasks:

<ArrayOfTask>
   <Task>
      <Name>My First Task</Name>
      <ExternalId>1234</ExternalId>
      <TaskType>Install</TaskType>
   </Task>
   <Task>
      <Name>My Second Task</Name>
      <ExternalId>2345</ExternalId>
      <TaskType>Install</TaskType>
   </Task>
</ArrayOfTask>

XML uses the ArrayOfTask container XML element that then contains a number of child Task elements. See the API Usage Notes document for more details about XML data structures and what's supported.

If you are updating a single task, you make a request to update a list of task objects with a single task in the list.

JSON Sample to create a single task using the TaskList variation:

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

 

Updating Records using the ExternalID

Field Squared can automatically insert or update a record as required whenever the API is called.

If you call the Field Squared API with a Task using the Task API 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 the Task is the Unique ID of the Task in the source database. It 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 through the API, we look to see if our database already has the External ID present – if so, we update the record. If not, we create a new record using this External ID.
  • External ID must be unique in the source data for each Task.
  • If you omit the External ID property, all tasks will be treated as new tasks and will always be created.
  • You cannot omit External ID for single task operations

The Task 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 and the list payload is 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

First API call

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

Second API call – updates the record

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

XML Sample Create and Update

First API Call

<ArrayOfTask>
   <Task>
     <Name>My Task</Name>
     <ExternalId>1234</ExternalId>
   </Task>
</ArrayOfTask>

Second API call – updates the record

<ArrayOfTask>
   <Task>
     <Name>My Renamed Task</Name>
     <ExternalId>1234</ExternalId>
   </Task>
</ArrayOfTask>

 

Task API Properties

Core Properties

The core properties of a task are:

  • Name (required) – the name of the task – typically this is a word order number of a short title (eg. "WO-1234" or "Install fixture in Room 234"
  • Description (optional) – the details notes, comments or description for this task.
  • ExternalId (optional) – the unique ID of the record in your system. If omitted all items in the API request will result in a new record being created.
  • Task Type (required) – the type of this job (eg. "Install" or "Replace"). This must map onto one of the Task Types that have been configured in App Builder for your company.
  • Status (required) – the current job status for this task (eg. "Not Started", "Complete" etc.). This must map onto one of the Status Codes that have been configured in App Builder for your company.
  • User (optional) – ExternalID of user assigned to task
  • Team (optional) – ExternalID of team assigned to task
  • Asset (optional) – ExternalID of asset related to task

Minimum JSON Task body to create a single task

[
 {
   "Name": "Test Delivery Task for API",
   "Description": "Test Description for Task",
   "ExternalId": "1234",
   "TaskType": "Delivery",
   "Status": "Not Started",
   }
]

Minimum XML Task body to create a single task

<ArrayOfTask>
  <Task>
    <Name>Test Delivery Task for API</Name>
    <Description>My comments about this task go here</Description>
    <ExternalId>1234</ExternalId>
    <TaskType>Delivery</TaskType>
    <Status>Not Started</Status>
  </Task>
</ArrayOfTask>

Omitting Properties

If you omit a property from the API call, then

  • During a create 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 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.

<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.

Empty vs. Null vs. Omitted

The rules for JSON elements and XML elements that are empty or null or omitted vary and are documented in this extended article on API structure.

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

  • A missing property means that property will not be updated. Example: {} – due date is not updated
  • 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:

  • A missing property means that property will not be updated. Example: <Task></Task> – due date is not updated
  • An self closed element means that property will not be updated: Example:<Task><DueDate/></Task> – due date is cleared out
  • An empty element means that property will not be updated: Example:<Task><DueDate></DueDate></Task> – due date is cleared out

These rules don't apply to things that are child array elements, like <Users> and <Teams>.

Task Prioritization Properties

  • Priority – the priority number field – this is a number from 1 to 9 with priority 1 being the highest priority. The priority numbers are mapped to text in Field Squared using App Builder, which is a display only property at runtime (eg. 1 = "Critical", 3 = "Normal")
  • Due Date – the date that the work order is due by in YYYY-MM-DD format. Example: "2016-11-16"
  • Desired Completion – the date that the work order would ideally be completed by in YYYY-MM-DD format.

These can be added to the task record

[
 {
   "Name": "My Task",
   "Status": "Not Started",
   "ExternalId": "1234",
   "TaskType": "Default", 
   "Priority": 3,
   "DueDate": "2017-01-28",
   "DesiredCompletionDate": "2017-01-16"
  }
]

Scheduling Tasks Properties

  • ScheduledStart – the date and time in UTC format to schedule the task to start at
  • ScheduledEnd – the date and time in UTC format to schedule the task to start at

For example, to schedule a task for 1 hour from 6pm on Dec 25th in UTC time, the minimum viable Task object would look like the following:

[
 {
   "Name": "My Task",
   "Status": "Not Started",
   "ExternalId": "1234",
   "TaskType": "Default",
   "ScheduledStart": "2016-12-25T18:00:00Z",
   "ScheduledEnd": "2016-12-25T19:00:00Z"
  }
]

Note that it is an error to send through a scheduled end time that is before the scheduled start time.

To Unschedule a task, set the properties to an empty string (JSON) or an empty XML element (XML).

Unscheduling a task in XML

<ArrayOfTask>
  <Task>
    <Name>Test Delivery Task for API</Name>
    <Description>My comments about this task go here</Description>
    <ExternalId>1234</ExternalId>
    <TaskType>Delivery</TaskType>
    <Status>Not Started</Status>
    <ScheduledStart/>
    <ScheduledEnd/>
  </Task>
</ArrayOfTask>

Unscheduling a task in JSON

[
 {
   "Name": "My Task",
   "Status": "Not Started",
   "ExternalId": "1234",
   "TaskType": "Default",
   "ScheduledStart": "",
   "ScheduledEnd": ""
  }
]

Setting Custom Fields through the API

Tasks are customizable and extensible in Field Squared. You can extend tasks using Custom Fields which have a very flexible structure and there's over 30 different types of custom fields available. A detailed description of custom fields in our API is discussed in This Article.

All custom fields are configured inside the Field Squared App Builder. Each custom field has:

  • A customizable user interface
  • A unique BINDING key to identify the control
  • A label to display on the screen for the control

You configure custom fields for each task type in Field Squared. Two task types may or may not have the same custom field binding keys available to use.

For example, you can extend the Task screen to include a Combo Box control that has default list items with values "Value A", "Value B" and "Value C". The user can select one of those options at runtime, or type their own value into the field. See our documentation on custom fields for more details on the possibilities.

The Data property on the API is used to set custom field values in API integrations.

  • Each message body can send any values you like to the Field Squared API.
  • All values are key-value pairs where the keys are strings and the values are strings.
  • All binding keys must be uppercase.
  • If the keys sent to our API are not configured on that Task Type, then they will be ignored by our API. We only update keys that exist for that task type.

For example, say we want to update a Car Wash task type, which has the custom fields vehicle type and number of wheels added to it to extend the core Task object. You would update this record using the following sample API calls:

JSON: Data is a dictionary of key-value pairs

[
 {
   "Name": "My Task",
   "Status": "Not Started",
   "ExternalId": "1234",
   "TaskType": "Car Wash",
   "Data": {
      "VEHICLE_TYPE": "Truck",
      "NUMBER_OF_WHEELS": 18
   }
  }
]

 

XML: Data is an XML <Data> element with multiple child elements

<ArrayOfTask>
  <Task>
    <Name>Test Delivery Task for API</Name>
    <Description>My comments about this task go here</Description>
    <ExternalId>1234</ExternalId>
    <TaskType>Delivery</TaskType>
    <Status>Not Started</Status>
    <Data>
       <VEHICLE_TYPE></VEHICLE_TYPE>
       <NUMBER_OF_WHEELS>18</NUMBER_OF_WHEELS>
    </Data>
  </Task>
</ArrayOfTask>

Task Address Properties

Most work orders have an address where the work will be performed. You can attach the address object to the message body to send in the address.

Geocoding Addresses

You can also specify a lat/lon location (as y and x coordinates) if you have a location for that work order already. You do not need to specify the street address details if you have the GPS location of the task and you do not have a street address. However if you specify the street address in the API call and omit the location, we'll geocode the address for you and convert it into a GPS location.

Note that GPS coordinates are GPS coordinates for lat/lon based on WGS84 coordinates and the API keys are lowercase y for Latitude and lowercase x for Longitude.

Currently Field Squared cleanses all addresses that come in and will auto-correct Zip code and other fields to best match the input addresses.

Sample Address messages snippets

Address JSON sample

   "Address": {
      "Street": "1514 Blake St",
      "Unit": "Suite 200",
      "City": "Denver",
      "State": "CO",
      "Zip": "80202-1322,
      "Location": {
        "y": 39.749911,
        "x": -105.000026
       },
     },

Address XML sample

   <Address>
     <Street>1514 Blake St</Street>
     <Unit>Suite 200</Unit>
     <City>Denver</City>
     <State>CO</State>
     <Zip>80202-1322</Zip>
     <Location>
        <y>39.749911</y>
        <x>-105.000026</x>
   </Address>

Remember that if you omit part of the record and the record exists, then only the parts of the record that have been specified will be updated.

For example, this API call will update a Task record and update the GPS coordinates only.

<ArrayOfTask>
  <Task>
    <ExternalId>1234</ExternalId>
    <Address>
       <Location>
          <y>39.749911</y>
          <x>-105.000026</x>
       </Location>
    </Address>
  </Task>
</ArrayOfTask>

Assigning the Task to an Asset

If you have a work order or job that has to be created for a specific asset in the field (eg. a compressor) then you can link the task to the asset and the asset to the task whenever you create or update the task record using the Assets key on the Task API.

   "Asset": "abcd1234"

In order to link the Task to the Asset, the asset must already exist in Field Squared at the time the task is created. The Assets property is a key on the Task that takes a list of assets (you can link a task to multiple assets – we recommend generally only linking it to a single asset).

The Asset property is a single ID of an asset to link the task to. The ID can either be the Field Squared internal ID or the External ID of the asset that you used when importing assets into our system. We recommend the External ID of the asset record for most cases. While a task can support being linked to multiple assets, we only support linking to a single asset through our API when creating or updating Tasks.

JSON worked example

Say you created an asset in our system using our Assets API

[
  {
     "Name": "Well site ABC",
     "ExternalID": "000123",
     "Type": "WELL_HEAD",
     "Data":{
        "FILTER_SIZE": "202"
     }
  }
]

Now you can create a task for this asset and link the two together:

[
 {
   "Name": "My Taskf for Well site ABC",
   "Status": "Not Started",
   "ExternalId": "1234",
   "TaskType": "Inspect",
   "Asset": "000123"
  }
]

 

XML worked example

Say you created an asset in our system using our Assets API

<ArrayOfAsset>
   <Asset>
      <Name>Well site ABC</Name>
      <ExternalID>000123</ExternalID>
      <Type>WELL_HEAD</Type>
      <Data>
         <FILTER_SIZE>202</FILTER_SIZE>
      </Data>
   </Asset>
</ArrayOfAsset>

Now you can create a task for this asset and link the two together. Note that the Assets property is an array of strings, so there's more decoration of the XML elements required to make this work than in the JSON example:

<ArrayOfTask>
  <Task>
    <Name>New job for Well site ABC</Name>
    <Description>My comments about this task go here</Description>
    <ExternalId>1234</ExternalId>
    <TaskType>Inspect</TaskType>
    <Status>Not Started</Status>
    <Asset>000123</Asset>
  </Task>
</ArrayOfTask>

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.

Was this article helpful?

Yes No

Related Articles