Managing Watch Folders with the Node API

You can use the Node API to create, remove, and manage watch folders. The instructions below uses curl commands to interact with the Node API.

This documentation covers how to retrieve a list of watch folders, update the configuration of watch folder, and delete a watch folder. For instructions on creating a watch folder with the Node API, see Creating a Watch Folder with the Node 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 https://host:node_api_port/v3/watchfolders

For example:

# curl -k --user watchfolder_admin:XF324cd28 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> 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 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> https://host:node_api_port/v3/watchfolders/watchfolder_id

For example:

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

Copy the output in a .json file.

Updating a watch folder

To update a watch folder configuration, you must first 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. Follow the steps provided prevoiusly to query and save a configuration for the watch folder.

Next, open the 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 (******). You must enter the password again as part of your changes.

Run the following command, specifying the modified configuration file as the JSON file:

# cat path/to/json_file | curl -k --user node_api_user:node_api_password -X PUT -d @- https://host:node_api_port/v3/watchfolders/watchfolder_id

For example:

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

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

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 prevoiusly 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:

# cat path/to/json_file | curl -k --user node_api_user:node_api_password -X POST -d @- https://host:node_api_port/v3/watchfolders

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

# cat ~/watchfolder_conf.json | curl -k --user admin2:XF324cd28 -X POST -d @- 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 above. If the watch folder ID is no longer listed, the watch folder was successfully deleted.