SuiteDash v2

Provides integration with SuiteDash through the SuiteDash Secure API. Use it to list and look up contacts, companies and projects, create contacts and companies, update contacts, companies and projects, and subscribe email addresses to marketing audiences. The Node is available on Cloud Runtime Clusters.

Revision History

0.0.0.4 - Initial release.

Connection

Use this Connection to store the SuiteDash Secure API key pair used by every Method and when loading template details that include custom fields.

Setup Notes

1. In SuiteDash, open Integrations → Secure API and copy the Public ID and Secret Key.
2. Create a SuiteDash Connection in Flowgear and enter the values in PublicId and SecretKey.
3. Test the Connection. The test makes one read-only request for your account's contact field definitions.
4. Select a Method and its operation template, then map the fields needed by your Workflow.

Requests use the fixed https://app.suitedash.com/secure-api/ endpoint. The key pair does not expire through a token exchange, so replace it on the Connection if it is regenerated in SuiteDash.

SuiteDash accounts have a monthly API request quota. You can view your usage under Integrations → Secure API. Every request counts toward the quota, including the Connection test, each template detail that loads custom fields, each page of a list, and the custom field lookup made by a write that sets custom fields.

Methods

Select an operation template for the Method you want to use. The template supplies OperationId and describes the operation's Options, Items and Response fields. An OperationId from a different Method is rejected.

Query

Reads contacts, companies or projects using the selected template. List templates retrieve subsequent pages automatically as you consume Response.

Available templates:

• List contacts (list-contacts) - Lists contacts, optionally filtered by creation time.
• Get a contact (get-contact) - Returns one contact by UID or primary email.
• List companies (list-companies) - Lists active companies, optionally filtered by creation time. Idle companies are not returned.
• Get a company (get-company) - Returns one company by UID or exact name.
• List projects (list-projects) - Lists projects, optionally filtered by creation time.
• Get a project (get-project) - Returns one project selected by UID, exact name, name fragment or most recent creation.

Create

Creates one contact or company for each input item. Supply the record's fields directly in each Items row.

Available templates:

• Create a contact (create-contact) - Creates a contact. first_name, last_name and role are required, and email is required unless role is Lead. Primary emails must be unique.
• Create a company (create-company) - Creates a company. name and role are required. Company names must be unique, and a referenced category must already exist.

Update

Updates the record identified in Options once for each input item. Only the fields supplied in an item are changed.

Available templates:

• Update a contact (update-contact) - Updates one contact identified by UID or primary email.
• Update a company (update-company) - Updates one company identified by UID or exact name.
• Update a project (update-project) - Updates one project selected by UID, exact name, name fragment or most recent creation.

Subscribe

Subscribes email addresses to SuiteDash marketing audiences using the Subscribe to marketing audiences template (subscribe-marketing-audiences). Each Items row is one subscriber. The Node sends subscribers to SuiteDash in batches of up to 50 and returns the results in input order.

Usage Notes

• SuiteDash does not provide delete operations or project creation through this Node.
• Options applies to the whole invocation, so every Items row in an Update targets the same record. To update several records, run the Node once per record, for example inside a For Each.
• Options accepts only the values shown by the selected template. Unknown values are rejected. Paging is managed by the Node, so do not add page to Options.
• createdMin and createdMax are exclusive bounds and must be timestamps with an explicit time zone offset, for example 2024-07-14T09:00:00+00:00. createdMin must be earlier than createdMax. orderBy accepts the values listed in the template, such as created, created.desc, name and name.desc. The Node validates these values before sending the request, because SuiteDash ignores malformed filters instead of rejecting them.
• For Get a project and Update a project, set type to uid for a project UID, name for an exact name, contains_the_following for a name fragment (the first match is used), or most_recent for the most recently created project. With most_recent, set identifier to true. The Get a project template defaults to the most recent project.
• Template samples illustrate valid inputs and are not applied unless you enter a value.
• Map string and integer collections, such as tags, quizzes, circle names and marketing audiences, as CSV strings. Quote values containing commas, quotes or line breaks, and double any quotes inside a quoted value. Whitespace is preserved, and an empty string represents an empty collection. Object collections, such as notes, remain structured.
• Updating tags replaces the record's existing tags. The record returned by an update can still show the tags from before the update; a later read returns the new tags.
• Custom fields are keyed by their SuiteDash field UID. When you load the details of a template that includes custom fields, the Node reads your account's field definitions through the Connection and lists each available field with its display name and any allowed values. Supply single-value custom fields, including numeric fields, as strings. Supply multi-select fields as CSV strings. An unknown field UID fails the item.
• The Node validates each item against the template before sending it, including required fields, allowed values, formats and value types. Values are not converted between types, so for example a number supplied for a text field is rejected. An invalid first item stops the Node; an invalid later item produces a failed row and processing continues.
• Check Flowgear.IsSuccess for every Create, Update and Subscribe result. Validation, not-found and duplicate errors returned by SuiteDash produce a failed row and allow later items to continue. A rejected subscribe batch produces one failed row per subscriber in that batch. Authentication and permission failures, throttled writes, server errors and unexpected responses stop the Node.
• Read requests that SuiteDash throttles are retried up to two times, respecting SuiteDash's Retry-After value up to 30 seconds. Writes are never retried automatically. Check SuiteDash before repeating a write because the request may already have succeeded.
• When the account's monthly request quota is exhausted, SuiteDash returns a message such as The maximum allowed number of 80 monthly requests has been exceeded. The Node, Connection test or template detail fails immediately with that message until the quota resets.
• Consume the response stream to process all list pages or all input items. The first page, lookup, write or subscribe batch executes when the Node starts; later pages and items are processed as the stream advances. Lists are read ten records per page, so large lists use several requests.
• Empty objects that SuiteDash returns as empty arrays are returned as {}.

Examples

List recently created contacts

Select the Query template List contacts and supply the following Options object:

{
  "createdMin": "2024-07-14T09:00:00+00:00",
  "orderBy": "created.desc"
}

Each row in Response is one contact created after the supplied time, newest first.

Update a contact by email

Select the Update template Update a contact, set Options.identifier to the contact's primary email, for example jane.doe@example.com, and supply the following object as an item in Items:

{
  "title": "Operations Manager",
  "tags": "Customer,Priority"
}

Check the result's Flowgear.IsSuccess before continuing.

See also

• Handle Partial Batch Failures.
• For Each.