Design Patterns

A collection of design patterns to be used when working with the Field Systems data services.

Attachment Tags

For example, an image file can serve various purposes such as a background map, design input, report, or field data.

When an image file is attached to a job, its purpose may need to be specified. This can be done by using the attachments Tag[] property when adding or updating the attachment.

We might want to define the following tags Background, Design,Report and FieldData.

Tags can be added using the PUT/POST /projects/{projectTrn}/jobs/{jobsId}/attachments end points. See swagger/ui for examples.

These tags should be declared in your application’s jobType schema using a $defs / attachmentTags definition. This ensures the enforcement of attribute naming rules. If your application uses the Jobs Service feature, don’t forget to include RootDataFile.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  ...

  "$defs": {
    "attachmentTags" : {
        "type" : "string",
        "description": "Possible tags are."
        "enum" : ["RootDataFile","Background","Design","Report","FieldData"]
    }
  }
}

Schema Metadata

Job data is stored in the attributes object of an individual job record.

These attributes follow the schema registered for each jobType and can be retrieved using the GET /schema/{jobType} API end point. This schema definition is managed by the jobType owner.

In addition to the normal JSON Schema type information, you can enhance this schema to add additional metadata for jobType attributes.

For instance, you might want to include SI storage units or fields that are only visible to administrators.

For this example we will add SI storage units to some attributes. Imagine we have the following schema types that need SI units.

"attributes": {
  "type": "object",
  "properties": {
    "area": {
      "type": "number"
    },
    "altitude": {
      "type": "number",
      "default": 0
    }
  }
}

The type information can be added like this.

"attributes": {
  "type": "object",
  "properties": {
    "area": {
      "si_units" : "sq_m",
      "type": "number"
    },
    "altitude": {
      "si_units" : "m",
      "type": "number",
      "default": 0
    }
  }
}

Once the schema definition has been updated it needs to be given to the Trimble Field Data Jobs Service team for publication in the Jobs Service. Once published applications will be able to GET the schema and use this new attribute metadata.