CTA enables Reverse ETL (rETL) syncs between PAD and ActionBuilder (AB) instances. This allows you to extract data from PAD and load it into ActionBuilder. Use cases include enriching your AB instance with data from other integrations or performing regular mass updates of your AB data.
What kind of data can I load into ActionBuilder?
Currently, we support importing and updating both AB record types - people and custom entities - with optional connections and tags on records. Multiple tags and connections can be uploaded per record if mapped properly, and each run is limited to records in one ActionBuilder campaign. Tag section, field, and names must already exist in ActionBuilder before being applied via the workflow.
Note that the ActionBuilder API does not allow changes to certain core fields, such as name. It also retains records for other fields, such as phone number, email and address even if new values are uploaded, so old and new values will be present in the entity’s record.
How do I set up this sync?
Contact your CTA representative or email help@techallies.org to set up an ActionBuilder rETL sync. In order to set up the sync, CTA will need an API key for your ActionBuilder instance.
How do I find and run the sync?
Navigate to https://console.cloud.google.com/workflows. If prompted, sign in to Google Cloud using your cta.tools account.
Look for action-builder-parent-import and action-builder-child-import under the Workflow section of the console. These should appear under the Workflow header.
If these are listed, you have access to ActionBuilder rETL. If these are not listed but you are interested in testing the workflow, contact help@techallies.org.
Once you confirm access, prepare the data you want to import into ActionBuilder.
Navigate back to Workflows. Under Workflows, select action-builder-parent-import.
Enter your parameters in the input field box on the left of the Execution setup. Some parameters are required for every run, and some are optional based on what you’re uploading. These parameters need to be structured in a specific way. See the list of parameters below and an example below of how to structure; we recommend copy/pasting the example and replacing your parameters as needed. If you modify spacing, quotation marks, etc., the workflow will not run; it’s important to follow this format exactly.
Input parameters:
campaign_id: required, ActionBuilder Campaign ID
dataset_id: required, source dataset ID in BigQuery
org_id: required, ActionBuilder instance name
add_connections: optional array for adding a connection to records. Requires the person_id you’re connecting to.
add_connections → add tags: optional array for adding tags on a connection to records. Requires a field, name and section value for the tag, which you can find in ActionBuilder’s UI.
add_tags: optional array for adding tags on records. Requires a field, name and section value for the tag, which you can find in ActionBuilder’s UI.
Person fields: series of fields, all optional, that you want to upload to a record. Each field needs to be mapped to its corresponding column in your source table in BQ. Note that custom_id_1 specifically maps to the custom_id_1 slot in ActionBuilder, and name can map to a name or given_name column depending on the entity type.
job_name: required, this is used for workflow logging; you can decide what goes here but we recommend making it something you can recognize in the logs if needed for troubleshooting.
Example input:
{
"campaign_id": "<your AB campaign ID here>",
"dataset_id": "<your BQ dataset ID here>",
"org_id": "<your AB org ID here>",
"table_id": "<your BQ table ID here>",
"fields": {
"add_connections": [
{
"add_tags": [
{
"field": "<tag field here>",
"name": "<tag name here>",
"section": "<tag section here>"
}
],
"person_id": "<person ID you're connecting to here>"
}
],
"add_tags": [
{
"field": "<tag field here>",
"name": "<tag name here>",
"section": "<tag section here>"
}
],
"person": {
"entity_type": <corresponding entity type here>,
"identifiers": {
"action_builder": <corresponding BQ column name here>,
"custom_id_1": <corresponding BQ column name here>
},
"given_name": "<corresponding BQ column name here>",
"name": "<corresponding BQ column name here>",
"family_name": "<corresponding BQ column name here>",
"additional_name": "<corresponding BQ column name here>",
"pronouns": "<corresponding BQ column name here>",
"address_line_1": "<corresponding BQ column name here>",
"address_line_2": "<corresponding BQ column name here>",
"locality": "<corresponding BQ column name here>",
"region": "<corresponding BQ column name here>",
"postal_code": "<corresponding BQ column name here>",
"country": "<corresponding BQ column name here>",
"home_phone": "<corresponding BQ column name here>",
"mobile_phone": "<corresponding BQ column name here>",
"work_phone": "<corresponding BQ column name here>",
"home_email": "<corresponding BQ column name here>",
"work_email": "<corresponding BQ column name here>"
}
},
"metadata": {
"jobName": "<your job name here>"
}
}
Once you have your parameters inputted, select ‘Execute’. From there, once the workflow is complete, you’ll see notification of success or failure in the Execution section you will be redirected to. Then you’re done!
How can I see the results of a sync run?
You can access logs from each sync run by going to the Workflow page, clicking on the action-builder-child-import and clicking on the run you are interested in viewing under ‘Executions’. From there, you’ll see in the ‘output’ section what was sent to the API and returned from each run. Note that there is a new child import execution for each record added. Keep in mind that while the parent workflow might report a success, individual child workflows may have still failed, and we recommend looking at the child workflow logs after runs.
FAQ:
Is there a limit on how many records I can pass through at a time?
No. ActionBuilder limits API calls to 4 per second, but our workflow typically passes calls through at a speed that does not trigger that limit. If you receive failures due to API call limitation, we recommend retrying the failed child import tasks. Bulk import in the ActionBuilder UI is also a good option for one-time bulk uploads.
One of my rows of data failed to import; does that mean everything else didn’t import as well?
No! Each row is treated as its own POST request, so failures only impact the individual row that failed. The rest of the job will run unless a certain number of failures are hit.
Some of my values - for example, part of a record’s address - are null. Is that okay for the workflow?
Yes, that’s fine for the workflow.
I keep getting a 422 error when I try to update records; how can I fix that?
This is a known limitation with ActionBuilder’s API; it does not allow a person to be uploaded twice with the same phone number. We recommend stripping out the phone number if you’re receiving this error and re-running.
I ran the workflow and didn’t get any parent or child import errors, but some or all of the data isn’t showing up in ActionBuilder
There are a number of reasons this could occur. Check that the BigQuery column names you’ve mapped in your input are correct, and that all the ActionBuilder inputs (campaign ID, person ID for connections, info for tags, etc.) are valid. Column names and ActionBuilder inputs need to be exactly the same as they appear in BQ or ActionBuilder, including case, underscores, etc. For tags and connections, also make sure that a) the tags previously existed in ActionBuilder and b) the record you are trying to connect to exists in the same campaign. If you’re still running into issues, contact help@techallies.org.
I want to use a custom ID slot to upload my records.
Our workflow currently supports uploads to the custom_id_1 slot in ActionBuilder. Other custom ID slots are not supported. We recommend using an ActionBuilderID when uploading data to ensure the best possible match to existing records in your instance. If both ActionBuilderID and custom ID are present in your upload, ActionBuilder’s API will default to using ActionBuilderID.
I’m seeing duplicate records get created when using the workflow.
We have observed some issues with duplicate records when records are upserted only with custom ID and not ActionBuilderID via the workflow and the record was originally created in the UI. This appears to be an API limitation. We recommend using ActionBuilderID to ensure the best possible match.
Due to known API limitations, records will only be matched in the campaign you’re uploading to (e.g., if the record exists in another campaign, the workflow will not pull it over into your campaign. You’ll instead end up with two records, one in each campaign.).
I want to import, create or update a type of record I don’t see listed here.
Reach out to help@techallies.org; we can discuss options depending on what you’re looking for.
Have questions? Reach out to us at help@techallies.org.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article