Managing Watch Folders with the API

Retrieve a list of Watch Folders

To retrieve a list of Watch Folders, run the following curl command:

# curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders

For example:

# curl -k --user watchfolder_admin:XF324cd28 -H "X-aspera-WF-version:2017_10_23" -X GET https://198.51.100.22:9092/v3/watchfolders
{
"ids" : [
"b394d0ee-1cda-4f0d-b785-efdc6496c585"
]
}

If there are no running Watch Folders, the server returns the following output.

{
"ids" : [

]
}

Check state, statistics, and status of a watch, transfer, or Watch Folder

curl -ks -u node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders/watchfolder_id/state

In the following example, the output shows Watch Folder errored due to a configuration option that was not set. Errors with ascp transfers are displayed similarly in the transport section.

# curl -ks --user watchfolder_admin:XF324cd28 -H "X-aspera-WF-version:2017_10_23" -X GET https://198.51.100.22:9092/v3/watchfolders/b394d0ee-1cda-4f0d-b785-efdc6496c585/state
{
  "state": "HEALTHY",
  "statistics": {
    "files_transferred": 0,
    "files_succeeded": 0,
    "files_failed": 0,
    "files_skipped": 0,
    "files_ignored": 0,
    "files_disappeared_before_cool_off": 0,
    "files_unsatisfied_dependency": 0,
    "files_never_appeared": 0,
    "bytes_completed": 0,
    "bytes_written": 0
  },
  "components": {
    "watch": {
      "state": "HEALTHY",
      "state_changed_at": "2016-12-19T20:18:47Z"
    },
    "transport": {
      "state": "UNKNOWN",
      "state_changed_at": "2016-12-19T20:17:48Z"
    },
    "watchfolderd": {
      "state": "HEALTHY",
      "state_changed_at": "2016-12-19T20:18:47Z",
      "last_error": "UAC don't allow raw_options",
      "last_error_at": "2016-12-19T20:18:10Z"
    }
  }
}

Query and save a configuration for a specific Watch Folder

# curl -ks -u node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders/watchfolder_id > config_file.json

For example:

# curl -ks --user watchfolder_admin:XF324cd28 -H "X-aspera-WF-version:2017_10_23" -X GET https://198.51.100.22:9092/v3/watchfolders/b394d0ee-1cda-4f0d-b785-efdc6496c585 > wf_config1.json

Copy the output in a .json file.

Retry a failed drop

Watch Folders groups files into "drops" for transfer. If a file in a drop fails to transfer, it is automatically retried based on the Watch Folder configuration (see options in the "error_handling" section, Watch Folder JSON Configuration File Reference). A drop is marked as failed if the file does not transfer within the specified retry period.

You can retry to transfer the failed drop through the Watch Folder API by retrieving the Watch Folder ID and drop ID, then updating the state of the drop:

Get the ID of the Watch Folder that you want to update by getting a list of Watch Folders:

# curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders

Get the ID of the failed drop:

# curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders/watchfolder_id/drops?state="FAILED"

If you need to disambiguate failed drops by seeing the files that are contained in them, you can run the following command:

# curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders/watchfolder_id/drops/drop_id/files

Retry the drop by changing the state to RETRY:

# curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X PUT https://host:node_api_port/v3/watchfolders/watchfolder_id/drops/drop_id -d'{"state":"RETRY"}'

The drop transfer now retries for the specified number of attempts within the retry period.

Updating a Watch Folder

To update a Watch Folder configuration, retrieve the Watch Folder's configuration, make the desired changes, and then save the configuration as a JSON file.

You cannot use a new configuration file, because the new configuration file must match the old file exactly, except for the changes you are making, and because the configuration version number increments with each update.

Get the ID of the Watch Folder that you want to update by getting a list of Watch Folders:

# curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders

Save the Watch Folder configuration file for editing:

# curl -ks -u node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders/watchfolder_id > config_file.json

Open the configuration file in an editor, make your changes, and save the file.
Note: When aswatchfolderadmin returns the JSON configuration, it obfuscates the password for the host with asterisks (******). If you do not want to update the password, leave it obfuscated (as asterisks) in the new file and the old password is used. To update the password, enter the new string. If no password is specified, then the password value is empty and transfers cannot be authenticated.
Update the Watch Folder configuration by sending the updated configuration file:
```
# curl -kv --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X PUT -d @/path_to_json https://host:node_api_port/v3/watchfolders/watchfolder_id
```
Note: The header "X-aspera-WF-version:2017_10_23" is required when submitting POST, PUT, and GET requests to /v3/watchfolders on servers that are version 3.8.0 or newer. This enables Watch Folders to parse the JSON "source" and "target" objects in the format that was introduced in version 3.8.0.

For example:
```
# curl -kv --user watchfolder_admin:XF324cd28 -H "X-aspera-WF-version:2017_10_23" -X PUT -d @/tmp/wf_config_update.json https://198.51.100.22:9092/v3/watchfolders/b394d0ee-1cda-4f0d-b785-efdc6496c585
```
If the update is successful, then the following is returned:
```
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
```

Moving a Watch Folder from one user or daemon to another

To move a Watch Folder configuration, you must first retrieve the Watch Folder's configuration, make the desired changes, and then create a new Watch Folder with the modified configuration file. Follow the steps provided previously to query and save a configuration for the Watch Folder.

Open the configuration file in an editor and make the following changes:

Remove the "id" field.
Remove the "version" field.
Re-enter the password in the "pass" field.
Set proper watchfolderd IDs in the ("wfd_id") fields

Save the configuration file and then run the following command, specifying the modified configuration file as the JSON file:

# curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X POST -d @path/to/json_file https://host:node_api_port/v3/watchfolders

For example, to change the user to admin2, run the following:

# curl -k --user admin2:XF324cd28 -H "X-aspera-WF-version:2017_10_23" -X POST -d @~/watchfolder_conf.json https://198.51.100.22:9092/v3/watchfolders
{
"id": "b394d0ee-1cda-4f0d-b785-efdc6496c585"
}

To verify that the configuration was updated, retrieve the configuration file again and look for your changes.

Deleting a Watch Folder

To remove a Watch Folder, run the following command:

# curl -sk --user node_api_user:node_api_password -X DELETE https://host:node_api_port/v3/watchfolders/watchfolder_id

For example:

# curl -k --user watchfolder_admin:XF324cd28 -X DELETE https://198.51.100.22:9092/v3/watchfolders/b394d0ee-1cda-4f0d-b785-efdc6496c585

To verify that the Watch Folder was removed, retrieve the list of Watch Folders with the command as shown previously. If the Watch Folder ID is no longer listed, the Watch Folder was successfully deleted.