Working with the Claris Studio connector

The Claris Studio connector is a powerful and useful tool for integrating your Claris Studio data with the rest of the Claris platform as well as third-party apps. To begin using the connector, see:

To be successful with this connector, there are two concepts that you should familiarize yourself with: Field resolution and querying records.

  • Field resolution

  • Querying records

Field resolution

When Claris Studio connector steps return record data, for example with the Get record action, they 'resolve' the fields by inserting more semantic data, which makes working with the JSON-based content that's returned by the API more user-friendly. These semantic fields can then be more easily used as step data in subsequent steps in a flow. See Viewing flow history and Using step data.

For example, the metadata fields CreatedBy and ModifiedBy are expanded to include the name and contact information of the user who edited the record.

Copy 
{
  "CreatedBy": {                       // Name & contact details are added
    "FullName": "Johnny Appleseed",
    "ID": 1,
    "Contact": {
      "Type": "Email",
      "Value": "johnny.appleseed@example.com"
    }
  },
  ...
}

The Claris Studio connector will also provide metadata on complex fields like drop-downs, which would otherwise be a list of simple key-value pairs.

Copy 
{
  ...
  "Fields": {
    "Allergies": {                     // Field keys are mapped to the display label      
      "Options": {                  
        "Mold": "ea555123",            // Field option mappings are included
        "Animal Dander": "ea555121",
        "Shellfish": "ea555122",
      },
      "ResolvedValue": [        
        "Mold",
        "Shellfish"
      ],
      "FieldName": "Checkbox2",       // Field names are provided
      "Value": [                      // Field values are preserved
        "ea555123",
        "ea555122"
      ]
    }
}

In the example above, a record with allergy information is returned. The response body can be understood as follows:

  • "Fields" is an object that contains all the fields associated with this record.

  • "Allergies" is an object that corresponds to a checkbox field, which contains the options associated with that checkbox.

  • "Options" is an object that corresponds to the available choices in the checkbox field, in this case "Mold," "Animal Dander," and "Shellfish," which have corresponding behind the scenes values.

  • "ResolvedValue" is an array that indicates which options were chosen in the "Allergies" checkbox field, in this case "Mold" and "Shellfish."

  • "FieldName" is a field that corresponds to the value of the "Allergies" checkbox field behind the scenes.

  • "Value" is an array that indicates the behind the scenes values of the options chosen in the "Allergies" checkbox field.

    By having the resolved values of fields separated into their own arrays in the response body, it becomes much easier to select those values as step data for use later in a flow.

Querying records

This section provides a high level overview of Claris Studio’s query language syntax that is used in the Find records action. When querying records with the Find records action, you can perform complex and targeted finds by using a variety of operators that provide different ways of locating data within a table. Query operators are prefixed with a dollar sign ( $ ).

Available operators:

  • $limit

  • $skip

  • $select

  • $sort

  • $filter

$limit

The $limit operator defines the maximum number of records to return in a result set.

The $limit operator data type is a positive integer or string equivalent. If no $limit is specified, the default limit is 25. The maximum result set size per request is 100.

Example

Copy 
{
    "$limit": 5
}

$skip

The $skip operator offsets the records returned from a query.

The $skip operator data type is a positive integer or string equivalent.

Example

Copy 
{
    "$skip": 5
}

$select

The $select operator defines what fields from the record result set to return.

The $select operator is defined as a $select key and object value. The object value is currently unused and reserved for future use.

Example

Copy 
{
    "$select": [{ "ID": {}, "Fields.Name": {} }]
}

$sort

The $sort operator defines the order of records returned.

The operator is defined as a $select key and object value to allow options to be included for each field. By default, sorts are in ascending order by the specified field unless the $desc (descending) option is used. The $sort operator allows for more than one field to be specified. When more than one field is specified, the sort is updated from left to right.

Example

Copy 
{
    "$sort": [ { "Fields.Name": { "$desc": true }, "ModifiedOn": {} }]
}

$filter

The $filter operator.

Copy 
{ '<operator>': { '<field.Name|field.DisplayLabel>' : '<value>'  } }

$eq / $neq

Matches values that are equal to or not equal to the specified value.

Example

Copy 
{
  "$filter": {
    "$eq": {
      "Fields.Allergies": "Animal Dander"
    }
  }
}

$gt / $lt / $gte / $lte

Matches values that are greater than, less than, greater than or equal to, or less than or equal to the specified value.

Example

Copy 
{
  "$filter": {
    "$gt": {
      "Fields.Age": 5
    }
  }
}

$regex

Provides regular expression (regex) pattern matching capability. Supports Perl compatible regular expressions (i.e. "PCRE" ) version 8.42 with UTF-8 support. An optional $ci boolean property can be included to indicate a case sensitive or insensitive search

Example

Copy 
{
  "$filter": {
    "$regex": { 
      "Fields.First Name": "^Da",
      "$ci": true
      }
    
  }
}

$in / $nin

Returns one record for each distinct sets of records that share the same value in or not in a found set.

Example

Copy 
{
  "$filter": {
    "$in": {
      "Fields.Allergies": ["Animal Dander", "Household Chemicals"] }
    }
  }
}

$exists

Checks if the field exists in the record.

Example

Copy 
{
  "$filter": {
    "$exists": { "Fields.Allergies": false } 
    }
  }
}

$and / $or / $not / $nor

Joins query clauses together to enable complex queries.

Example 1 - Find records where Fields.Allergies does not exist and Fields.Age is greater than 5

Copy 
{
  "$filter": {
    "$and": [
      { "$exists": { "Fields.Allergies": false } },
      {
        "$gt": {
          "Fields.Age": 5
        }
      }
    ]
    
  }
}

Example 2 - Find records where Fields.Allergies does not exist or the Fields.Age is greater than 5.

Copy 
{
  "$filter": {
    "$or": [
      { "$exists": { "Fields.Allergies": false } },
      {
        "$gt": {
          "Fields.Age": 5
        }
      }
    ]
    
  }
}

Example 3 - Find records where Fields.Age is not greater than 5.

Copy 
{
  "$filter": {
    "$not": {
      "$gt": {
        "Fields.Age": 5
      }
    }
  }
}

Example 4 - Find records where Fields.City is neither Dublin nor Napier.

Copy 
{
  "$filter": {
    "$nor": [
      { "$eq": { "Fields.City": "Dublin" } },
      { "$eq": { "Fields.City": "Napier" } }
    ]
  }
}

Additionally $and / $or / $not / $nor operators can be nested. The following query will find records where Fields.Allergies does not exist, Fields.Age is greater than 5 and Fields.City is either Dublin or Napier, but Fields.Zipcode is not 25533 or 44811.

Copy 
{
  "$filter": {
    "$and": [
      { "$exists": { "Fields.Allergies": false } },
      {
        "$gt": {
          "Fields.Age": 5
        }
      },
      {
        "$or": [
          { "$eq": { "Fields.City": "Dublin" } },
          { "$not": { "$eq": { "Fields.City": "Shaanxi" } } },
          { "$eq": { "Fields.City": "Napier" } }
        ]
      },
      {
        "$nor": [
          { "$eq": { "Fields.Zipcode": 44811 } },
          { "$eq": { "Fields.Zipcode": 25533 } }
        ]
      }
    ]
  }
}

Notes 

  • File upload size is limited to 25 MB.

  • The following fields are not currently visible in response data: Rich text, Signature, Comment, and Calculation.