Vendasta v2

Provides integration with Vendasta to work with CRM records, schemas and pipelines, social and blog posts, reviews, listings and Net Promoter Scores, meetings, and business users through one Connection. Use it to query, create, update and delete CRM contacts, companies, opportunities and custom objects, schedule social posts, respond to reviews, and book, reschedule or cancel meetings in your Workflows. The Node is available on Cloud Runtime clusters.

Revision History

0.0.0.2 - Initial release.

Connection

This Connection identifies the Vendasta environment and stores the credentials used by every Vendasta Method. Choose an AuthenticationType, only the properties for the selected type are shown.

Setup Notes

1. In Vendasta, create a service account for the environment you will use and download its key JSON. Alternatively, obtain an access token for that environment.
2. Create a Vendasta Connection in Flowgear and select the matching Environment.
3. For ServiceAccount, paste the downloaded key JSON into ServiceAccountCredentials without changing it, and enter the scopes your Workflows need in Scopes. Request narrower scopes than the default when you only use some of the APIs. For example, CRM operations use crm, Meetings operations use meeting and business-app, Reputation and Social Posts operations use business-app, and Business Center user operations use user. Vendasta's API reference lists the scopes for each operation.
4. For AccessToken, enter the token in AccessToken.
5. Test the Connection. The test requests the identity of the authenticated user and needs the profile or email scope. A successful test confirms the credentials and environment, but does not confirm access to a specific product or business.

With ServiceAccount, the Node obtains a new short-lived access token for each run, renews it before it expires, and does not save it on the Connection. If Vendasta rejects a token during a run, the Node renews it once. With AccessToken, the token cannot be renewed automatically, so an expired or rejected token stops the Node.

Methods

Each Method exposes templates for a fixed set of Vendasta operations across six APIs: CRM, Social Posts, Reputation, Meetings, Business Center and Composer. Template names start with the API family followed by the Vendasta operation name, for example CRM and Create Contact. Select a template to populate the OperationId, a GUID identifying that operation, and the operation's input and Response fields. An OperationId from a different Method is rejected.

Query uses Options for the request. Create, Update, Delete and Action use Items, with one Vendasta request per row. All template inputs use Vendasta's field names.

Query

Reads Vendasta records using the selected template. The Node retrieves subsequent pages automatically as you consume Response.

Create

Creates, imports, schedules or books one Vendasta resource for each row in Items.

Update

Updates one Vendasta resource, or reschedules one meeting, for each row in Items.

Delete

Deletes one Vendasta resource, or cancels one meeting, for each row in Items. Templates never supply a default identifier.

Action

Performs the selected Vendasta action, such as restoring a deleted CRM record or validating a custom object, for each row in Items.

Usage Notes

• Most CRM operations require a namespace, which identifies the business whose CRM you are working with, for example an account group ID such as AG-.... The credentials must have access to that business.
• CRM records store their values in crmObject.fields, one entry per field. Name each field by its fieldId or by its externalId; built-in fields use external IDs such as standard__first_name. Use the CRM List Field Schema template for the object type to discover field IDs and external IDs.
• Use fieldMask.paths to limit the fields returned or updated, for example fields.standard__first_name when getting contacts, or ownerId when updating a contact. Template samples show the format for each operation. Custom object samples contain a placeholder field ID that you must replace with a field of your custom object type.
• Filter and sort samples, such as filtersV2 and sortBy, illustrate the syntax and are not applied unless you enter a value.
• A contact's companies and opportunities are held as associations. Use the CRM List Associations template with a filtersV2 filter on the association_type field, for example Contact-Company.
• Let the Node handle paging. Do not supply cursor, pageSize, pagingOptions or paging. Fields that are not in the selected template, read-only fields, and values that do not match the field's type or allowed values are rejected before the request is sent.
• Map string and integer lists, such as crmObjectIds and fieldMask.paths, as CSV strings. Quote values containing commas, quotes or line breaks, and double any quotes inside a quoted value. Spaces are preserved. An empty string represents an empty list, while "" represents one empty string. Lists of objects remain structured. List values returned by Vendasta use the same CSV format.
• Many numeric fields, such as integerValue, are strings in Vendasta's API. Supply them as strings.
• When Vendasta wraps the request in a single object, for example pipeline when creating a pipeline or blogPost when updating a blog post, the template shows that object's fields directly and the Node adds the wrapper.
• Schedule Social Posts and Composer Update Posts send one post per row in Items. A scheduled post is reported as successful only when Vendasta accepts it for scheduling. Composer returns a row for each updated post and for each post that Vendasta rejects.
• Book meeting returns one row with the booked meeting's details, including meetingId. Attendee email addresses are returned as a CSV string.
• CRM get operations for associations fail when Vendasta cannot retrieve every requested association. Check the record IDs and access.
• Deleted CRM companies, contacts, opportunities and custom objects are retained by Vendasta and can be restored using the matching Action template.
• Check Flowgear.IsSuccess for every Create, Update, Delete and Action result. When Vendasta rejects an individual row because it is invalid, not found or already exists, the Node returns a failed row containing Vendasta's code, message and details and continues with later rows. details is returned as JSON text. Authentication failures, access-denied responses, server errors, timeouts and connection failures stop the Node.
• Consume the response stream to process every query page or input row. The first page or write runs when the Node starts, and later pages and rows are processed as the stream advances.
• When Vendasta limits the request rate, the Node waits for the period Vendasta specifies and retries up to two times. If Vendasta requires a wait of more than one hour, the Node stops. Writes that time out or fail because of a server or connection error are not retried. Check Vendasta before repeating a write because the request may already have succeeded.

Examples

Create a contact

Select the Create template for the CRM Create Contact operation and supply the following object as a row in Items:

{
  "namespace": "AG-EXAMPLE",
  "crmObject": {
    "fields": [
      {
        "externalId": "standard__first_name",
        "stringValue": "Jane"
      }
    ]
  }
}

When Flowgear.IsSuccess is true, the result's crmObjectId contains the ID of the new contact.

Get contacts by ID

Select the Query template for the CRM Get Multi Contact operation and supply the following Options object:

{
  "namespace": "AG-EXAMPLE",
  "crmObjectIds": "ContactID-00000000-0000-0000-0000-000000000001,ContactID-00000000-0000-0000-0000-000000000002",
  "fieldMask": {
    "paths": "fields.standard__first_name"
  }
}

Each row in Response is one contact containing the requested fields.

Known Issues

• Composer Update Posts can fail with the message that the endpoint does not have scopes defined. Contact Vendasta support before retrying the operation.
• CRM field options queries return up to 100 options, so the result might not include every available option.

See also

• Handle Partial Batch Failures.
• Vendasta developer documentation.