Skip to content

Automations

MASV agent allows you to automate certain tasks to save time and support more robust workflows. Creating an automation returns an automation_id, which can be used to query, update and delete the automation.

To list all managed automations, call:

curl -X GET http://localhost:8080/api/v1/automations

Portal Download Automations

Portal download automations are used to automatically download packages uploaded to portals.

There are currently 2 kinds of portal download automations,

  • Portal Download: polls a single portal for available packages
  • All Portals Download: polls all portals associated with a given team_id

Portal Download

This automation automatically picks up new packages uploaded to the specified portal and queues them up as a new download. The downloads can be managed in the same way as other user-initiated downloads are handled, and they go through the same state transitions.

To create a portal download automation, simply call:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/portal_download -d '{
  "name": "AUTOMATION_NAME",
  "portal_subdomain": "PORTAL_SUBDOMAIN",
  "dst_folder": "DESTINATION_FOLDER",
  "create_package_folder": true,
  "effective_time": "2010-12-12T23:59:59-05:00",
  "enabled": true,
  "download_priority": 3,
}'

Where:

  • create_package_folder indicates whether package contents should be placed straight into the dst_folder, or if they should be placed within dedicated package directories
  • download_priority the transfer priority to assign to all created downloads
  • dst_folder is the destination folder where all packages will be downloaded to.
  • effective_time is a string date/time in RFC333 format which indicates the start date/time after which uploaded packages will be downloaded. Setting it to a date/time in the past will cause the agent to download all packages uploaded after that point in the past until now, and subsequently, any future packages.
  • enabled indicates whether the automation will be enabled immediately or not
  • name is a custom automation name.
  • portal_subdomain is the subdomain of the portal from which uploaded packages will be automatically downloaded. The portal has to be owned by the team of the signed-in user.

To update a portal download automation, call:

curl -X PUT -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/portal_download/{automation_id} -d '{
  "name": "NEW_AUTOMATION_NAME",
  "enabled": false
}`

The following Portal Download automation fields can be updated:

  • create_package_folder
  • dst_folder
  • download_priority
  • effective_time
  • enabled
  • name
  • portal_subdomain

To delete a Portal Download automation, call:

curl -X DELETE http://localhost:8080/api/v1/automations/portal_download/{automation_id}

All Portals Download

This automation polls all portals associated with the specified team_id for available packages. These packages are queued up as new downloads. The downloads can be managed in the same way as other user-initiated downloads are handled, and they go through the same state transitions.

To create an all portals download automation, simply call:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/all_portals_download -d '{
  "name": "AUTOMATION_NAME",
  "team_id": "TEAM_ID",
  "dst_folder": "DESTINATION_FOLDER",
  "create_portal_subfolder": true,
  "effective_time": "2010-12-12T23:59:59-05:00",
  "enabled": true,
  "download_priority": 3,
}'

Where:

  • create_portal_subfolder indicates whether package folders will be placed directly into the dst_folder, or if they should be placed within directories based off of the originating portal name.
  • download_priority the transfer priority to assign to all created downloads.
  • dst_folder is the destination folder where all packages will be downloaded to.
  • effective_time is a string date/time in RFC333 format which indicates the start date/time after which uploaded packages will be downloaded. Setting it to a date/time in the past will cause the agent to download all packages uploaded after that point in the past until now, and subsequently, any future packages.
  • enabled indicates whether the automation will be enabled immediately or not.
  • name is a custom automation name.
  • team_id is the Team ID to poll for portal packages. The signed-in user must belong to this team.

To update an all portals download automation, call:

curl -X PUT -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/all_portals_download/{automation_id} -d '{
  "name": "NEW_AUTOMATION_NAME",
  "enabled": false
}`

The following All Portals Download automation fields can be updated:

  • create_portal_subfolder
  • dst_folder
  • download_priority
  • effective_time
  • enabled
  • name
  • team_id

To delete an All Portals Download automation, call:

curl -X DELETE http://localhost:8080/api/v1/automations/all_portals_download/{automation_id}

Watch Folder automations

A watch folder is a type of upload automation that uploads subfolders within the watched directory. After a timeout has passed without detecting any file modifications, the subfolder is sent as a package, delivered according to the type of upload automation.

Attention

Top level files in the watch folder will be ignored. Ensure that the files you want delivered are properly placed in their appropriate package subfolder.

There are two types of watch folder automations:

  • Send (Team) Upload: sends all subfolders within the watch folder to the configured recipient(s).
  • Portal Upload: sends all subfolders to the configured portal.

Note

Transfer Agent cannot upload to a Portal that requires metadata.

Send (Team) Upload

To create a Send automation, call:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/team_upload -d '{
  "name":"send automation 1",
  "path":"/path/to/watch/folder",
  "timeout":5,
  "enabled":true,
  "team_id":"TEAM_ID",
  "recipient_emails":["[email protected]"]
}'

Where

  • name is the name of the automation, used for identification.
  • enabled is the enabled/disabled state of the automation.
  • path is the directory to be watched. After the timeout window of inactivity, subfolders within this path will be sent as packages.
  • recipient_emails is an array of emails to send the packages to.
  • team_id is the TeamID from which to send the package(s).
  • timeout is the filesystem inactivity timeout in minutes. If no changes are observed after this duration, the packages are sent.

Optional parameters can be provided when creating a Send automation, where

  • blacklist is an array of glob patterns to ignore when scanning files in the watch folder.
  • delete_after: Integer value, specifying the number of days to keep the package(s) in storage.
  • delete_files_after_upload is a boolean value, indicating whether to clean up the source package subfolder once the package upload has completed.
  • download_limit is an override for the team's maximum downloads available for the sent package(s)
  • download_password: Optional password that all downloaders must enter before being granted access to the package(s).
  • message is an optional message that will be sent to recipients along with the package(s).
  • package_name_suffix is an optional suffix that is added as a suffix after the subfolder name, combining to form the name of the package(s).
  • send_loose_files is a boolean value that, if true, directs the automation to send individual top level loose files in the watch folder as individual packages.
  • tag is a tag object of the form {"name":"my_tag_name","id":"my_tag_id"} that will be passed to all created uploads.
  • unlimited storage is a boolean value that forwards the flag to all created uploads
  • upload_priority is an integer value that is assigned as the transfer priority for all created uploads

To update a Send automation, call:

curl -X PUT -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/team_upload/{automation_id} -d '{
  "name":"send automation 2"
}'

The following Send automation fields can be updated:

  • blacklist
  • delete_after
  • delete_files_after_upload
  • download_limit
  • download_password
  • enabled
  • message
  • name
  • path
  • package_name_suffix
  • recipient_emails
  • send_loose_files
  • team_id
  • timeout
  • tag
  • unlimited_storage
  • upload_priority

To delete a Send automation, call:

curl -X DELETE http://localhost:8080/api/v1/automations/team_upload/{automation_id}

Portal Upload

To create a Portal Upload automation, call:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/portal_upload -d '{
  "name":"portal upload automation 1",
  "path":"/path/to/watch/folder",
  "timeout":5,
  "enabled":true,
  "portal_subdomain":"PORTAL_SUBDOMAIN",
  "sender_email":"[email protected]"
}'

Where:

  • enabled is the enabled/disabled state of the automation.
  • name is the name of the automation, used for identification.
  • path is the directory to be watched. After the timeout window of inactivity, subfolders within this path will be sent as packages.
  • portal_subdomain is the portal subdomain of the portal the package(s) will be sent to.
  • sender_email is the sender email that the recipient will see when they receive the package(s).
  • timeout is the filesystem inactivity timeout in minutes. If no changes are observed after this duration, the packages are sent.

Optional parameters can be provided when creating a Portal Upload automation, where:

  • blacklist is an array of glob patterns to ignore when scanning files in the watch folder.
  • delete_files_after_upload is a boolean value indicating whether or not to clean up the source subfolder once the package upload has completed.
  • message is an optional message that will be sent along with the package(s).
  • package_name_suffix is an optional suffix that is added as a suffix after the subfolder name, combining to form the name of the package(s).
  • portal_password is the password required to upload to the configured portal. If the portal requires no password, leave this blank.
  • send_loose_files is a boolean value that, if true, directs the automation to send individual top level loose files in the watch folder as individual packages.
  • upload_priority is an integer value that is assigned as the transfer priority for all created uploads.

To update a Portal Upload automation, call:

curl -X PUT -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/portal_upload/{automation_id} -d '{
  "name":"portal upload automation 2"
}'

The following Portal Upload automation fields can be updated:

  • blacklist
  • delete_files_after_upload
  • enabled
  • message
  • name
  • package_name_suffix
  • path
  • portal_password
  • portal_subdomain
  • send_loose_files
  • sender_email
  • timeout
  • upload_priority

To delete a Portal Upload automation, call:

curl -X DELETE http://localhost:8080/api/v1/automations/portal_upload/{automation_id}

Stream Upload Automations

A stream upload automation is used to upload growing files to the desired recipient. Each stream automation has a path to a stream folder, where the automation will scan for new files to stream. After a timeout has passed without detecting any file size changes, the growing file upload is finalized.

Attention

Stream Upload automations will only work with supported file formats and codecs that append to the end of a given file. File chunk modifications that are made to already streamed chunks will not be synced with the resulting package.

Attention

Any directories within the stream folder will be ignored. Ensure that the growing files you want delivered are properly placed directly in the stream folder.

There are two types of watch folder automations:

  • Send (Team): sends the growing files within the stream folder to the configured recipient(s).
  • Portal Upload: sends the growing files to the configured portal.

Note

Transfer Agent cannot upload a stream to a Portal that requires metadata.

Send (Team) Stream

To create a Send Stream automation, call:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/team_stream -d '{
  "name":"team stream automation 1",
  "team_id":"TEAM_ID",
  "path":"/path/to/stream/folder",
  "timeout":60,
  "recipient_emails":["[email protected]"],
  "enabled":true,
  "delete_after":1,
  "whitelist":["*.mxf"]
}'

Where:

  • name is the name of the automation, used for identification.
  • enabled is the enabled/disabled state of the automation.
  • path is the directory to be watched. Uploads will be created immediately after a new top-level files are detected within the stream directory.
  • recipient_emails is an array of emails to send the packages to.
  • team_id is the TeamID from which to send the package(s).
  • timeout is the filesystem inactivity timeout in seconds. If no changes are observed after this duration, any ongoing stream is finalized.

Optional parameters can be provided when creating a Send automation, where

  • whitelist is an array of glob patterns to stream. If empty, all files will be streamed.
  • delete_after: Integer value, specifying the number of days to keep the package(s) in storage.
  • download_limit is an override for the team's maximum downloads available for the sent package(s)
  • download_password: Optional password that all downloaders must enter before being granted access to the package(s).
  • message is an optional message that will be sent to recipients along with the package(s).
  • tag is a tag object of the form {"name":"my_tag_name","id":"my_tag_id"} that will be passed to all created uploads.
  • unlimited storage is a boolean value that forwards the flag to all created uploads
  • upload_priority is an integer value that is assigned as the transfer priority for all created uploads

To update a Send automation, call:

curl -X PUT -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/team_stream/{automation_id} -d '{
  "name":"team stream automation 2"
}'

The following Send automation fields can be updated:

  • whitelist
  • delete_after
  • download_limit
  • download_password
  • enabled
  • message
  • name
  • path
  • recipient_emails
  • team_id
  • timeout
  • tag
  • unlimited_storage
  • upload_priority

To delete a Send automation, call:

curl -X DELETE http://localhost:8080/api/v1/automations/team_stream/{automation_id}

Portal Stream

To create a Portal Stream automation, call:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/portal_stream -d '{
  "name":"portal stream automation 1",
  "path":"/path/to/stream/folder",
  "timeout":60,
  "enabled":true,
  "portal_subdomain":"PORTAL_SUBDOMAIN",
  "sender_email":"[email protected]"
}'

Where:

  • enabled is the enabled/disabled state of the automation.
  • name is the name of the automation, used for identification.
  • path is the directory to be watched. Uploads will be created immediately after a new top-level files are detected within the stream directory.
  • portal_subdomain is the portal subdomain of the portal the package(s) will be sent to.
  • sender_email is the sender email that the recipient will see when they receive the package(s).
  • timeout is the filesystem inactivity timeout in seconds. If no changes are observed after this duration, the ongoing stream is finalized.

Optional parameters can be provided when creating a Portal Upload automation, where:

  • whitelist is an array of glob patterns to stream. If empty, all files will be streamed.
  • message is an optional message that will be sent along with the package(s).
  • portal_password is the password required to upload to the configured portal. If the portal requires no password, leave this blank.
  • upload_priority is an integer value that is assigned as the transfer priority for all created uploads.

To update a Portal Upload automation, call:

curl -X PUT -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/portal_stream/{automation_id} -d '{
  "name":"portal stream automation 2"
}'

The following Portal Upload automation fields can be updated:

  • whitelist
  • enabled
  • message
  • name
  • path
  • portal_password
  • portal_subdomain
  • sender_email
  • timeout
  • upload_priority

To delete a Portal Upload automation, call:

curl -X DELETE http://localhost:8080/api/v1/automations/portal_stream/{automation_id}

Export & Import

Automation can be exported to a base64 string, which can then be imported by the transfer-agent or desktop-app. This can be used to share automations between transfer-agents or desktop-apps, or duplicate automations if need be.

To export an automation, use one of the following endpoints depending on the automation type: 

Portal Download:
  curl http://localhost:8080/api/v1/automations/portal_download/{automation_id}/export

Portal Upload:
  curl http://localhost:8080/api/v1/automations/portal_upload/{automation_id}/export

Team Upload:
  curl http://localhost:8080/api/v1/automations/team_upload/{automation_id}/export

Team Stream:
  curl http://localhost:8080/api/v1/automations/team_stream/{automation_id}/export

Portal Stream:
  curl http://localhost:8080/api/v1/automations/portal_stream/{automation_id}/export

The response for this request will be a json payload, with a single data field. 

{"data":"base64_data_field"}

This data field can then be used with the import automation endpoint 

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/automations/import -d '{"data":"base64_data_field"}'