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 automations, use the following request:

CLIREST API

masv automation ls

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, use the following request:

CLIREST API

masv automation add download \
--name "AUTOMATION_NAME" \
--subdomain "PORTAL_SUBDOMAIN"
--destination "DESTINATION_FOLDER" \
--create-package-folder=true \
--effective-time "2025-01-20 00:00:00" \
--enable=true \
--priority 1

Where:

create-package-folder indicates whether package contents should be placed straight into the destination, or if they should be placed within dedicated package directories. Defaults to true.
priority the transfer priority to assign to all created downloads
destination 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. Defaults to true.
name is a custom automation name.
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.

curl -H "Content-Type: application/json" -X POST \
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": 1,
}'

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, use the following request:

CLIREST API

masv automation update download {automation_id} \
--name "NEW_AUTOMATION_NAME" --disable

The following Portal Download automation fields can be updated:

create-package-folder
destination
priority
effective-time
enabled
name
subdomain

curl -H "Content-Type: application/json" -X PUT \
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

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, use the following request:

CLIREST API

masv automation add download \
--all \
--name "AUTOMATION_NAME" \
--team-id "TEAM_ID"
--create-package-folder=true \
--create-portal-subfolder=true \
--destination "DESTINATION" \
--effective-time "2025-01-20 00:00:00" \
--enable=true \
--priority 8

Where:

all indicates that this should be an all portals download automation
create-portal-subfolder indicates whether package folders will be placed directly into the destination, or if they should be placed within directories based off of the originating portal name.
priority the transfer priority to assign to all created downloads.
destination 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.

curl -H "Content-Type: application/json" -X POST \
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, use the following request:

CLIREST API

masv automation update download {automation_id} \
--name "NEW_AUTOMATION_NAME" --disable

The following All Portals Download automation fields can be updated:

create-portal-subfolder
destination
priority
effective-time
enabled
name
team-id

curl -H "Content-Type: application/json" -X PUT \
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

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, use the following request:

CLIREST API

masv automation add upload email \
--name "AUTOMATION_NAME" \
--enable=true \
--path "PATH_TO_WATCH" \
--recipients '[email protected],[email protected]' \
--team-id "TEAM_ID" \
--timeout 5 \
--blacklist ".exe,.jpg" \
--delete-after 5 \
--delete-files-after-upload=true \
--download-limit 3 \
--download-password "PASSWORD" \
--message "PACKAGE_MESSAGE" \
--package_name_suffix "SUFFIX" \
--priority 1 \
--upload-loose-files=true

Where the following fields are required:

name is the name of the automation, used for identification.
enable 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.
recipients 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.

And the following fields are optional:

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).
priority is an integer value that is assigned as the transfer priority for all created uploads
tag-id is a ID of an existing tag object that will be passed to all created uploads.
tag-name is a Name of an existing tag object that will be passed to all created uploads.
unlimited-storage is a boolean value that forwards the flag to all created uploads
upload-loose-files Determines if the loose, top level files in the watch-folder will be uploaded as their own packages.

curl -H "Content-Type: application/json" -X POST \
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 the following fields are required:

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.

And the following fields are optional:

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, use the following request:

CLIREST API

masv automation update upload email {automation_id} \
--name "NEW_AUTOMATION_NAME" --disable

The following Send automation fields can be updated:

blacklist
delete-after
delete-files-after-upload
download-limit
download-password
enable
message
name
path
package-name-suffix
priority
recipients
team-id
timeout
tag-id
tag-name
unlimited-storage
upload-loose-files

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

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

Portal Upload

To create a Portal Upload automation, use the following request:

CLIREST API

masv automation add upload portal \
--enable=true \
--name "AUTOMATION_NAME" \
--path "PATH_TO_WATCH" \
--subdomain "PORTAL_SUBDOMAIN" \
--sender "[email protected]" \
--timeout 5 \
--blacklist ".exe,.jpg" \
--delete-files-after-upload=true \
--message "PACKAGE MESSAGE" \
--package-name-suffix "SUFFIX" \
--password "PASSWORD" \
--priority 3 \
--upload-loose-files=true

Where the following fields are required:

enable 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.
subdomain is the portal subdomain of the portal the package(s) will be sent to.
sender 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.

And the following fields are optional:

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).
password is the password required to upload to the configured portal. If the portal requires no password, leave this blank.
priority is an integer value that is assigned as the transfer priority for all created uploads.
upload-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.

curl -H "Content-Type: application/json" -X POST \
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 the following fields are required:

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.

And the following fields are optional:

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, use the following request:

CLIREST API

masv automation update upload portal {automation_id} \
--name "NEW_AUTOMATION_NAME" --disable

The following portal upload automation fields can be updated:

blacklist
delete-files-after-upload
enable
message
name
package-name-suffix
path
password
priority
subdomain
sender
timeout
upload_loose_files

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

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

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, use the following request:

CLIREST API

masv automation add upload email \
--name "AUTOMATION_NAME" \
--enable=true \
--path "PATH_TO_WATCH" \
--recipients '[email protected],[email protected]' \
--team-id "TEAM_ID" \
--timeout 5 \
--whitelist=".txt,.doc" \
--delete-after 3 \
--download-limit 77 \
--download-password "PASSWORD" \
--message "PACKAGE MESSAGE" \
--priority 3 \
--growing-files

Where the following fields are required:

name is the name of the automation, used for identification.
enable 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.
recipients 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.

And the following fields are optional:

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).
priority is an integer value that is assigned as the transfer priority for all created uploads
tag-id is a ID of an existing tag object that will be passed to all created uploads.
tag-name is a Name of an existing tag object that will be passed to all created uploads.
unlimited-storage is a boolean value that forwards the flag to all created uploads

curl -H "Content-Type: application/json" -X POST \
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 the following fields are required:

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.

And the following fields are optional:

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 (Team) stream automation, use the following request:

CLIREST API

masv automation update upload team {automation_id} \
--name "NEW_AUTOMATION_NAME" --disable

The following Send (Team) stream automation fields can be updated:

whitelist
delete-after
download-limit
download-password
enable
message
name
path
priority
recipients
team-id
timeout
tag-id
tag-name
unlimited-storage

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

The following Send (Team) stream 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

Portal Stream

To create a Portal Stream automation, use the following request:

CLIREST API

masv-srv automation add upload portal \
--whitelist ".txt,.jpg" \
--enable=true \
--message "MESSAGE" \
--name "AUTOMATION NAME" \
--password "PASSWORD" \
--path "PATH_TO_WATCH" \
--priority 1 \
--sender "[email protected]" \
--subdomain "SUBDOMAIN" \
--timeout 5 \
--growing-files

Where the following fields are required:

enable 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.
subdomain is the portal subdomain of the portal the package(s) will be sent to.
sender 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.

And the following fields are optional:

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).
password is the password required to upload to the configured portal. If the portal requires no password, leave this blank.
priority is an integer value that is assigned as the transfer priority for all created uploads.

curl -H "Content-Type: application/json" -X POST \
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 the following fields are required:

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.

And the following fields are optional:

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 Stream automation, use the following request:

CLIREST API

masv automation update upload portal {automation_id} \
--name "NEW_AUTOMATION_NAME" --disable

The following Send (Team) stream automation fields can be updated:

whitelist
enable
message
name
path
password
priority
subdomain
sender
timeout

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

The following Send (Team) stream automation fields can be updated:

whitelist
enabled
message
name
path
portal_password
portal_subdomain
sender_email
timeout
upload_priority

Removing Automations

CLIREST API

To delete any type of automation with the CLI, use the following request:

masv automation rm {automation-id}

Using the REST API, different endpoints need to be used to correctly delete automations.

curl -X DELETE http://localhost:8080/api/v1/automations/portal_download/{automation_id}
curl -X DELETE http://localhost:8080/api/v1/automations/all_portals_download/{automation_id}
curl -X DELETE http://localhost:8080/api/v1/automations/team_upload/{automation_id}
curl -X DELETE http://localhost:8080/api/v1/automations/portal_upload/{automation_id}
curl -X DELETE http://localhost:8080/api/v1/automations/team_stream/{automation_id}
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.

CLIREST API

When using the CLI, any automation can be exported with the same request

masv automation export {automation_id}

When using the REST API, use one of the following requests depending on the automation type:

curl http://localhost:8080/api/v1/automations/portal_download/{automation_id}/export
curl http://localhost:8080/api/v1/automations/portal_upload/{automation_id}/export
curl http://localhost:8080/api/v1/automations/team_upload/{automation_id}/export
curl http://localhost:8080/api/v1/automations/team_stream/{automation_id}/export
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"}

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

CLIREST API

masv automation import 'base64_data'

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