This article describes how Okta Workflows supports using files and attachments in a flow.
To access a file in workflows, the file must be stored in the Workflows platform file system. Workflow action and function cards that create or download a file will store the file in the workflows' file system. Examples include:
- Tables Export to CSV card
- File Download card
- Flows Export Flow and Export Folder cards
- Connector action cards that download or return a File
It is not possible to upload files from a local file system to the workflows file system.
When a flow execution stores a file in the workflows file system, it will only be accessible to the workflow execution that stored it, meaning a different execution of the same flow will not be able to access the file. Once a file is saved to the file system, it can be uploaded to a web service or sent as an attachment using several different connector action cards and function cards as described below.
See the Flow Files section of the Workflows system limits documentation for guidance regarding file size limits, etc.
- Okta Workflows
- Multiple Connector Action cards and Function cards
- Okta Workflow Files
Uploading/Downloading Files using Built-in Connectors
There are several built-in workflows connectors that support uploading and downloading files to/from dedicated file storage services, including, but not limited to:
- OneDrive connector
- Google Drive connector
- Box connector
- Dropbox for Business connector
- SFTP connector
- AWS S3 connector
Sending Attachments using Built-in Connectors
There are several built-in workflows connectors that support sending files as an attachment with a notification, including, but not limited to:
Uploading/Downloading Files using File Function Cards
For scenarios where there is not a built-in connector that supports uploading or downloading files, it may be possible to use the File Upload, Multipart Upload and Download function cards, depending on the third-party service endpoint requirements.
The File Upload and Download cards provide basic functionality for uploading and downloading files to and from a web service. See the documentation for details regarding the inputs for these cards.
There are a few points to be aware of when using the Upload card:
- The File Content input requires a file stored in the workflow file system. This must be mapped from another card that precedes the Upload card in the flow, which has an output of type File
- The Headers input allows for specifying additional headers; however, adding a Content-Type header will not override the default of binary/octet-stream set by the card
- The file parameter name used for the upload is "file" and cannot be changed. If the service requires a different file parameter name, use the Multipart Upload card
- The existing filename will be used for the upload and cannot be changed. If a different filename is required, use the Multipart Upload card
The Multipart Upload card provides more flexibility for customizing upload requests to adhere to specific requirements of the service being used:
- The File Name input allows for specifying the file name, including extension, of the file to be uploaded
- The Headers input allows for specifying additional headers; however, adding a Content-Type header will not override the default content types set by the card:
- Request Content-Type: multipart/form-data
- File subpart Content-Type: binary/octet-stream
- Data subpart Content-Type: text/plain
- When Use Custom File Parameter is enabled in the card Options, File Parameter is exposed as an input, allowing for a name other than "file" to be used as the file parameter name if required
- The Data section allows for specifying additional inputs that will be sent with the request as key/value pairs. Some services may have required inputs, such as a file ID that can be specified here. Each attribute is sent as a separate sub-part in the request body, and the Content-Type for each sub-part is set by the card and cannot be overridden.
If authorization is required when using any of the File cards, it must be manually added to the Headers input. In other words, using an existing API connection to authorize the request is not supported. This means that sensitive data, such as tokens, credentials information, etc., used in the headers will be exposed in the workflow in plain text. To make this more secure, Connector Builder can retrieve the authorization header value, and the flow execution history can be disabled so the header value is not exposed in the history.
Multipart Upload Example
The following is an example flow that uses the Multipart Upload card to upload a file to an endpoint that allows inspection of the request:
The following shows the request that is sent to the endpoint:
There are a few points to take note of:
- The file being uploaded was downloaded from OneDrive, which stores it in the workflows file system. The File Content output on the OneDrive Download File card is of type File, and it is mapped to the File Content input on the Multipart Upload card, which also has a data type of File.
- The File Name input is exposed on the card, allowing for the filename to be specified; in this case, it is set to SamplePDF.pdf.
- An Authorization header was included in the Headers object for illustration purposes. In this case, the endpoint being called does not require authorization.
- In the card Options, the Use Custom File Parameter is set to Yes, which exposes the File Parameter input and allows for a name other than file to be used as the file name parameter.
- The fileId input was manually added under the Data section of the card. This key/value pair is uploaded as a separate subpart.
Custom API Action Cards & API Connector Cards
The API Connector cards and Custom API Action connector cards cannot be used to upload binary files to a web service, as they do not support the File datatype. In addition, there are no built-in function cards in workflows that allow for encoding binary data as a string so it can be included in the JSON payload of an API request.
