For the complete Automation API endpoint reference, go to Aspera on IBM API Explorer.

This page contains request and response examples for the following actions that can be created in an Automation workflow:

Note: Each workflow must contain at least one action that transfers a file or sends a package.

For a full example of a fourth type of action, which transfers a file, go to Aspera on IBM API Explorer.

Action that Sends a Package

Parameter Definitions

Parameter Name Required Type Description
data true object Payload for the action
package true object Details about the package being sent
recipients false string Details about package recipients
id true string Recipient ID
type true string User type of recipient. Allowed values: user, admin.
name false string Name of recipient
bcc_recipients false array Details about bcc: package recipients
id true string Recipient ID
type true string User type of recipient. Allowed values: user, admin.
name false string Name of recipient
upload_notification_recipients false array Details about recipients of package upload notification
id true string Recipient ID
type true string User type of recipient. Allowed values: user, admin.
name false string Name of recipient
download_notification_recipients false array Details about recipients of package download notification
id true string Recipient ID
type true string User type of recipient. Allowed values: user, admin.
name false string ame of recipient
content_retention_duration false integer Length of time that content should be retained at the transfer destination, in seconds
name false string Name of package
target_rate false object Rate and retry conditions for the transfer
rate true integer Transfer rate, in bytes per second
allow_retry true boolean Whether to allow retry of a failed transfer
retry_attempts true integer Number of times Automation can retry the transfer
retry_interval true integer Length of time to wait before retrying the transfer, in seconds
content_encryption false object
encryption true string Method of content encryption. Allowed value: AES-128, none. Default: none.
apply_protection true boolean Apply protection to the file transfer
password true string Password for the transfer, used if the value of apply_protection is true.
resume_policy false object Policy for resuming a transfer
difference_check true string Type of check used to validate content. Allowed values: sparse_checksum, full_checksum, file_attributes.
resume_partials true boolean Partial transfers should be resumed
destination_file_options true string Processing options for the file at the destination. Allowed values: ‚Äúoverwrite_always‚ÄĚ, ‚Äúoverwrite_both_newer_and_different‚ÄĚ, ‚Äúoverwrite_different‚ÄĚ, ‚Äúoverwrite_newer‚ÄĚ, ‚Äúoverwrite_never‚ÄĚ.
file_attributes false boolean File attributes are defined
source_archive false object Archive policy for the transfer source
archive_option true string Archive policy for the package at the source. Allowed values: none, archive, delete.
delete_empty_subdirectories false boolean Delete empty subdirectories at source after transfer
archived_file_location false object For an archive_option of ‘archive’, the location where the file will be archived
node_id false string ID of node where the archive is located
file_name false string Filename of file to be archived
file_id false string ID of file to be archived
conditions_type false string The conditions type for the transfer, either a default condition to transfer all new files or a custom filtering condition. Allowed values: custom, all_new
join_type false string The logical operator that joins multiple conditions. Allowed values: and, or.
conditions false array Filtering conditions for the transfer
field_name false string Name of the condition field. Allowed values: file_name, extension_name, file_size
field_type false string Type of the condition field. Allowed values: string, byte. The value ‘string’ is used with a field_name of file_name or extension_name. The value ‘byte’ is used with a field_name of file_size.
match_type false string Logic for the matching condition. Allowed values: includes, excludes, matches, regex, equal, greater_than, less_than, greater_than_or_equal, less_than_or_equal. A value of includes, excludes, matches, or regex is used with a field_name of file_name or extension_name. A value of equal, greater_than, less_than, greater_than_or_equal or less_than_or_equal is used with a field_name of file_size.
value false string Value of the condition, for example, .jpg
source true object Source for the transfer
type false string Source type for the transfer. Allowed values: workspace, node.
file_id false string ID of file that is transferred
file_name false string Name of file that is transferred
node_id false string ID of source node
node_name false string Name of source node
paths false array Source paths for transfer; array of objects
source false string Source path for the transfer, for example: “/”.
token false string Bearer token for the transfer
substitutions false array Data for substitution variables from previous steps, inserted into the message
template false string Template for insertion of substitution variables in the message, for example:

{{step_id_1357.action_id_1409.node_id}}
path false array Path to the substitution variable
name false string Name for the path. Allowed values: source, file_id, node_id, message, value, conditions.
type false string Path type. Note that path type = map indicates a key:value pair. Allowed values: map, array.
index false integer Index of the substitution variable
type false string Action type. For package send action, always package_transfer.
step_id false string ID of the step that contains the action

Request and Response Examples

Request URL: https://api.qa.ibmaspera.com/automation/v1/actions
Request Method: POST
Status Code: 201 Created

{
  "data": {
    "package": {
      "recipients": [jjones@company.com],
      "bcc_recipients": [ssalir@company.com],
      "content_retention_duration": 604800,
      "upload_notification_recipients": [thonor@company.com],
      "download_notification_recipients": [qsurprise@company.com],
      "name": "project notes",
      "note": new files
    },
    "target_rate": {
      "rate": 10000,
      "allow_retry": true,
      "retry_attempts": 3,
      "retry_interval": 30
    },
    "content_encryption": {
      "encryption": "aes-128"
    },
    "resume_policy": {
      "resume_partials": true,
      "difference_check": "sparse_checksum"
    },
    "file_attributes": true,
    "source_archive": {
      "archive_option": "archive",
      "delete_empty_subdirectories": true,
      "archived_file_location": {
        "node_id": "95",
        "file_name": "0108",
        "file_id": "1780369"
      }
    },
    "conditions_type": "all_new",
    "join_type": "and",
    "conditions": [
      {"field_name": "file_name",
       "field_type": "string",
       "match_type": "includes", 
       "value": "final"
      }
    ],
    "source": {
      "type": "node",
      "node_name": "Tor02_node",
      "node_id": "95",
      "file_name": "01-test",
      "file_id": "1730980",
      "paths": [
        {
          "source": "/"
        }
      ],
      "token": "VGRFQVV1Uy15SS1rcE9VZDlUT3FNSjhJb3otXzYxZkQwWEJoeTJfUFRTZ0E6YXNwZXJh"
    },
    "substitutions": [
      {
        "template": "dsdfsd{{step_id_1604.action_id_1668.filename}}{{step_id_1604.action_id_1668.timestamp}}",
        "path": [
          {
            "name": "package",
            "type": "map"
          },
          {
            "name": "note",
            "type": "map"
          }
        ]
      }
    ]
  },
  "type": "package_transfer",
  "step_id": "1605",
  "organization_id": "58",
  "user_id": "3201"
}

#RESPONSE:

{
  "id": "1669",
  "name": null,
  "type": "package_transfer",
  "data": {
    "package": {
      "recipients": [jjones@company.com],
      "bcc_recipients": [ssalir@company.com],
      "content_retention_duration": 604800,
      "upload_notification_recipients": [thonor@company.com],
      "download_notification_recipients": [qsurprise@company.com],
      "name": "project notes",
      "note": new files
    },
    "source": {
      "type": "node",
      "node_name": "Tor02_node",
      "node_id": "95",
      "file_name": "01-test",
      "file_id": "1730980",
      "paths": [
        {
          "source": "/"
        }
      ],
      "token": "SVGFQVV1Uy15SS1rcE9VZDlUT3FNSjhJb3otXzYxZkQwWEJoeTJfUFRTZ0E6YXNwZXJj"
    },
    "file_attributes": true,
    "conditions_type": "all_new",
    "join_type": "and",
    "target_rate": {
      "rate": 10000,
      "allow_retry": true,
      "retry_attempts": 3,
      "retry_interval": 30
    },
    "content_encryption": {
      "encryption": "aes-128"
    },
    "resume_policy": {
      "resume_partials": true,
      "difference_check": "sparse_checksum"
    },
    "source_archive": {
      "archive_option": "archive",
      "delete_empty_subdirectories": true,
      "archived_file_location": {
        "node_id": "95",
        "file_name": "0108",
        "file_id": "1780369"
      }
    },
    "conditions": [
      {"field_name": "file_name",
       "field_type": "string",
       "match_type": "includes", 
       "value": "final"
      }
    ],
    "substitutions": [
      {
        "template": "dsdfsd{{step_id_1604.action_id_1668.filename}}{{step_id_1604.action_id_1668.timestamp}}",
        "path": [
          {
            "type": "map",
            "name": "package"
          },
          {
            "type": "map",
            "name": "note"
          }
        ]
      }
    ]
  },
  "outputs": {
    "package_id": "string",
    "status": "string"
  }

Action to Call an API

Parameter Definitions

Parameter Name Required Type Description
data true object Payload for the action
method true string API method for the request. Allowed values: get, post, put, delete.
headers false array Request headers
key true string Header key
value true string Header value
authentication false object Authentication for the request.
type false string “Authentication type required by the API. Allowed values:¬†bearer, basic, none. Default: none. Use ‘bearer’ for bearer token¬†authentication, for basic authentication, ‘none’ for no authentication¬†method.

The bearer authentication¬†type requires a token parameter. The basic authentication type¬†requires username and¬†password parameters. The ‘none’ authentication type does not require¬†additional parameters.”

token true string Bearer token for bearer authentication
username true string Username for basic authentication
password true string Password for basic authentication
endpoint true string (URI) Endpoint for the request
substitutions false array Data for substitution variables from previous steps, inserted into the message
template false string Template for insertion of substitution variables in the message, for example:

{{step_id_1357.action_id_1409.node_id}}
path false array Path to the substitution variable
name false string Name for the path. Allowed values: source, file_id, node_id, message, value, conditions.
type false string Path type. Note that path type = map indicates a key:value pair. Allowed values: map, array.
index false integer Index of the substitution variable
type false string Action type. For an action that calls an API, type is always api.
step_id false string ID of the step that contains the action

Request and Response Examples

Request URL: https://api.qa.ibmaspera.com/automation/v1/actions
  Request Method: POST
  Status Code: 201 Created

  {
  "data": {
    "method": "get",
    "headers": [
      {
        "key": "Content-type",
        "value": "xml"
      }
    ],
    "authentication": {
      "type": "none"
    },
    "endpoint": "https://openweathermap.org/api",
    "substitutions": []
  },
  "type": "api",
  "step_id": "1607"
}

#RESPONSE

{
  "id": "1671",
  "name": null,
  "type": "api",
  "data": {
    "method": "get",
    "endpoint": "https://openweathermap.org/api",
    "authentication": {
      "type": "none"
    },
    "headers": [
      {
        "key": "Content-type",
        "value": "xml"
      }
    ],
    "substitutions": []
  },
  "outputs": {
    "status": "string",
    "response_code": "integer",
    "response_body": "hash"
  }
}

Action to Notify Users

Parameter Definitions

Parameter Name Required Type Description
data true object Payload for the action
sender false string Sender for the notification
email_addresses true array Email addresses of recipients
message false string Message for the recipient of the notification
substitutions false array Data for substitution variables from previous steps, inserted into the message
template false string Template for insertion of substitution variables in the message, for example:

{{step_id_1357.action_id_1409.node_id}}
path false array Path to the substitution variable
name false string Name for the path. Allowed values: source, file_id, node_id, message, value, conditions.
type false string Path type. Note that path type = map indicates a key:value pair. Allowed values: map, array.
index false integer Index of the substitution variable
type false string Action type. For a notification step, this is always email_notification.
step_id false string ID of step that contains the action

Request and Response Examples

Request URL: https://api.qa.ibmaspera.com/automation/v1/actions
Request Method: POST
Status Code: 201 Created

{
  "data": {
    "sender": "IBM Aspera on Cloud",
    "email_addresses": [
      "asmith@company.com"
    ],
    "message": files transcoded and transferred,
    "substitutions": [
      {
        "template": "slafjksldjflj{{step_id_1604.action_id_1668.file_id}}{{step_id_1604.action_id_1668.node_id}}{{step_id_1605.action_id_1669.package_id}}{{step_id_1607.action_id_1671.status}}{{step_id_1607.action_id_1671.response_code}}",
        "path": [
          {
            "name": "message",
            "type": "map"
          }
        ]
      }
    ]
  },
  "type": "email_notification",
  "step_id": "1608"
}

#RESPONSE

{
  "id": "1672",
  "name": null,
  "type": "email_notification",
  "data": {
    "email_addresses": [
      "asmith@company.com"
    ],
    "message": null,
    "sender": "IBM Aspera on Cloud",
    "substitutions": [
      {
        "template": "slafjksldjflj{{step_id_1604.action_id_1668.file_id}}{{step_id_1604.action_id_1668.node_id}}{{step_id_1605.action_id_1669.package_id}}{{step_id_1607.action_id_1671.status}}{{step_id_1607.action_id_1671.response_code}}",
        "path": [
          {
            "type": "map",
            "name": "message"
          }
        ]
      }
    ]
  },
  "outputs": {
    "status": "string"
  }
}