@grouparoo/calculated-property

Last Updated: 2021-09-02

Grouparoo's Calculated Property plugin enables you to write a custom function to generate a new property based upon other existing Grouparoo Profile Properties.

This guide will show you how to work with the Calculated Property plugin to create a custom Calculated Property

Install the Calculated Property Plugin

To work with the Calculated Property plugin, you must first install it in an existing Grouparoo project. You can do this using the install command from our CLI:

$ grouparoo install @grouparoo/calculated-property

This adds the package to your package.json file as a dependency, and also drops the plugin in the grouparoo.plugins section in that same file, which enables it.

// package.json
{
// ...
"dependencies": {
"@grouparoo/calculated-property": "...",
// ...
},
"grouparoo": {
"plugins": [
"@grouparoo/calculated-property",
// ...
]
}
}

Once the plugin is installed, you'll be working primarily with the CLI's configuration commands to get everything set up.

Create a Calculated Property App

With Grouparoo, an App is how we establish a connection with a source or destination. Add this connection by generating an App:

$ grouparoo generate calculated-property:app my_calculated_property_app

This will generate a file at config/apps/my_calculated_property_app.js. Open this file and edit the connection details to match your desired configuration. Here is an example of what this config object will look like after generation:

// config/apps/my_calculated_property_app.js
exports.default = async function buildConfig() {
return [
{
class: "app",
id: "my_calculated_property_app",
name: "my_calculated_property_app",
type: "calculated-property",
options: {
}
},
];
};

Create a Calculated Property Source

The Calculated Property Source is a specific type of Source. The focus of the Calculated Property plugin is the ability generate custom properties based upon a JavaScript function in the Property configuration.

In order to generate the property, you will first need to generate a parent source.

You can generate a Calculated Property Source using the generate command. You must specify a parent, which should match the id of the App you created.

The Generator for Calculated Property Sources looks like:

$ grouparoo generate calculated-property:source calculated_source --parent my_calculated_property_app

This generates a file at config/sources/calculated_source. Calculated Property Sources act primarily as placeholders. The real fun comes when you get to the Property configuration.

exports.default = async function buildConfig() {
return [
{
class: "source",
id: "calculated_source",
name: "calculated_source",
type: "calculated-property-import",
appId: "my_calculated_property_app",
}

Calculated Property Properties

After you generate a Source, you get to see the real power of Calculated Properties. You can generate a Calculated Property through the CLI:

$ grouparoo generate calculated-property:property full_name --parent calculated_source

The Property generator will drop individual a file in the config/properties directory. Edit this file to match your desired configuration. All Calculated Properties are required to have a valid customFunction option.

exports.default = async function buildConfig() {
return [
{
id: "full_name",
name: "full_name",
class: "property",
sourceId: "calculated_source",
type: "string",
unique: false,
identifying: false,
isArray: false,
options: {
customFunction: customFunction,
},
filters: null,
},
];
};
function customFunction() {
// write your custom function here
// use mustache variables to reference the keys of any properties you would like to reference
}

Calculated Property Custom Function

The Property config object for Calculated Properties has a single option. This option is the customFunction option and it is where the real magic happens with Calculated Properties.

At the bottom of your config file for a Calculated Property, there will be an empty function called customFunction. Here, you can write how you would like to generate your new Property.

Custom functions can do anything from string concatenation or splitting, to performing calculations, to returning a conditional value. Your custom function must return a value, though that value is allowed to be null.

To reference other Grouparoo Properties, use mustache variables to refer to the key of that property. A Property's key can be found in its config file. If no key is present, the default key is a Property's id.

To calculate a full_name Property, you would fill in the configuration as follows using mustache variables to reference existing properties:

function customFunction() {
return "{{firstName}} {{lastName}}"
}

customFunction is executed Profile by Profile, so the value of each Profile's first_name and last_name Properties are parsed directly into the function, which is why it is quoted in order to evaluate as and return a string.

You can write customFunctions using string, number, boolean, anddate property types. All mustached variables are returned as the string value of their value. This means if you want to use an integer or float type for calculation, you will have to parse it. For example:

const ltv = parseFloat("{{ltv}}")

For example, to use an existing property total_cost and total_sales to calculate a profit_margin property, run:

function customFunction() {
return parseFloat("{{total_sales}}") - parseFloat("{{total_cost}}")
}

You can also do coalescing. For example, say you want to add a primary_phone and your first pick is cell_phone_number, if there isn't a cell, you want work_phone_number, and if there isn't one of those a home_phone_number, otherwise you want null.:

function customFunction() {
return "{{cell_phone_number}}" || "{{work_phone_number}}" || "{{home_phone_number}}" || null;
}

To replace a null value, you can evaluate the string from the mustache variable against an empty string and use a conditional. Here we'll make a property that flags any account missing an email:

function customFunction() {
return "{{email}}" !== "" ? "{{email}}" : "unknown"
}
A Calculated Property's customFunction can use whatever synchronous JavaScript you would like to generate your property. Please note that:
  • Using require is not currently supported
  • Async functions are not currently supported
  • Your function must return a value (or null, but not undefined)to pass validation

Validating & Applying Your Config

You can validate your config at any time using the validate command:

$ grouparoo validate

And you can apply that config (save it to your Grouparoo application's database) using the apply command:

$ grouparoo apply

Calculated Property Next Steps

Once you have the plugin installed, App and Source created, and Property configured, you are ready to validate, apply, then import or export your data!