Data flows through a Dodgeball checkpoint in very consistent and customizable ways.
It is important to know how to reference data that has come into the checkpoint whether via the event data, or other sources, and how to change the default behaviors. This will enable you to help customers, and diagnose any issues they are seeing, or confusion they might have about how to implement their anti-fraud strategy.
An example data situation
For the examples below, lets imagine we have input data like this:
{ "phoneAsNumber": 1234567890 }
and we have some service that takes the phone number as an input and returns transformedPhoneNumber = "+11234567890"
How do I know what data is available at a given point of a workflow?
There are a few ways to check the expected available data at a given point of a workflow:
Use a Decision to view available fields
Note: Many fields from Checkpoints and Integrations are preloaded here, but they must be sent via event data in order to actually have a value defined at this point of the workflow.
Use DTL to view expected data structure
The DTL Service Block shows you example available data based on simulations of data that could be available at a given step. Just insert a DTL Service block and click “Manage Transformations” to see what has been computed.
This calculation is a good starting place, but may not represent actual data available during a workflow execution. For example, currently it will not include available data where the only reference in a workflow is via interpolated event data. It also does not currently have a way to know about event data that is never used in a checkpoint
Use Custom Messages to Troubleshoot
You can interpolate values into custom messages on Allow/Deny blocks to view values and troubleshoot.
Try something like this!
If you run this through Demo Examples, you will see the Custom Message Logged. This is a very simple way to start testing.
Use Developer Logs to view Data Logging
Often the developer logs are good places to see where data is defined, what is is called, and how it is moving around.
Referencing data via interpolation
See the Glossary for a definition of interpretation.
Where can you interpolate values?
Allow/Deny Custom Messages
Custom API Request Service Block Params
Send Email Body
In places where you can interpolate, reference available values value as follows {{transformedPhoneNumber}}
For event data, you will need to indicate that the data is from the event by starting the value like this {{event.phoneAsNumber}}
For Dodgeball Vocabulary (i.e. customer.primaryEmail) you can reference event.customer.primaryEmail but it will only be populated for the event if they sent it in the event. The vocabulary field can also pull from history.
See this example, for how to reference both phone numbers in the “Allow” Custom Message
Referencing Data via Input Data Mapping
Most integration service blocks have a section where you can “Manage Input Data Sources” - this is usually found under the “ADVANCED OPTIONS” dropdown.
If you click on this button, you can manage the data sent to an integration.
By default, Twilio Phone Lookup will look like this:
We can actually change the data sent to this integration by changing the “Source” for twilio.phoneLookup.phoneNumber - note how the workflow knows that transformedPhoneNumber is an available field, and we can just select it from available sources.
NOTE: make sure that if you have “Only show compatible Sources” checked, that the data type is correct, or it will not show up in the available sources list.
Updating or Creating data via Output Data Mapping
Some Service Blocks allow you to export data into the workflow context.
Currently these are DTL and Custom API (webhook) Service Blocks.
How to start managing output mappings
For Webhooks - Click “Manage Output Data Mapping” in settings
For DTL - Click “Manage Transformations” in settings
Managing the outputs looks similar regardless of where it is located.
There are three primary components to map for each output
-
The source path (WHERE TO LOOK) — in the data created by this service block (webhook/DTL) - where do we go to access the information?
For example if a webhook returns the following (example simplified from an actual ChatGPT API response), we probably want to access the first choice’s message content
{
"id": "chatcmpl-Acz6B3bdlZSOWJO01xyZjJM5bQqpc",
"choices": [
{
"message": {
"role": "assistant",
"content": "in the silence of a digital sea \textbackslash{}nwhere whispers of code gently stir, \textbackslash{}nwebhooks dance in unseen harmony, \textbackslash{}nan ethereal pulse, a soft, sure blur. \textbackslash{}n\textbackslash{}nthey awaken in the heartbeat's call, \textbackslash{}na signal flares from server lands, \textbackslash{}nacross the wire, the data sprawls, \textbackslash{}nlike fingers grasping distant hands. \textbackslash{}n\textbackslash{}nin their touch, a tale unfurls, \textbackslash{}na story told in logic's tongue, \textbackslash{}nbridging worlds with electric swirls, \textbackslash{}nuntil the final note is sung. \textbackslash{}n\textbackslash{}noh, quiet spirits in the mesh, \textbackslash{}nconnect us through your gentle nudge, \textbackslash{}nwhere every line and every dash \textbackslash{}nunveils the universe's subtle judge.",
},
"finish_reason": "stop"
}
],
}You can reference in-app descriptions of how to define source paths for a variety of cases
In our use case, we can get the message content with `choices[0].message.content`
We can also get all outputs as an object with the special `*` source path. This is an advanced feature, and not necessarily a best practice since the exported data type is not known or necessarily consistent, so probably best to not bring it up unless a customer needs the functionality.
Below, you can see two source paths defined, one exporting all webhook response data, the other exporting just the message content from the first choice.
-
The Destination Element Name (WHAT DO WE CALL IT)
This setting tells Dodgeball what to call the output response. Generally, we should use a new field name here. It is a best practice to use some kind of prefix to keep names easy to manage.
You can overwrite existing data fields with this value. Be careful with this! It can be very useful, but also could cause problems if done accidentally or incorrectly. Using a prefix like webhookOutputOpenAi will ensure this does not happen on accident.
-
The Destination Data Type (WHAT CAN WE DO WITH IT)
Setting the data type lets us know what kind of data to expect, and therefore lots of other useful things. For example, if it is a string, we can check if it contains text in a condition. If it is a number, we can compare it to other numbers in conditions.
Number 2 & 3 Configurations are pictured below
At the end of the day, you will have a mapping that looks something like this, which can be summarized as follows:
Take all the webhook response data and save it in a field called openAiOutputs - we can’t do much with this since we don’t know the type.
Take the first message content and save it in a field called openAiResponse - this is a string and can be interpolated in other places or referenced in a decision.
This second example is from a DTL step and can be summarized as follows:
Take the transformedLineItems value from DTL outputs and save it as microsoftDfp.getDecisionPurchase.transaction.lineItems which is a list.of unknown type.
Nathan Clement - record a video of doing this live and talking for reference
Referencing Data in Decisions
If you have transformed data and want to reference it in a decision, use the “Search Data Elements” input to search for available fields.
If you are sending data via the checkpoint event, you can add it here by clicking “Add new Data Element”
Data from Integrations, mapped out of webhooks, and from DTL outputs will show up automatically.
Defining and Referencing Secrets
Clients should never type any secrets like API keys into places like service parameters. Because of this, Dodgeball offers a secret management system that enables teams to safely define and access secrets where needed.
Using the Secrets Manager
You can access the Checkpoint Secrets Manager under the Developer Center if you have sufficient permission.
Referencing Secrets
In places where data can be referenced by interpolation, and access to secrets is enabled (like Webhook configuration), you can reference a secret value using the secrets. prefix. For example in the screenshot above, the OpenAI key can be referenced as secrets.openAIKey