Catalogs API

In Field Squared, a 'Catalog' is an object that defines a lookup table or LOV.  Catalogs can be simple lists however they also support an N level hierarchy.  There are a number of components to a catalog:

• Template – Defines the fields for each Catalog item.
• Category Object – Defines a  'branch' of the catalog hierarchy.
  • Name – Defines the Name for the Category
  • Items – List of items, each item has the fields defined in the main Catalog 'Template' above.
  • Categories – List of category objects.  This property enables an N level hierarchy to be modeled.

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

Catalogs in Field Squared are written to the API as either a single catalog or a list of catalog objects. For most integrations we recommend doing batch updates of catalogs (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.

Catalog Object Payload

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

{
   "externalid": "Universe",
   "name" : "Universe",
   "lastupdated": "2016-02-12T23:20:14.099Z",
   "created": "2016-01-06T22:57:03.084Z",
   "data": {
      "Template": [
         {
            "CustomFieldDataType": "Text",
            "Key": "NAME",
            "Label": "Name",
            "_visible": true,
            "_index": 0,
            "_width": 2
         },
         {
            "CustomFieldDataType": "Text",
            "Key": "STATE",
            "Label": "State",
            "_visible": true,
            "_index": 1,
            "_width": 1
         },
         {
            "CustomFieldDataType": "Number",
            "Key": "MOONS",
            "Label": "Moons",
            "_visible": true,
            "_index": 2,
            "_width": 3
         }
      ],
      "Categories": [
         {
            "Name": "Solar System",
            "Items": [],
            "Categories": [
               {
                  "Name": "Planets",
                  "Items": [
                     {
                        "NAME": "Earth",
                        "STATE": "Solid",
                        "MOONS": "1"
                     },
                     {
                        "NAME": "Mercury",
                        "STATE": "Solid"
                     },
                     {
                        "NAME": "Venus",
                        "STATE": "solid"
                     },
                     {
                        "NAME": "Mars",
                        "STATE": "Solid"
                     },
                     {
                        "NAME": "Jupiter",
                        "STATE": "Gas"
                     },
                     {
                        "NAME": "Saturn",
                        "STATE": "Gas"
                     },
                     {
                        "NAME": "Neptune",
                        "STATE": "Gas ??"
                     },
                     {
                        "NAME": "Pluto",
                        "STATE": "Solid"
                     }
                  ],
                  "Categories": []
               },
               {
                  "Name": "Stars",
                  "Items": [
                     {
                        "NAME": "Sun",
                        "MOONS": "0",
                        "STATE": "Plasma"
                     }
                  ],
                  "Categories": []
               },
               {
                  "Name": "New Category"
               }
            ]
         }
      ],
      "Display": [
         "NAME",
         "STATE",
         "MOONS"
      ],
      "Columns": [
         2,
         1,
         3
      ]
   }
}

Working with Single Catalogs

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

Methods Supported: GET|POST|DELETE
URL: https://api.fieldsquared.com/workspace/api/catalog/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/catalog/1234
will retrieve the catalog 1234 from workspace 10. The structure of the Catalog returned will look like the payload above.

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

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

Working with Lists of Catalogs

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/catalog

Where workspace is the ID we assign to your company.

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

[
  {
    "Name": "Products",
    "ExternalId": "1234",
  },
  {
    "Name": "Services",
    "ExternalId": "1235",
 }
]

Field Squared supports batch updates of multiple catalogs, or sending through just a single catalog object in a request within a list.

Example 1
GET https://api.fieldsquared.com/10/api/catalog
This retrieves an array of catalog 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/catalog
This example can bulk create or update catalogs of type Boat where each item in the request will be created/updated in the Field Squared database.

View of Example Catalog

The Catalog example above, when viewed through the Field Squared App Builder UI, appears as shown below.  Clicking on the 'Integrations' button in the top right will display the shape of the object required when interacting with this type of catalog through the Field Squared API.

Once a Catalog control has been loaded, it can be used within a Task, Asset, Contact, User or Team custom field or can be included as a document control in a Document Template, as shown below: