Creating Workflows with SendSafely Actions API

Here we'll teach you how to create and monitor Actions workflows via the SendSafely REST API. This document  contains guidance on how to invoke our API endpoints to perform certain tasks. If you wish to configure your Actions workflow using the Actions Editor UI, please see this article instead.

Creating a Workflow

When you create a new workflow, you must specify the type of event that triggers it. Every workflow can only be triggered by a single EVENT_TYPE. We currently support two EVENT_TYPEs: 

1. Upload a file to a Workspace (UPLOAD_WORKSPACE_FILE)
2. Finalize a Transfer or Dropzone package (FINALIZE_PACKAGE)

In order to create a new enterprise workflow, submit a POST request to the Add Enterprise Workflow endpoint. An example JSON request body for this endpoint is shown below.

{"workflowEventType":"UPLOAD_WORKSPACE_FILE"}

In addition to EVENT_TYPE, every workflow has the following properties. Unless otherwise noted, each of these properties can be updated using the Update Workflow endpoint. 

• Status. Every workflow is created with the workflowStatus "INACTIVE." Workflows in this state won't trigger until they are updated to "ACTIVE" status. If you delete a workflow, the status is changed to "DELETED" and can't be reverted to "ACTIVE" or "INACTIVE." 

• Identity. The workflowIdentityUserId is the SendSafely UserID that the workflow will execute as. For enterprise workflows, the identity can be changed so that the workflow can execute as any active admin user within your SendSafely portal. By default, the admin who creates an enterprise workflow is assigned as the identity, but this can be changed after the workflow is created.  

• Priority. Workflows are executed sequentially, in order of designated workflowPriority. Within the list of enterprise workflows, each workflow is assigned a numerical priority, starting from 1.  If an event triggers multiple workflows, they are executed in order of relative priority.

• Name. Each workflow can be assigned a workflowName to describe its nature and purpose. Within the list of Enterprise Workflows, every workflow must have a unique name. 

• Notification Email. The workflowNotificationEmail property indicates the email address to be notified if the workflow triggers a notification. By default, the notification email is set to the user who creates the workflow, but this can be changed after the workflow is created.  

• isOrgScope Flag. A Boolean value that cannot be changed once the workflow has been created. For enterprise workflows, this will be TRUE.  

• Organization ID. The workflowOrgId is the unique Organization ID associated with your SendSafely portal. This value cannot be changed.  

In order to UPDATE a workflow, submit a PUT request to the Update Workflow endpoint. An example JSON request body for this endpoint is shown below.

{"workflowEventType":"UPLOAD_WORKSPACE_FILE",
 "workflowStatus":"ACTIVE",
 "workflowPriority":"1",
 "workflowName":"MyWorkflow",
 "workflowNotificationEmail":"[e-mail]"} 

Event Properties

When the event occurs, a list of event properties is generated that includes metadata about the event. These properties can be used to create event filters, which can be used to define conditions under which a workflow should run. The event properties for each EVENT_TYPE are outlined below:

UPLOAD_WORKSPACE_FILE

• authenticatedUser: The email address of the user who uploaded the file
• organizationId: The unique Organization ID associated with the SendSafely portal
• packageId: The unique Package ID of the Workspace 
• ipAddress: The IP address of the device that the file was uploaded from 
• dateTime: The date and time that the file was uploaded, in ISO UTC format 
• fileId: The unique SendSafely File ID assigned to the file  
• fileName: The name of the file 
• directoryId: The unique SendSafely Directory ID that the file was uploaded to 
• directoryPath: The path within the workspace of the directory that the file was uploaded to 
• packageOwner: The email address of the user who owns the Workspace  
• isGuest: A Boolean flag indicating whether the authenticated user is a guest (unregistered) or a Registered User 

FINALIZE_PACKAGE

• authenticatedUser: The email address of the user who finalized the package. For unauthenticated Dropzone uploads, this property will show “Unverified Sender” (the email address of the uploader will be shown in the uploader property). 
• organizationId: The unique Organization ID associated with the SendSafely portal
• packageId: The unique Package ID of the Package 
• packageType: The type of package that was finalized (either "TRANSFER" or "DROPZONE"). 
• uploader: The email address of the person who uploaded the file. For unauthenticated Dropzone uploads where an email address was provided, the word “Unverified” will be listed in parenthesis next to the email address. 
• recipientEmails: The array of recipients associated with the package 
• ipAddress: The IP address of the device that the package was finalized from 
• dateTime: The date and time that the package was finalized, in ISO UTC format 
• keylessPackageLink: The link used to access the package (without a keycode parameter) 
• packageOwner: The email address of the package owner
• isGuest: A Boolean flag indicating whether the authenticated user is a guest (unregistered) or a Registered User 

Event Filters 

Event Filters allow you to execute a workflow only when events match certain criteria. Event filters are based on a subset of the properties associated with the event that triggers the workflow. The following event filters are supported for each EVENT_TYPE:

UPLOAD_WORKSPACE_FILE

FILTER_TYPE	Description	Supported Operators	Format/Validation
PACKAGE_ID	The unique SendSafely Package ID associated with the Workspace.	EQUALS NOT_EQUALS	NNNN-NNNN
IS_USER_GUEST	Boolean value indicating whether the user is a registered SendSafely user or not.	EQUALS NOT_EQUALS	TRUE or FALSE
PACKAGE_OWNER	Package Owner	EQUALS NOT_EQUALS	xxx@xxx.x or UUID
AUTHENTICATED_USER	The email address of the authenticated user that is uploading the file.	EQUALS NOT_EQUALS	xxx@xxx.x

FINALIZE_PACKAGE

FILTER_TYPE	Description	Supported Operators	Format/Validation
IS_USER_GUEST	Boolean value indicating whether the user is a registered SendSafely user or not.	EQUALS NOT_EQUALS	TRUE or FALSE
PACKAGE_TYPE	The type of package (TRANSFER or DROPZONE)	EQUALS NOT_EQUALS	TRANSFER or DROPZONE
PACKAGE_OWNER	Package Owner	EQUALS NOT_EQUALS	xxx@xxx.x or UUID
AUTHENTICATED_USER	The email address of the authenticated user that finalized the package.	EQUALS NOT_EQUALS	xxx@xxx.x or “Unverified Sender”

In order to add an event filter to a workflow, issue a POST request to the Add Workflow Filter. An example JSON request body for this endpoint is shown below.

{"filterType":"PACKAGE_USER",
 "filterOperator":"EQUALS",
 "filterValue":"[e-mail]"}

Workflow Actions

Every workflow must have one or more actions, steps carried out by the workflow based on the event that triggered its execution. Actions are executed sequentially based on the actionOrder that the action is assigned, starting with 1.  

After an action executes, it returns a result of either TRUE, FALSE, or ERROR to indicate its outcome. If an action returns ERROR, all subsequent steps in the workflow are halted and a notification is generated that includes details of the step that returned the error.  

The available actions for each EVENT_TYPE are as follows: 

UPLOAD_WORKSPACE_FILE

Action Type	Description	Result when True	Result when False
BLOCK_FILE	Sets the fileState to BLOCKED on the file that triggered the event. Blocked files cannot be viewed or downloaded.	Block was applied	N/A
UNBLOCK_FILE	Sets the file state to NULL on the file that triggered the event.	Block was released	N/A
HOLD_FILE	Sets the fileState to HOLD on the file that triggered the event. Held files cannot be deleted but can be viewed and downloaded.	Hold was applied	N/A
RELEASE_FILE	Sets the file state to NULL on the file that triggered the event.	Hold was released	N/A
DELETE_FILE	Deletes the file that triggered the event.	File was deleted	N/A

FINALIZE_PACKAGE

Action Type	Description	Result when True	Result when False
BLOCK_PACKAGE	Sets the fileState to BLOCKED on all files in the package that triggered the event. Blocked files cannot be viewed or downloaded.	Block was applied	N/A
UNBLOCK_PACKAGE	Sets the file state to NULL on all files in the package that triggered the event.	Block was released	N/A
HOLD_PACKAGE	Sets the fileState to HOLD on all files in the package that triggered the event. Held files cannot be deleted but can be viewed and downloaded.	Hold was applied	N/A
RELEASE_PACKAGE	Sets the file state to NULL on all files in the package that triggered the event.	Hold was released	N/A
DELETE_PACKAGE	Deletes the package that triggered the event.	Package was deleted	N/A

External Webhook Actions

The INVOKE_WEBHOOK action is available for any event. INVOKE_WEBHOOK can be used to trigger an external webhook that can perform custom actions. Because INVOKE_WEBHOOK actions are external to SendSafely, they must return a response within 15 minutes. If a response is not received within 15 minutes, a TIMEOUT result is recorded and the workflow is halted. External webhook actions can also return true/false results based on the specific task they perform. The webhook itself must provide guidance (in its own documentation) for how to interpret true/false responses.  

Action Notifications

When adding an action to a workflow, you can assign a notification preference for the action. A notification email that includes details on the result of the action/step is sent to the workflowNotificationEmail. By default, notifications are generated when an action results in an ERROR or TIMEOUT. You can change this behavior by configuring one of the following notification preferences:

• DEFAULT: Notify when the action/step results in an ERROR or TIMEOUT
• ON_TRUE: Notify when the action/step results in TRUE, ERROR, or TIMEOUT
• ON_FALSE: Notify when the action/step results in FALSE, ERROR, or TIMEOUT
• ON_SKIP: Notify when the action/step is SKIPPED due to a filter, or results in ERROR or TIMEOUT
• ALWAYS: Always notify when the action/step runs

In order to add an action to a workflow, issue a POST request to the Add Action endpoint. An example JSON request body for this endpoint is shown below.

{"actionType":"BLOCK_PACKAGE",
 "actionNotify": "DEFAULT"}

When adding the “INVOKE_WEBHOOK” actionType, you must specify an additional “actionInput” value with the URL for the webhook endpoint. An example JSON request body for this option is shown below.

{"actionType":"INVOKE_WEBHOOK",
 "actionInput":"https://k927jhd0s.lambda-url.us-east-1.on.aws/", 
 "actionNotify":"DEFAULT"}

Action Filters

Action Filters allow you to execute a specific step/action only if certain criteria are met. Action filters can be based on the results of a previous step in the workflow or on the event properties that triggered the workflow (the same properties and operators available when setting an Event Filter). Unless ALL criteria specified in an action’s Action Filters are met, the action will be SKIPPED (not executed) and the workflow will proceed to the next step.  

Refer to the Event Filters above for the list of filters supported for each EVENT_TYPE. The additional filter types available when setting an Action Filter (available for all event types) are as follows:

 

 

FILTER_TYPE	Description	Supported Operators	Format/Validation
ACTION_RESULT_TRUE	References a specific step/action that must return TRUE	EQUALS	Action ID of a previous step in the same workflow
ACTION_RESULT_FALSE	References a specific step/action that must return FALSE	EQUALS	Action ID of a previous step in the same workflow
ACTION_RESULT_SKIPPED	References a specific step/action that was SKIPPED due to a filter	EQUALS	Action ID of a previous step in the same workflow

In order to add an action filter to a workflow, issue a POST request to the Add Action Filter endpoint. An example JSON request body for this endpoint is shown below.

{"filterType":"ACTION_RESULT_TRUE",
 "filterValue":"e8d462f3-0235-4908-a003-08debe478204",
 "filterOperator":"EQUALS"}

Monitoring Workflow Executions

Once a workflow is active, you can monitor invocations of the workflow by viewing the Workflow Execution Logs, which are generated every time a workflow runs. Execution logs include details of the Workflow that ran along with information about the triggering event and each action/step within the workflow. The following details are included in every execution log entry:

• workflowId - The Workflow ID that was executed 
• workflowName - The name assigned to the workflow when it ran 
• runnerId - Unique ID of the back-end process responsible for executing the workflow. For any given workflow, the runnerId will be unique for every execution.  
• createTimestamp - Timestamp from when the workflow was queued for execution, in ISO UTC format
• startTimestamp - Timestamp from when the workflow execution began, in ISO UTC format. The time in between the create and start timestamp can be larger for workflows that run after other workflows which might have been triggered by the same event (such as a higher-priority workflow)  
• endTimestamp -  Timestamp from when the workflow execution ended, in ISO UTC format
• state - The current state of the workflow execution. Can be one of the following:
  • PENDING: Queued for execution, but not yet started (typically waiting on a higher-priority workflow to complete)
  • RUNNING: Execution in progress 
  • COMPLETE: Execution completed successfully (no error or timeout responses) 
  • ERROR: Execution was aborted due to an error in one of the steps/actions
  • TIMEOUT: Execution was aborted because an external webhook did not resume within 15 minutes
• eventTarget - The ID of the object that triggered the workflow, which varies based on the EVENT_TYPE that triggered the workflow: 
  • UPLOAD_WORKSPACE_FILE - The File ID of the uploaded file 
  • FINALIZE_PACKAGE: The Package ID that was finalized 
• workflowIdentity - The SendSafely UserId of the identity configured for the workflow
• orgScope - Boolean value indicating that the Workflow is an Enterprise Workflow (true)
• organizationId - The unique Organization ID associated with the SendSafely portal 
• eventPayload - JSON payload that includes the Event Properties associated with the triggering event
• executionResults - JSON array with detailed status/output from each step/action of the workflow. Each entry includes:
  • step: The step number, starting from 1
  • actionId: The unique Action ID of the workflow step 
  • actionType: The Action Type (BLOCK_FILE, UNBLOCK_FILE, etc) 
  • start: Execution start time for this step, in ISO UTC format)
  • end: Execution end time for this step, in ISO UTC format
  • result: The result returned by the action: TRUE, FALSE, ERROR, TIMEOUT or SKIPPED
  • message: The result message returned by the action (informational only)
  • notify: The notification preference for the step/action (DEFAULT, ON_TRUE, ON_FALSE, ON_SKIPPED or ALWAYS)

In order to view the execution logs related to your workflows, issue a GET request to the Execution Logs endpoint.