Field Data API

API Explorer The OpenAPI description for this API is available to view and download here.

This is a service which facilitates the flow of data to and from the field. It is an external API that provides mechanisms for creating, updating, retrieving, and deleting field data.

Data must conform to the appropriate schema when it is uploaded.

Jobs will be processed and have their features extracted when new data comes in.

Schemas

To read about core and job type schemas used in the Field Data API see the Design Patterns documentation.

Common Field Data Service Workflows

• Get List Project Tenancies

  gets a list of all projects the user has access to, allows filtering with the Match String. This is useful if you forget the projectTrn/projectId

• Get List Jobs

  List all Jobs associated with a project. This is useful if you forget the jobTrn/jobId. The List Jobs endpoint also contains accommodations for an RSQL filter expression.

• Get Job details

  This is important for getting values like the eTag which change often.

• Creating a new Job

  A minimum JSON body for creating a new job

{
  "name": "any string",
  "jobType": "any string although `Survey` has additional logic",
  "lifeState": "ACTIVE",
  "attributes": {}
}

• Uploading a File and creating an Attachment

  1. Call Upload file(s) endpoint make a note of fileTrn which will be needed later and uploadUrl which is a signed URL for AWS S3
  2. Using the uploadUrl upload a file to AWS S3

  curl --upload-file <path/to/file> <uploadUrl from part 1>

  3. Call Get Job Details to get the current eTag value of the job

  4. Call the Add Job Attachment(s) endpoint be sure to use the current eTag value you got from part 3

     A minimum JSON body for adding an attachment

  {
    "attachmentId": "<fileTrn from part 1>",
    "tags": []
  }

  5. Congratulations! File is uploaded and attached to the job. if the file is of the type *.job and has the tag RootDataFile it will be sent to the Job Converter for processing. You should see a *.jxl file also be attached to the job in 10 seconds or so.

• Patch a Job

  uses JSON Patch Operations to update the Job object.

  minimum JSON body for updating the attributes object

{
  "op": "add",
  "path": "/attributes",
  "value": {
    "description": "desc",
    "status": "NEW",
    "priority": "LOW",
    "tags": [],
    "assignees": []
  }
}

• Update a Job

  replaces the job object with a new job object.

  minimum JSON body

{
  "name": "Testing",
  "jobId": "trn:jobs:job:b402c4b8-aa6c-4b77-b161-1b1567844737",
  "jobType": "Survey",
  "attributes": {
    "description": "desc",
    "status": "NEW",
    "priority": "LOW",
    "tags": [],
    "assignees": []
  }
}