Nutshell v2

Provides integration with Nutshell CRM to query, create, update, delete, and restore companies, contacts, and leads in your Workflows. The Node uses Nutshell's REST API with API-key authentication and is available on Cloud Runtime Clusters.

Revision History

0.0.0.3 - Initial version.

Connection

Use this Connection to store the Nutshell user's email address and API key used to authenticate requests.

Setup Notes

1. Create an API key in Nutshell under Setup → API keys. See Nutshell's API authentication guide.
2. Create a Nutshell Connection in Flowgear and enter the user's email address in UserName and the API key in ApiKey.
3. Test the Connection. The test reads the list of users without changing any records.
4. Select a Method and its operation template, then map the fields needed by your Workflow.

Requests use the fixed https://app.nutshell.com/rest/ endpoint.

Methods

Select an operation template for the Method you want to use. The template supplies OperationId, a GUID identifying that operation, and describes its input and response fields. An OperationId from a different Method is rejected.

Nutshell's API calls companies accounts. The company templates therefore use names such as Create an account and Get a list of accounts.

Query

Reads records using the selected list or single-record template. Company, contact, and lead list queries retrieve subsequent pages automatically as you consume Response.

Use Options.Id with a single-record template to retrieve a record by its API ID. A missing record or another provider error stops the query; it is not returned as an empty successful result.

Create

Creates one company, contact, or lead for each non-null input item. Supply the entity's fields directly through Items; the Node builds the API request envelope.

To create a company, provide at least one of Name, Phones, Emails, Addresses, or Urls.

Update

Applies one complete JSON Patch document per input item to the company, contact, or lead identified by Options.Id.

Invoke the Node separately for each target when updating different records. Supplying an ID in Items does not change the target in Options.Id. A remove patch does not send a value; move and copy use From instead of ValueJson.

Delete

Deletes the company, contact, or lead identified by Options.Id. This Method executes once per invocation and has no Items input.

Restore

Restores the deleted company, contact, or lead identified by Options.Id. This Method executes once per invocation and has no Items input.

Usage Notes

• Use the record's full API ID, such as 1-contacts or 1-leads, in Options.Id and relationship fields. A lead's display number is different from its API ID.
• Map declared template fields using PascalCase, including nested fields such as Filter.Number and Links.Contacts. The Node translates these names to Nutshell's JSON names. JSON Patch paths and JSON inside ValueJson keep the provider's spelling and casing.
• Map declared string and integer collections as CSV strings. For example, Links.Contacts can contain 1-contacts,2-contacts. The Node converts these fields to API arrays on input and back to CSV on output. Keep object collections, such as emails, phones, addresses, and product maps, structured.
• Quote CSV fields containing commas, line breaks, or quotes, and double quotes inside a quoted field. Whitespace is preserved. An empty CSV string represents no elements; "" represents one empty string. Invalid integer values stop processing. Arrays inside ValueJson use ordinary JSON arrays without CSV conversion.
• Use Options.Filter for the filters exposed by the selected template. Additional provider filter keys are accepted at runtime and retain their original names. Template samples illustrate valid inputs and are not automatically applied as filter values.
• Let the Node handle pagination. Do not add page[page] or page[limit] to Options.
• Define Workflow-specific child fields when mapping tenant custom fields or other fields absent from the fixed templates. The Node preserves these values at runtime but does not discover your account's custom field definitions.
• Consume the response stream to process all query pages or all create and update items. The first page or write executes when the Node starts; later pages and items are processed as the stream advances.
• Check Flowgear.IsSuccess for every mutation result. Handled provider business errors produce a failed row and allow later input items to continue. Flowgear.StatusMessage describes the result, and Errors contains provider error details when available. Authentication or authorization failures, invalid inputs, transport failures, and other unhandled request failures stop the Node.
• Reads retry rate limiting within a bounded retry budget and the request timeout. Writes are not automatically retried. Check Nutshell before repeating a write after a connection failure or timeout because the request may already have succeeded.
• Templates are available without contacting Nutshell. Their availability does not establish that your credentials can execute an operation.

Examples

Filter leads by number

Select the Query template Get a list of leads and supply the following Options object to retrieve leads whose number is greater than 1020:

{
  "Filter": {
    "Number": ">1020"
  }
}

Use each returned record's Id for later single-record operations, rather than its Number.

Create a company

Select the Create template Create an account and supply the following object as an item in Items:

{
  "Name": "Example Company"
}

Check the result's Flowgear.IsSuccess before using the returned Id in later operations. Supply the company fields directly; do not wrap them in an accounts array.

Update a contact's description

1. Select the Update template Update a contact.
2. Set Options.Id to the contact's API ID, such as 1-contacts.
3. Supply this object as an item in Items:

{
  "Patches": [
    {
      "Op": "replace",
      "Path": "/contacts/0/description",
      "ValueJson": "\"Integration update\""
    }
  ]
}

4. Check the result's Flowgear.IsSuccess and Flowgear.StatusMessage.

The escaped quotes in ValueJson make the replacement value a JSON string. Use "42", "true", or "null" as the ValueJson text for a number, boolean, or explicit null respectively. For an object or array, supply serialized JSON using Nutshell's field names.

See also

• Nutshell REST API quickstart.