Connectors / Helper / Object Helper
Object Helper
Interact with your workflow objects more fluidly, professionally and easily.Overview
The Object Helper connector allows users to interact with objects more easily and efficiently depending on their workflow needs.
Think of the Object Helper connector as a 'tidier' way of dealing with data from multiple steps and databases, i.e; it helps a user put all their data into an format which all subsequent steps can then handle.
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. See our documentation for more details.
TRAY ACADEMY: Interested in getting to grips with even more features? Why not check out our academy course: Object Helpers. It covers basic concepts, potential use cases, and some of the best ways to utilise specific operations.
Below is listed what each Object Helper operation is capable of achieving, along with how they might be utilised within various scenarios to a users own advantage.
Basic Use Case
Users may have more than one source of client contact information which needs to be consolidated into a singular database. Therefore the incoming objects may need to be edited in order to maintain a singular architectural structure.
This scenario uses both Salesforce and Hubspot to try and replicate how one might use the following operations, under such circumstances. Before relocating back to the original source (Salesforce), the objects must be checked, merged and updated removing any potential inconsistencies.
Note that the workflow in question begins with a Manual trigger and a Salesforce 'Find records' service connector, in order to initiate the run and generate a list of client objects with which to start working with. A Loop collection connector is used in most cases in order to iterate through Salesforce and Hubspot client contact details, depending on the scenario. Google sheets and other connectors are used intermittently in order to best exemplify the potential of the Object Helper operations at hand.
Operations
Contains
Description: Returns true if an object contains an assigned Key, false otherwise.
Think of this as a object specific Boolean condition. The answer will only ever return true or false depending on the circumstances.
USER TIP: If you need to return the Value of the data itself, use the Get Value by Key operation instead.
As this scenario wishes to consolidate the two databases, having a check in place to confirm whether or not certain information already exists within the client objects themselves is good practice. This is where the Contains operation comes in handy.
For example, depending on the Sales representative at the time, they may or may not have been able to garner a clients phone number, and therefore the field Value might be available or missing depending on the call.
Using the Contains operation, set the 'Source' field to the output of the Loop step (or hardcode it in as per your use case), and then add in the 'Key' that you wish to check is missing or not, in this case phone_number.
Here is some example output from the Debug panel which demonstrates positive and negative test results. These have been run using phone_number, client_number, and a client email address opolini4@icio.us. Values are not recognised even if they are in fact present and accounted for.
The result will be a simple true or false, which you can later use to build your resulting workflow actions from.
Add Key/ Value pairs
Description: This operation adds Key/Value pairs from a list array, to a source object as properties, and returns a singular object. The source object can either be empty or already populated with properties. The list array contains objects and each object will have the fields Key and Value.
Simply put, this operation not only allows you to add new Values to pre-existing objects, but users can use this to create a new object from scratch if need be.
USER TIP: If you need to update/ create a new Value based off a pre-existing Key, use the Add Value by Key operation instead.
Within our scenario, one database contains client information which the other doesn't. In order to consolidate and update the individual client objects. Having already used the 'Contains' Object helper operation in order to verify whether or not the client objects do indeed contain a phone_number Key; now comes the turn of the Add Key/ Value pairs operation.
Setting the 'Source' to the Loop result in this instance means iterating over the list of objects will be possible. From there the appropriate Key is hard coded into the field 'List' -> 'Pairs' -> 'Key' field. The 'List' -> 'Pairs' -> 'Value' field is taken from the Google sheets step and is using a jsonpath to get the details (aka, the phone number data).
Here is an example of how the Google object looks in the debug panel and the 'Get rows' operation used for further clarity:
Note that the new Key is kept consistent with the Salesforce data format (i.e. snake_case), rather than the Google sheets format (Sentence case).
The output panel displays in details how and what the operation finds as a result:
Now the that workflow knows this information is missing from the original object, it can update the object accordingly.
Get Value by Key
Description: Get a Value from an object by its Key.
This operation in best used when the Value (resulting data) of the Key in question alone is required.
USER TIP: If you need to return a boolean result use the Contain operation instead.
Imagining a use case similar to the one described above, instead of using 'Contains' to return a true or false verdict, using the Get Value by Key operation means that users can retrieve a Key's actual data Value.
Setting the 'Source' to the Loop result in this instance means iterating over the list of objects will be possible. From there the 'Key' as state, and the 'Value' as a jsonpath linked to the relevant clients Google sheet, aka the alternative data source, means the Value alone will be displayed.
The users result should be similar to: result: "xxxxxx" depending on the data found in the object, which in this case is an empty string:
For more details on how your own workflow is running, open the Debug panel as displayed below:
Add Value by Key
Description: Add a Value to an object by its Key.
This operation allows users to update and/ or add a singular Value via the Key specified. This means should a Value not be consistent or relative to your needs, it can be changed provided the Key is available.
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 operation instead.
Having checked the output of the client objects in question,
Having used the 'Get Value by Key' operation previously the user notices that there is data missing, more specifically the state information that each client is located at. The next logical step to resolve this matter would be to use the Add Value by Key operation in order to update this empty string.
Once more utilising the Loop results in order to iterate over the client list, the source is set. Having hard coded in the Key, this use case uses the Google sheet client data that is available in order to set the Value (using a relevant jsonpath).
The new version of the client object will have an updated Value, set to this predefined Key as a result.
See your logs for more details:
Properties Exist
Description: Check if a list of properties are found in an object. If any are not found, a list of the properties not found is returned.
This operation essentially checks if a list of properties or Keys are available within an object. It will return a list of Keys found, a list of Keys not found, and a boolean result as well; indicating whether all the Keys lists were indeed found.
Within this scenario the user has come to realise that there are more elements than originally thought to be missing. Therefore it is best to update the 'Contains' operation and replace it with the Properties Exist operation instead. The Keys which are being referenced in this example include country, email and test.
The output generated shows which of the properties sought are present or missing. If there is only a single item to check for, a boolean result and a list will still be generated.
Full a full view of the step in question, view the Debug panel image below:
Check out the video guide below for more information on how and when to the Properties Exist operation for more details.
Enforce Object Structure
Description: Define a JSON structure which the output object must adhere to. The output object will contain at least the defined structure along with any additional fields from the input. The property type for Object and Structure can either be Object or String (with valid JSON).
The enforced object structure operation takes an input object as your source, and checks for any Keys that are listed under the field 'Structure'.
Please be aware that this operation is set to return null values for any property Keys that do not already exist within the source object. As opposed to the default value the users set (within the 'Structure' field heading):
Think of it as helping the user to create a "skeleton structure" for either the Values to come or simply because the database structure you are working in conjunction with, requires them (even if as a user you do not). This 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.
You may find that our Fallback values feature is 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
As can be seen from the output panel, the structure as outlined in the properties panel, has been added to the client object as requested:
For more details on how your own workflow is running, open the Debug panel as displayed below:
Check out the video guide below for more information on how and when to the Enforce Object Structure operation for more details.
Delete Value by Key
Description: Delete a Key/ Value pair by its Key reference.
This is useful when the Values at hand are no good, and a simple removal would serve your purpose.
The client objects coming in from Salesforce may already have phone_number allocated to them, but having checked, the user is now aware that they might be out of date. As a result, should this Value be found, our user would like to delete the number on record in order to leave a clean slate for the next stage of development.
Set the source as the object to work with, and the Key as per your use case (eg, phone_number).
Each client object is checked to see if said Key's Value is currently available and if so, the Value is permanently deleted.
As you can see from this output panel, there is technically nothing to display as what was located, was in turn destroyed:
For more details on your Delete Value by Key results, open the Debug panel as displayed below:
Equals
Description: Returns true if an object is exactly the same as another object, false if otherwise.
When comparing two databases, with "the same information", it is often good practice to double check your data. This is a simple boolean replica operation, in that once a comparison has been made a true or false statement is returned.
USER TIP: If you need to find the difference between two objects, use the Find Difference operation instead.
This scenario envisions a cross database comparison between the available client information recorded in Salesforce, and the information found on Hubspot for the same client. Iteration through both loops will compare the clients individually. The main difference under these circumstances being that there are two different Keys for the client, client_number vs reference_number.
Having set the operation to 'Equals', and created a jsonpath comparison between the two lists (and the individual objects within them) the result can clearly been seen in the Debug panel that while all else remains equal, the singular Key difference is enough to return a false output.
The operation will not highlight the differences, only compare the two objects in order to confirm if they are alike in every way.
For a more complete view, open the debug panel and see the results yourself:
Find Difference
Description: Finds the difference between two objects and returns it.
This operation returns the contested point in question, be it the Keys or Values or entire object themselves if they are not in sync with one another.
USER TIP: If you need to return a boolean indicator based off the difference between two objects use the Equals operation instead.
This scenario envisions a cross database comparison between the available client information recorded in Salesforce, and the information found on Hubspot for the same client. Iteration through both loops will compare the clients individually. The main difference under these circumstances being that there are two different Keys for the client, client_number vs reference_number.
Simply input the 'Source' and 'Target' that needs to be compared (in this case, each client object from the opposing databases).
Depending on the variants found, the returned items will follow suit.
See your logs for more details:
Map Keys
Description: Given an object, transform the given property's Key names.
Once mapped, this operation will seek and update the Keys referred to, with the new (preferred) Key reference. If the source Key does not exist, then no changes will be made to the object in question. This operation is ideal when a situation arises where the Values are consistent, but the Key references themselves do not automatically sync across databases.
USER TIP: Check out our documentation on the Data Mapper core connector for more potential mapping use cases and operations.
This scenario imagines that most client contact information is consistent (that is to say the Values), however the "client reference Key" used within each service varys. For the sake of consistency, the Keys for the client objects need to be uniform. This is a perfect example of when a user would use Map Keys.
Once the operation is set, simply ascribe the Key that needs to be updated under 'Key name', and its preferred reference under 'New key name'. The end result will display the new Key name within the updated object itself.
In this case, the Salesforce client_number is to become the Hubspot reference_number.
Always reference the Debug panel for more details.
Merge two objects
Description: Merge two objects. If there is any property specified in both objects, the one specified in the first (source object) will be used.
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, the former objects Value will be taken as standard. If there is a Key/ Value pairing within the second object which does not exist in the first, it will exist within the final version due to the merge.
The scenario at hand has three sources of potential information, and in this particular instance the workflow checks whether the object meets a basic client Key reference, before moving on to the next stage. That is; to merge the two client contact information objects, from Hubspot and Salesforce, into one.
The user must be very sure which object they wish to use as their main reference point, else the output will be incorrect. In this case, both the Salesforce and Hubspot client contact data sets are being merged; therefore the jsonpath loops displayed in the 'Source' and 'Target' fields are iterating through each client contact object, in order to compare and find contrasting details within (if any).
As you can see, both versions of the same client object, contain details the other object does not. Salesforce contains: client_number, whereas Hubspot has: sales_rep. Both have a phone_number. Due to the nature of this operation and Salesforce being the first object referenced in the 'source' field, it means the final object will contain both a client_number and a sales_rep Key/ Value pair, as well as Salesforce's Value for the phone_number.
This is why the while the phone number is technically the same, the numerical version is used in the end result as opposed to the string version found in Hubspot's database.
PLEASE NOTE: This operation automatically utilises a
Trim
method should there be trailing white space found in any of its Values while merging. That is to say, there is an automatic 'tidy up' of the Keys and Values if need be.
Iterative transform
Description: Given an object, iterate through its properties, and transform the associated Keys and Values accordingly.
IMPORTANT!: This operation cannot be applied to numerical, boolean and null Key/ Values, only
"strings"
are utilised by this operation.
Potentially there is a lot that can be done with this operation as there are so many formats that a user could choose from, in order to change the presentation format of their Key/ Value pairs. You may find it useful to think of this as a 'Text helper' operation, specifically designed for use with objects.
USER TIP: Check out our guide on Text Helpers for more inspiration.
Below is a full list of the formats and methods that could be used:
camelCase
kebab-case
lower case
snake_case
Start case
UPPER CASE
Sentence case
Reverse
Trim
Trim end
Trim start
Deburr
Escape characters
Unescape characters
Take this scenario under a new instance; that is to say, our user simply wants to migrate all their client information from one database to a second database with all other things being equal.
It is known thanks to the Debugger that the Keys for both Salesforce and Hubspot are in the format of snake_case, and the Values themselves are in Sentence case. The issue is that when it was originally transferred over the software used created unnecessary trailing whitespace.
Therefore it makes sense to use the 'Trim' option from the Values field, as it references both the start and end points of the strings in question. The results will be tidied up like so.
Set the 'Source' to the object in question, and select the Key or Value field as per the use case. In this instance, only the 'Value transform' field is used as the Keys themselves appear to have remained intact.
As you can see form the display, the object in its 'native' state has an enormous amount of trailing whitespace. Once deleted, the object displayed as expected in accordance to most databases.
For more details on your Iterative transform results, open the Debug panel as displayed below:
JSON Parse
Description: Take a JSON string/text and parse it into an object.
When this operation is used, it will transform the data and turn the string into an object. A common use for this operation is for when users are dealing with receiving data from a web server, as the data is always passed in a string format.
USER TIP: If you need to turn an object into a sting use the JSON Stringify operation instead.
Having received some new client details from an online marketing tactic, our user wishes to add these details into the client contact list as an object within its own right, so that it may be uploaded to the Salesforce database more easily.
Using a Form trigger and the CSV Editor connectors, a set up is created whereby the string can be interpreted by the Object Helper connector aka, the JSON Parse operation. The source is once more set as the object that the user wishes to transform.
If a user looks closely, they will notice that the string taken from the original online form, has been changed into an object within its own right.
The Debugger displays each step's process more clearly and helps users to get a better understanding of how and what the JSON parse operation is being transformed:
JSON Stringify
Description: Take an object and transform it into a JSON string.
When this operation is used, it will transform the data and turn the object into a string. This could be handy for when information that is 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.
USER TIP: If you need to turn an string into an object use the JSON Parse operation instead.
This scenario imaginges that the client contact data Saleforce needs to be included as part of an important sales document. As such, the client objects within the database needs to be transformed into strings.
Being one of the simplist operations of the Object Helper, means that once the 'Source' is specified the workflow does the rest:
The output panel display clearly indicates that the change has taken place successfully:
Full a full view of the step in question, view the Debug panel image below:
BEST PRACTICES: Whenever you do decide to create your own workflow, please make sure you take a look at our managing data best practices guide.