# Object Helpers

The Object Helper helps you interact with your workflow objects more fluidly, professionally and easily.

## Overview

The Object Helpers connector allows you to **interact with objects more easily and efficiently**, depending on your workflow needs.
Think of it as a 'tidier' way of dealing with data from multiple steps, sources and / or databases.
It primarily helps users alter their data into a format which subsequent steps can then work with more proficiently.
See our operation summaries below for more ideas and information on your potential data manipulation options.

> **Info:** **USER TIP**: A user can also use the Object Helper to create an object from the data gathered throughout the workflow steps, and then send said object to another workflow using the [Callable Trigger](https://tray.ai/documentation/connectors/trigger/callable-trigger). See our documentation for more details.

## Object Helper Templates

Below are some relevant templates you may wish to use or learn from. The full range can be found in our [Templates Library](https://tray.io/documentation/templates/).
Templates demonstrate **pre-configured best practices / common use cases** as well as examples of **how to use** this connector and **how best to integrate it** with others.

> **Warning:** **IMPORTANT!** Please make sure you **read the notes and instructional sections on this page before using any of these templates**. A basic understanding of this connector's capabilities will help avoid potential pitfalls during your own build process.

## Important notes

### Compatible objects

Incompatible objects will not always stop your workflow from running.
Please make sure that your 'object types' are compatible i.e. what your Object Helper is expecting to retrieve. Such as an array of objects vs a single object, or that the formatting of the objects themselves are correct.

## Operations

## Add Key / Value pairs

**Adds** **fields** to a pre-existing object
Or creates a new object from scratch
Then **returns everything** in the form of **a 'new' single object**

### Explanation

You can use this operation to create a new object from scratch or to add new Key / Value pairs to pre-existing objects.
This image showcases two sets of client details (two objects) which need to merge.
A missing value from the original object: `phone_number` is available in the second.
The 'Source' uses a jsonpath to iterate over **a list array** of incoming objects. The 'Key' is set while the appropriate 'Value' is dynamically taken from the previous Google sheets step.
**The result being a singular "blended object"**.
![obj-helper-add-key-value-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-f3a321da_oh-full%201.png)

### Important notes

Note that\*\* the\*\* **source object can be either empty or already populated** with properties and \*\*therefore overwritten. \*\*
If you are adding to a pre-existing object it is **good practice** to make sure the case you use (such as `snake_case` or `Sentence case`) match.

> **Info:** **USER TIP**: If you need to update/ create a new Value based off a pre-existing Key, use the [Add Value by Key](https://tray.ai/documentation/connectors/helper/object-helper/#add-value-by-key) operation instead.

## Add Value by Key

Updates the value of a particular field

### Explanation

This operation allows users to **update and / or add a singular Value via the Key** **specified**.
It is useful in situations when Value's might not have guaranteed consistency.
The new version of the client object will have an updated Value, set to a predefined Key.
![obj-helper-add-value-by-key-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-f9f9b3dd_Group%208.png)

> **Info:** **USER TIP**: If you need to return a singular object (i.e. create both the Value and the Key in question), use the [Add Key/ Value pairs](#add-key--value-pairs) operation instead.

## Contains

Checks if an object contains a particular field.
Returns:

* **True** if an object contains your specified field
* **False** if otherwise

### Explanation

Think of this as an "object specific Boolean condition".
![oh-contains](https://tray.ai/documentation/images/connectors/helper/object-helper/4YRBG5bJIvEh6d8C0P9Z9Y_oh-contains.png)

### Important notes

Please\*\* make sure you reference the Key and not the Value of your field\*\*.
Otherwise you may get false positives / negatives.
![obj-helper-contains-results](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-a742378b_obj-helper-contains-results%20%281%29.png)

> **Info:** **USER TIP**: If you need to **return the Value of the data** itself, use the [Get Value by Key](https://tray.ai/documentation/connectors/helper/object-helper/#get-value-by-key) operation instead.

## Delete Key / Value pair

Allows you to delete a particular field from an object

### Explanation

This is useful when the Key and respective Values at hand are no good.
![obj-helper-delete-output](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-b82c7689_Untitled%2017.23.01.png)

## Enforce Object Structure

**Defines a structure** that the object **MUST adhere** to
**Once confirmed** any **additional fields** from the input are **also included**

### Explanation

Think of it as helping the user to create a "skeleton structure".
The property type for Object and Structure can be either **Object** or **String** (with valid JSON).
It is incredibly **useful for cases when you need an object to contain certain Keys** for data validation or uploading later on, but when the Values themselves may not yet be present or necessarily need to be correct.
![obj-helper-enforce-struc-rtn-null](https://tray.ai/documentation/images/connectors/helper/object-helper/5iDqnu8KpTvIggn549aKtX_asdf.png)
![obj-helper-enforce-struc-output](https://tray.ai/documentation/images/connectors/helper/object-helper/z7UV2X5SDG2pz5snI0iEW_Group%2010.png)

### Important notes

**This operation deals with Structure NOT Content**:

* Any **Keys that do not already exist** within the source object **will automatically be assigned** `null` Values.
  * Regardless of what you put into the property panel Value field.
* The property panel **Value field data will not be written into the object itself**.
  * Only the Keys will.
* **If both the Key and Value referenced in the structure already exists**, then\*\* they will remain as they were\*\* within the original source object.

### Video guide

> **Info:** **USER TIP**: You may find that our[ Fallback values feature](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/fallback-values/) a more effective and simpler way to deal with inconsistent data - especially when Service APIs do not return anything at all for fields with missing values and can cause errors in subsequent steps trying to pull those fields.

## Equals

Allows you to check if two objects are the same.
Returns:

* **True** if the object **has exactly the same fields and values** as the comparative
* \*\*False \*\*if otherwise

### Explanation

The result will come in a boolean format.
![obj-helper-equals-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-73c87ce8_asldkfjhsd.png)
![obj-helper-equals-output](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-e27f958e_Group%2011.png)

### Important notes

Please note that **the operation will not highlight the differences**.
It will **only confirm if they are alike in every way - barring the listed order of Key / Values**.

> **Info:** **USER TIP**: If you need to find the difference between two objects, use the [Find Difference](https://tray.ai/documentation/connectors/helper/object-helper/#find-difference) operation instead.

## Find Difference

**Compares** two fields or objects.
Returns:

* **The differences** if there are any
* **Empty** if none\*\* \*\*found

### Explanation

The 'Source' and 'Target' that needs to be compared, whether they are Keys or Values or entire object themselves.
The results will depend on the variants found.
![obj-helper-find-diff-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-af0bec8c_asdfagsf.png)
![obj-helper-find-diff-output](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-a7a852c7_obj-helper-find-diff-output.png)

> **Info:** **USER TIP**: If you need to return a boolean indicator based off the difference between two objects use the [Equals](https://tray.ai/documentation/connectors/helper/object-helper/#equals) operation instead.

## Get Value by Key

Allows you to retrieve the **value of a particular field**

### Explanation

Using the 'Get Value by Key' operation means that **users can retrieve a Key's Value** be it string, number, etc.
![obj-helper-get-value-by-key-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-444cd817_oh-by-key-value.png)

### Important notes

The **Default value is great for setting fallback options**.
This is particularly useful when using systems that react poorly to null values or stop functioning when what is expected is not displayed.

> **Info:** **USER TIP**: If you need to return a boolean result use the [Contain](https://tray.ai/documentation/connectors/helper/object-helper/#contains) operation instead.

## Iterative transform

Goes through the fields available and **alters them as requested** (capitalize, camelCase etc.)

### Explanation

You may find it useful to think of this as a '[Text Helpers](https://tray.ai/documentation/connectors/helper/text-helper/)' operation specifically designed for use with objects.
As you can see from the example the original object in its 'native' state has an enormous amount of trailing whitespace.
Once this operation is used to clean up the excess it displays as expected and in accordance with most databases.
![obj-helper-iterative-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-86423c59_asdfaffdsfsd.png)
![obj-helper-iterative-output](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-9bf0c238_Group%2015.png)

### Important notes

This operation **cannot be applied to numerical, boolean and null Key / Values.**
**ONLY strings** are utilised by this operation.

### Formats

Below is a **full list of the formats and methods** that could be used.

### Formats

* camelCase
* kebab-case
* lower case
* snake\_case
* Start case
* UPPER CASE
* Sentence case
* Reverse
* Trim
* Trim end
* Trim start
* Deburr: Converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removes combining diacritical marks.
* Escape characters
* Unescape characters

## JSON Parse

Takes **JSON code** and **returns it as an object**

### Explanation

The purpose of this operation is to **transform data and turn string into objects**.
A common use case for this operation is when users are receiving data from a web server - as the data is always passed in a string format.
This means subsequent steps can use the data
![obj-helper-json-parse-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-6a8fe859_Group%2019.png)
![obj-helper-json-parse-output](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-87aa2af3_Group%2018.png)

> **Info:** **USER TIP**: If you need to turn an object into a sting use the [JSON Stringify](https://tray.ai/documentation/connectors/helper/object-helper/#json-stringify) operation instead.

## JSON Stringify

Takes an **object and transforms it into a JSON string**

### Explanation

This operation transforms an object into a JSON string.
This could be handy for when information coming in from a database needs to be formatted in such as way as to me more human readable - included in an outgoing email for example.
![obj-helper-json-string-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-b8ff68e9_asdfdasfdfas.png)
![obj-helper-json-string-output](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-fb734dbd_Group%2016.png)

> **Info:** **USER TIP**: If you need to turn an string into an object use the [JSON Parse](https://tray.ai/documentation/connectors/helper/object-helper/#json-parse) operation instead.

## Map Keys

Allows you to **change** the **field name** referenced \*\*and replace \*\*it **with your preferred name**

### Explanation

Once mapped, **this operation will seek and update the referenced Keys** with the new (preferred) Key reference.
This operation is ideal when a situation arises where the Values are consistent, but the Key references themselves do not automatically sync across databases.
**If the source Key does not exist, then no changes will be made** to the object in question.
![obj-helper-map-keys-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-8e36bd64_Group%2012.png)

> **Info:** **USER TIP**: Check out our documentation on the [Data Mapper](https://tray.ai/documentation/connectors/core/data-mapper/) core connector for more potential mapping use cases and operations.

## Merge two objects

Allows you to **merge two objects** into one
The **primary object** is the **main point of reference**

### Explanation

This operation **merges two objects into a singular object using the first as the main point of reference**.
If the same Key that exists in both then **the primary object's Value will be taken as the default**.
If there is a Key/ Value pairing within the second object that **does not exist in the first it will be included in the final** merged version.
![obj-helper-merge-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-9a7b215d_Group%2014.png)
![obj-helper-merge-output](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-07401bc3_Group%2013.png)

### Important notes

Should there be **trailing white space** found in any of its Values while merging, this operation automatically utilises a `Trim` method.
It will **automatically 'tidy up' the Keys and Values** if need be.

## Pick Values by Keys

Allows you to **return a Value** **by** its **reference** **field**

### Explanation

Both the Key and Value are returned as an array when you specify your fields.
![obj-helper-by-key](https://tray.ai/documentation/images/connectors/helper/object-helper/2B7AJOR2VInUEgu5uVO5nn_;aksdjfasldkfj.png)

## Properties Exist

This operation **checks** if the fields mentioned exist and returns:
A\*\* list **of** found items\*\*
A **list** of **not found items**
As well as a \*\*True/ False \*\*value for the original query

### Explanation

In total this operation returns a **list of Keys found**, a **list of Keys not found**, and a **boolean result** which indicates whether all the Key lists themselves were collected.
The output image shows which of the properties sought are present or missing.
![obj-helper-props-exist-properties](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-0ef24bdd_asdf.png)
![obj-helper-props-exist-output](https://tray.ai/documentation/images/connectors/helper/object-helper/cad75b37-5086c12f_obj-helper-props-exist-output.png)

### Video guide

## Remove Null Values

Allows you to **Delete** any fields with **null** or **empty** values

### Explanation

This operation will remove all the Key / Value pairs within your object which contain `null` values.
You can also select 'Empty string' or 'Both'.
![obj-hlpr-delete-null](https://tray.ai/documentation/images/connectors/helper/object-helper/p4mPnYOCz92QuYEC0IUWw_asdkfjnasd;f.png)