A new feature in version 3 of opscotch is the capability to access files. As security is always a top priority, file access is strictly controlled in several ways.

How does this work?

Firstly, workflows cannot simply access any arbitrary file - workflows can ONLY access files (or directories) that have been specified in the bootstrap using the allowFileAccess property. Since the bootstrap cannot be changed remotely, the files available to opscotch workflows are limited to those defined by the administrator who installs opscotch.

Files listed in the allowFileAccess property must include at a minimum: an id, a directoryOrFile (the path), and a permission. When workflows request access to a file, the id is used to select the file from the bootstrap, and the workflow can append a path to the base path - the workflow cannot change the base path, only extend it.

A second layer of security is provided by the patterns property on the bootstrap file record. The patterns property is a set of path regex patterns that will allow access when matched. For example, you can allow .*\\.txt$ (all .txt files) and .*\\.log$ (all .log files). In this scenario, requests for .doc, .csv, or any other file type would fail.

Take a look at the documentation and note the key properties:

• id: This is how you will refer to the file or directory from your workflow (e.g., myDirectory).
• directoryOrFile: This is the base path from which you permit your workflow to request files (e.g., /a/path).
• patterns: You can specify a list of allowed file-matching regex patterns to match paths.
• LIST: When this is set to true, workflows can LIST files in the directory.
• READ: When this is set to true, workflows can READ the file.
• WRITE: When this is set to true, workflows can WRITE to the file or create new files.

How to use allowFileAccess from Workflows?

In the bootstrap, you will need to add the file permissions we described to the allowFileAccess property:

Bootstrap:

{
    ...
    "allowFileAccess": [
        {
            "id": "myDirectory",
            "directoryOrFile": "/a/path",
            "LIST": true,
            "READ": true,
            "WRITE": true
        }
    ],
    ...
}

From a step processor JavaScript script, use the files(...) method to obtain access to the file context for the requested id:

var fileContext = context.files("myDirectory");

Refer to the documentation for the FileContext, which includes three functions:

• list(String path)
• read(String file)
• write(String file, String body)

To list a directory, you can do the following:

var listing = list("/");

This will return a list of objects with name and type properties. The type will either be FILE or DIRECTORY.

For example, the listing above might look like this:

[
    {"name" : "aFile.txt", "type" : "FILE"},
    {"name" : "aDir", "type" : "DIRECTORY"},
]

You can then use the results as follows:

// listing another directory
var moreListing = fileContext.list("/aDir");

// or reading the file
var fileContents = fileContext.read("/aFile.txt");

// or write to the file
fileContext.write("/aFile.txt", "new contents");