The Account Processor enables you to run your own logic on attributes associated to Accounts by writing Javascript.
Go to the Connectors page of your Hull organization, click the button “Add Connector” and click “Install” on the card.
After installation, you will be presented with the three column Dashboard layout. The left column displays the Input which is an Account with, segments and attributes, the middle column will hold your Javascript Code that transforms it to the Output of the right column. The Output itself displays the changed attributes of the account.
You can begin writing your own code right away, but you probably might want to gather some useful background information first. We recommend to start with the execution model which clarifies when your code is run before you move on to the data that is available as Input:
Read more about writing code:
The allows your team to write Javascript and transform data in Hull for Accounts. The Processor is your multi-tool when it comes to data in Hull.
The Processor can add traits
, update traits
for Accounts.
You can use the superagent
library (https://github.com/visionmedia/superagent) to call external services or send data to webhooks.
Async/await and ES6 are supported by the connector, allowing you to write elegant code.
Before writing your first line of code, it is vital to have a good understanding when this code will be executed:
The changes
object represents all changes to a user that triggered the execution of this processor and contains information about all modified data since the last re-compute of the user. Changes itself is an object in Javascript which exposes the following top-level properties:
changes.is_new
indicates whether the Account created is new and has just been created or not.
changes.account_segments
, which holds all account segments the Account has entered and left since the last recompute, accessible via changes.account_segments.entered
and changes.account_segments.left
. Each segment is an object itself composed of the following properties created_at
, id
, name
, type
and updated_at
.
changes.account
which is an object that is exposes each changed attribute as property whose value is an array. The array has the old value as the first argument and the new one as the second. For example, if the email is set the first time, you can access it via changes.account.domain
and the value will look like this [null,"www.hull.io"]
The following code shows an example of changes:
{
"changes": {
"is_new": false,
"account_segments": {
"entered": [
{
"created_at": "2017-09-01 09:30:22.458Z",
"id": "dfbdd69d-1e6d-4a58-8031-c721a88f71f6",
"name": "All Accounts",
"type": "account",
"updated_at": "2017-09-01 10:04:01.938Z"
},
// more segments if applicable
],
"left": [
// omitted for brevity
]
},
"account": {
"name": [null, "Hull"],
"domain": [null, "www.hull.io"],
"mrr": [null, "500"]
}
}
}
The account object consists of a nested trait hierarchy in Hull. This means you can access all traits directly by their name, e.g. to get the name of an account, just use account.name
in the code.
Accounts do have various identifiers: the Hull ID (account.id
), an External ID (account.external_id
), one or more anonymous_ids in an Array (account.anonymous_ids
) and Domain (account.domain
).
The following snippet shows an example of an account:
{
account: {
id: "7ad5524d-14ce-41fb-8de4-59ba9ccf130a",
"anonymous_ids": [
"intercom:5907854a8ez91d591a49b4c2",
"hubspot:999999"
// additional identifiers
],
external_id: "8476c4c7-fe7d-45b1-a30d-cd532621325b",
domain: "hull.io",
name: "Hull Inc.",
clearbit: {
name: "Hull Inc."
},
... // more attributes in nested hierarchy
},
[...] // omitted for clarity
}
Please note that the external_id
is only present if the account has been created via another connector such as the SQL importer or Segment.
You can access the segments for the Account via account_segments
which is an array of objects itself. Each segment object has an identifier and name that can be accessed via id
and name
and metadata such as type
, updated_at
and created_at
.
The following code shows an example of the account_segments
data:
{
"account_segments": [
{
"id": "59b14b212fa9835d5d004825",
"name": "Approved users",
"type": "users_segment",
"updated_at": "2017-09-07T13:35:29Z",
"created_at": "2017-09-07T13:35:29Z"
},
{
"id": "5995ce9f38b35ffd2100ecf4",
"name": "Leads",
"type": "users_segment",
"updated_at": "2017-08-17T17:13:03Z",
"created_at": "2017-08-17T17:13:03Z"
},
// additional segments
]
}
You can access the input data as described above, here is the summary of available Javascript objects:
Variable Name | Description |
---|---|
changes | Represents all changes in attributes and segments since the last re-computation. |
account | Provides access to the account’s attributes. |
account_segments | Provides a list of all account segments the belongs to |
Please note that some of the input data shown on the left might be fake data that showcases additional fields available in your organization but that might not be applicable to all users.
In addition to the input, you can also access the settings of the processor:
Variable Name | Description |
---|---|
connector | Provides access to processor settings, e.g. connector.private_settings gives you access to the settings specified in manifest.json as shown in the Advanced tab. |
variables | Provides the values that you can store in the Settings tab of the connector. Usually to avoid storing Access Keys in the code itself |
Now that you have a good overview of which variables you can access to obtain information, let’s move on to the functions that allow you to manipulate data.
Lets first explore how you can change attributes for Accounts. As you already know from the section above, there are three types of attributes, top-level, ungrouped and grouped attributes. Top-level and ungrouped attributes can be set with the not-overloaded function call
hull.traits({ ATTRIBUTE_NAME: <value> })
For naming conventions, see the Golden Rules section below.
Of course you can set multiple attributes at once by passing a more complex object like:
hull.traits({ ATTRIBUTE_NAME: <value>, ATTRIBUTE2_NAME: <value> })
Using this function signature, these attributes are stored at the top level for the target
If you want to make use of grouped attributes, you can use the overloaded signature of the function, passing the group name as source in the second parameter:
hull.traits({ bar: "baz" }, { source: "foo" })
Alternatively, you can pass the fully qualified name for the grouped attribute. Those two signatures will have the same results
hull.traits({ "foo/bar": baz });
If you want to “delete” an attribute, you can use the same function calls as described above and simply set null
as value.
hull.traits({ foo: null });
Given the distributed nature of computation, if you want to increment or decrement a counter, you need to take special care. Since the code might run multiple times in parallel, the following operation will not be reliable:
DO NOT DO THIS:
hull.traits({ coconuts: user.coconuts+1 });
To get reliable results, you need to use atomic operations
. Here’s the correct way to do so:
DO THIS INSTEAD:
hull.traits({ coconuts: { operation: 'inc', value: 1 } })
Where: - Operation: inc
, dec
, setIfNull
- Value: The value to either increment, decrement or set if nothing else was set before.
You can add or remove aliases to the processed Account with the following syntax:
hull.alias({ anonymous_id: "foobar:1234" });
hull.unalias ({ anonymous_id: "foobar:1234" });
The processor provides the following methods to help you:
Function Name | Description |
---|
| isInAccountSegment(<name>)
| Returns true
if the account is in the segment with the specified name; otherwise false
. Please note that the name is case-sensitive. | | enteredAccountSegment(<name>)
| Returns the segment object if the account just entered the segment with the specified name; otherwise null
. Please note that the name is case-sensitive. | | leftAccountSegment(<name>)
| Returns the segment object if the account just left the segment with the specified name; otherwise null
. Please note that the name is case-sensitive. |
The processor exposes several external libraries that can be used:
Variable | Library name |
---|---|
_ | The lodash library. (https://lodash.com/) |
moment | The Moment.js library(https://momentjs.com/) |
urijs | The URI.js library (https://github.com/medialize/URI.js/) |
request (deprecated) | The simplified request client (https://github.com/request/request) |
superagent | The simple and elegant request library (https://github.com/visionmedia/superagent) |
uuid | The uuid library (https://github.com/uuidjs/uuid) |
LibPhoneNumber | The google-LibPhoneNumber library (https://ruimarinho.github.io/google-libphonenumber/) |
Please visit the linked pages for documentation and further information about these third party libraries.
The uuid
library exposes the version 4 of the algorithm, and only accepts the first options
argument - other arguments will be ignored. As a result, here’s the way to use it:
const user_id = uuid()
//or
const user_id = uuid({ random: [ 0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea, 0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36, ] });
The LibPhoneNumber
library exposes a subset of the google-libphonenumber
library. Here’s how to use it
//PhoneNumberFormat is the PhoneNumberFormat object from the library;
//PhoneNumberUtil is an INSTANCE of the PhoneNumberUtil methods
const { CountrySourceCode, PhoneNumberType, PhoneNumberFormat, PhoneNumberUtil } = LibPhoneNumber;
const number = PhoneNumberUtil.parseAndKeepRawInput('202-456-1414', 'US');
console.log(number.getCountryCode()); //1
// Print the phone's national number.
console.log(number.getNationalNumber());
// => 2024561414
// Result from isPossibleNumber().
console.log(PhoneNumberUtil.isPossibleNumber(number));
// => true
PhoneNumberUtil
Checkout i18n.phonenumbers.PhoneNumberUtil
: https://ruimarinho.github.io/google-libphonenumber/#google-libphonenumber-methods-i18nphonenumbersphonenumberutil
Calling PhoneNumberUtil.parse("1234-1234")
will return an instance of PhoneNumber
, which has the following methods: https://ruimarinho.github.io/google-libphonenumber/#google-libphonenumber-methods-i18nphonenumbersphonenumber
Checkout the Docs for CountryCodeSource
, PhoneNumberFormat
, PhoneNumberType
which are statics
The request library is now deprecated. Processors using the request library will be still operational, but we advise you to migrate to the super-agent request library which is much more intuitive and elegant to use.
If you are about to write new code to perform any API request, please refer to the Using Superagent section.
The library exposes request-promise
to allow you to call external APIs seamlessly:
const response = await request({
uri: 'https://api.github.com/user/repos',
qs: {
access_token: 'xxxxx xxxxx' // -> uri + '?access_token=xxxxx%20xxxxx'
},
headers: {
'User-Agent': 'Request-Promise'
},
json: true // Automatically parses the JSON string in the response
})
console.log(response)
To perform API requests, the processor connector exposes the superagent library through the superagent
keyword. It is an instance of the original superagent library with additional plugins added behind the scenes to make it run smoothly in your processor code. This comes with some syntax restrictions that our instance of superagent won’t work with, more on that right below.
The exposed superagent instances cannot be called as function, so following code won’t work:
const res = await superagent('GET', 'https://www.foobar.com/search');
Instead always call a method on superagent object choosing which HTTP method you want to use. See examples Below.
Here are a few code snippets to use the super-agent request library in your processor code:
const response = await superagent
.get("https://example.com/foo")
.set("accept", "json") // Set a header variable by using the set() function.
.set(`Authorization: Bearer ${api_key}`)
.send({ // Set a body by using the send() function
body_variable: "something" // and by giving it an object.
})
.query({ // Set a query by using the query() function
orderBy: "asc" // and by giving it an object.
})
You can also perform asynchronous requests by using promises as such:
superagent
.get("https://example.com/foo")
.set("accept", "json")
.set(`Authorization: Bearer ${api_key}`)
.send({
body_variable: "something"
})
.query({
orderBy: "asc"
})
.then(res => {
console.log(res.body);
})
Handling errors is also possible, either by using promises or by wrapping the code in a try catch
statement:
superagent
.get("https://example.com/foo")
.set("accept", "json")
.set(`Authorization: Bearer ${api_key}`)
.then(res => {
console.log(res.body);
})
.catch(err => {
console.log(`Error: ${err}`);
})
try {
const response = await superagent
.get("https://example.com/foo")
.set("accept", "json")
.set(`Authorization: Bearer ${api_key}`);
} catch (err) {
console.log(`Error: ${err}`);
}
You can find full documentation of the superagent library here. Keep in mind that calling superagent as function does not work.
You might have noticed a warning message coming on your processor saying that your code is using a deprecated request library. In order to fix that, you need to replace request
with the superagent library.
There are mostly two things to adjust. First you need to replace your request options object with set of chained methods on superagent instance. Second you will need to look for the response.body
object instead of looking directly at the data
object.
To illustrate that, let’s have a look at a code block using the deprecated request library, and another code block with the result of migrating it.
// Old request library
const reqOpts = {
method: "GET",
uri: "http://www.omdbapi.com/?t=James+Bond"
};
return new Promise((resolve, reject) => {
request(reqOpts, (err, res, data) => {
if (err) {
console.info("Error:", err);
return reject(err);
}
// data contains the response body
if(_.isString(data)) {
data = JSON.parse(data);
}
resolve(data);
});
});
// With super-agent library
return superagent
.get("http://www.omdbapi.com/?t=James+Bond")
.then(res => {
// res.body is parsed response body
return res.body;
})
.catch(err => {
console.info("Error:", err);
})
ls
for lead score, just name it lead_score
._at
or _date
as suffix to your trait name to let hull recognize the values as valid dates. You can pass either "1234"
as the value for trait customerId
, the trait will be always a treated as string, even if you intended it to be a number.track
calls and to plan accordingly when setting a trait to the current timestamp.When operating you might want to log certain information so that it is available for debugging or auditing purposes while other data might be only of interest during development. The processor allows you to do both:
console.log
is used for development purposes only and will display the result in the console of the user interface but doesn’t write into the operational logs.console.info
is used to display the result in the console of the user interface and does also write an operational log.You can access the operational logs via the tab “Logs” in the user interface. The following list explains the various log messages available:
Message | Description |
---|---|
compute.console.info | The manually logged information via console.info . |
compute.user.debug | Logged when the computation of a user is started. |
| incoming.account.success
| Logged after attributes of an account have been successfully computed. |
Learn how Hull unifies and syncs customer data by watching our product tour