Read Actions
A read action reads data from your customer's SaaS on a scheduled basis and send them to Destinations that you define.
read:
standardObjects:
...
Read standard objects
To read a standard object, you need to specify:
- objectName: to indicate which standard object you'd like to read. This should match the name of the object in the official documentation for the SaaS API.
- destination: the name of the destination that you've defined
- schedule: how frequently the read should happen. This value must be a schedule in cron syntax
- a list of fields
standardObjects:
- objectName: lineItem
destination: lineItemWebhook
schedule: "0 */12 * * *" # every 12 hours
...
On the roadmap
The ability for your users to define their own sync schedules.
Known fields
Fields can be either be required or optional. If a field is required, then all users who install this integration will need to give your app read access to that field. If a field is optional, then users can choose whether they'd like your app to read that field. For standard fields, you will specify:
- fieldName: the name of the field from the official SaaS API documentation, converted to lower case. For example, if you'd like to read the first name of a contact, write
firstname
.
standardObjects:
- objectName: contact
destination: contactWebhook
schedule: "0 */12 * * *" # every 12 hours
requiredFields:
- fieldName: firstname
- fieldName: lastname
- fieldName: email
optionalFields:
- fieldName: company
Allow users to pick from all fields
If you want to give your user the option to pick from any of the fields in their Object, use optionalFieldsAuto: all
. The UI component will populate a list of all the fields pulled from their object and allow them to pick which ones your app will be able to read.
standardObjects:
- objectName: contact
destination: contactWebhook
schedule: "0 */12 * * *" # every 12 hours
requiredFields:
- fieldName: firstname
- fieldName: lastname
- fieldName: email
# All other fields are optional
optionalFieldsAuto: all
Field mappings
You might want to ask your users during the set up of the integration to map a field (standard or custom) to a concept in your product, because your various customers might be using different fields for the same purpose. Field mappings can either be inside requiredFields
or optionalFields
.
For these fields, you'll specify:
- mapToName: when we deliver the data from this field to you, this is the name that we'll use to identify the field.
- mapToDisplayName: the phrasing to display to the user in the set up UI component when asking them to select a custom field (e.g. For the config below, the helper text will say, "Which of your custom fields map to Contact Notes?")
- default (optional): the default field, you should only use standard fields as defaults.
- prompt (optional): additional context that you want to show your user in the set up UI Component about this field. This should be a full sentence.
standardObjects:
- objectName: contact
destination: contactWebhook
optionalFields:
# field that your app created
- fieldName: myAppPriorityScore
# field that your user created
- mapToName: notes
mapToDisplayName: Contact Notes
prompt: These are notes that you would like to surface in our app.
...
Example read action
integrations:
- name: readSalesforce
api: salesforce
read:
standardObjects:
- objectName: account
destination: accountWebhook
schedule: "0 */12 * * *" # every 12 hours
requiredFields:
- fieldName: name
- fieldName: industry
optionalFields:
- fieldName: annualrevenue
- fieldName: website
- objectName: contact
destination: contactWebhook
schedule: "0 */12 * * *" # every 12 hours
requiredFields:
- fieldName: firstname
- fieldName: lastname
- fieldName: email
- mapToName: pronoun
mapToDisplayName: Pronoun
prompt: We will use this word when addressing this person in emails we send out.
optionalFieldsAuto: all
Updated 3 months ago