Event data is sent to your checkpoint from a server when the checkpoint is called. Many parts of a workflow may require certain information to be defined, or work best in its presence. Also, some integrations may fail if the event data is invalid or missing.
Because of this, it is very important to know what event data should be sent to Dodgeball, as well as how to handle certain transformations within Dodgeball if event data is not sent, but could be inferred/calculated.
How should I set up and organize my event data?
You can organize your event data in any way you desire; however, we provide a standard vocabulary discussed below.
Dodgeball Vocabulary
Dodgeball provides a vocabulary system based on a key-value Entity Model. You can read about this in our documentation: https://docs.dodgeballhq.com/developers/vocabulary/available-vocabulary/
INTERNAL NOTE: We should probably update the Dodgeball Vocabulary Documentation, it has not been updated in a while, and is definitely not complete. We might want to do some internal and strategy and cleanup before updating though.
Many integrations are set up to use Dodgeball Vocabulary by default.
When might event data be required?
A simple example: If you run a checkpoint that immediately checks the customer.primaryEmail - the workflow must have that data available. Unless Dodgeball is able to infer the primary email from history (this may be possible) - the decision will have no value from which to make calculations.
This will result in the decision going down a default path, but cause integrations which rely on the email address to return an error.
How do I know what event data is required?
Because of this, Dodgeball takes in the known checkpoint structure, and computes what data must be sent, and which data could be used by service blocks throughout the checkpoint. You can see this by clicking on the workflow trigger block:
Notice how the “Primary Email” is marked by a warning, and a required “*“?
This is because we have a decision using the primary email (thus it is required), and this is a new requirement since the last time the checkpoint was published.
In fact, if we click publish when one of these warnings is active, we require users to click through a confirmation. This is intended to prevent introducing any kind of failing integration service blocks which depend on that data being available.
Adding event data by asking an engineer
In some cases, the easiest solution is to have an engineer add the missing data; however, this is not always necessary.
When must an engineer add event data?
When data that cannot be calculated or inferred is required by some new logic of a workflow, an engineer must add that data.
For example, if you have never sent any address data to Dodgeball, and want to start validating that a payment’s shipping address is the same as a customers home address, you will likely need to start sending that data.
When data can be calculated via data transformation
If all the information is available (for example we have a customer phone number as a number (i.e. 1234567890) but we need it as a text string with "+1" in front, we can usually compute a field value with data transformation tools.
See Checkpoints and Integrations below for information about how to do custom data transformation in Dodgeball.
Once data is available, you can use it by referencing it as discussed in the data flow and mapping section.
When data can be pulled from another integration or an internal service
Say we want to pull in a customer’s country based on their email enrichment results from People Data Labs. We can do this as follows:
Run PDL: Enrich Person
See what fields are available (this can be done by looking at what data is available in a decision or by looking at the example input data on a DTL step). You can also run the checkpoint with PDL and look at the developer logs to see what data is available. Integrations worked on in the last year (Engineers would say that they use something called pathDisplayCommon and BaseIntegrationServiceV2) will have more useful outputs in the Developer Logs.
Map that field out wherever you want it to go:
When you do this, you will be able to see the data in your custom message
And in Developer Logs
In the same way, a user can configure a webhook to call their own internal service (or an arbitrary service provider with an API), to handle such calculations on their own.
When data may be inferable based on history
When data is sent to Dodgeball for a given customerExternalId that data will be available for the system to populate data from context based on a given set of rules.
These rules may change over time, and are NOT something that is currently set in stone. They may eventually be configurable or customizable by customers.
For now, an example of this logic would be the following sequence of events:
Client X Runs checkpoint SIGN_UP for customer “a@a.com”.
Event Data looks like this: {customer: {primaryEmail: "a@a.com"}}
Since this was the first checkpoint for the customer, no contextual data is available
Client X Runs checkpoint PAYMENT for customer “a@a.com”.
Event Data looks like this: {transaction: {amount: 500 }}
Since the signup event has already happened and we received an email, we can infer the email in the PAYMENT checkpoint to be "a@a.com" and use it to run things like enrichment by email or other fraud checks.
Note that if a customer tries to submit a payment prior to a signup, this will leave the checkpoint without a value for the customer email. For this reason, it is a best practice to send all data that is easily available to the checkpoint in order to make it possible to make changes in the future without engineering help. Often it helps to use a standardized vocabulary to help keep naming similar across the Dodgeball data environment. We recommend using Checkpoints and Integrations as a starting point.