SFTP Blueprint Triggering

The /blueprints/{blueprint-id} and /blueprints/{blueprint-id}/events folders allow you to create and manage business processes through blueprints using SFTP bulk operations.

📘

Info

The Customer must already exist, in order to create a Business Process.

Enable

To enable batch processing for a Blueprint you must add a Trigger where the protocol is system and the resource is jobs.line. This will cause the folder to be created in the FTP server, for files to be dropped.

Folder Structure

/blueprints/{blueprint-id}

Required Scopes

jobs:create blueprints:read business_processes:update

File Format

The CSV should use dot notation to match the blueprint's expected input structure. The exact fields depend on the blueprint configuration.

Required Fields

📘

ID Seed Benefits

When your integration is FTP based you are going to need to provide an idSeed as there is no reasonable way to get back an ID for a Business Process when it is created. So you will need to be sure your file provides a value and your Blueprint maps it appropriately.

ID seeds are used for the resulting Business Process ID generation. This is useful when you want to be able to send follow-up actions like reminders, or changing the status of the business process and still using SFTP batch to do so. Can also be used to protect against duplicates, if your file has not been sanitized.

Blueprint-Specific Fields

For this file format the column names are entirely determined by the configuration of the underlying Blueprint identified by the blueprint-id folder name. Generally, the payload that the Blueprint accepts can be flattened and put into a comma separated list and work.

More complex data types may need additional consideration within the Blueprint definition. However interpolation allows for pretty complex manipulation.

Example Blueprint Definition

name: "Payment Collection"
description: "Collect payments from customers"
attributes:
  amount:
    type: "number"
    required: true
    description: "Payment amount in dollars"
  currency:
    type: "string"
    required: true
    enum: ["USD", "CAD"]
    default: "USD"
  description:
    type: "string"
    required: false
    maxLength: 100
  dueDate:
    type: "string"
    format: "date"
    required: false
  metadata:
    type: "object"
    required: false
    # ... additional configuration

CSV Field Mapping

Blueprint attributes are mapped to CSV columns using dot notation:

Example CSV

Super simple file example where a Blueprint is sending out a payment request (payment-method and payment action combination).

customer,amount,description
cus-1,10000,Shoes

Processing

For each valid record:

1. Customer validation: Verify customer exists
2. Blueprint validation: Validate against blueprint configuration
3. Business process creation: Create business process via blueprint
4. ID seed assignment: Assign custom ID if provided
5. Status update: Mark record as processed

Error Codes

Common Problems

Below is a list of common issues we've seen and the corrective action to take to resolve it.

I don't see a folder for my blueprint?

A Trigger has not yet been created for that Blueprint which would enable batch. Protocol must be system and resource must be jobs.line. This causes system logic to create the corresponding folder for that blueprint.

You may also need to try logging out and back into your FTP client again, to get the folders to refresh.