Exporting resources

As of version 2.7.0, the mlExportResources task can be used to export one or more resources via the Manage API. This task is largely based on the APIs in ml-app-deployer.

Supported resources

In version 2.7.0, support is provided for exporting the following resources:

1. Servers, which by default exports the content-database and modules-database attached to each server.
2. Databases, which by default exports the forests attached to the database (but not yet the triggers, schemas, or security databases, as those sometimes are the default ones that probably aren't worth exporting).
3. Forests, though it's much more likely to just export the databases that forests are attached to.
4. Scheduled tasks
5. Users, roles, and privileges
6. Version 2.9.0 adds the ability to export amps.
7. Version 3.2.0 adds the ability to export groups.
8. Version 3.5.0 adds the ability to export CPF resources - domains, pipelines, and CPF configs - and triggers.

Important! As discussed in the Notes section below, some resources will need manual editing in order for them to be deployable.

Usage

mlExportResources provides multiple options for specifying resources to export - each is specified via a Gradle property flag on the command line.

You can export resources whose name starts with a prefix:

gradle -Pprefix=myapp mlExportResources

You can export resources whose name matches a regular expression:

gradle -Pregex=.*myapp.* mlExportResources

When using a prefix or regex, you can also restrict the types that are exported via -PincludeTypes (the type values are all defined in the properties file example below):

gradle -PincludeTypes=databases,servers -Pregex=.*myapp.* mlExportResources

For the most control, but which requires the most work, you can use a properties file to specify the exact name of each resource:

gradle -PpropertiesFile=path/to/file.properties mlExportResources

And in that properties file, you specify the names using any of the following keys with comma-delimited values:

cpfConfigs=my-domain-1 (new in 3.5.0, and CPF configs are identified by a domain name)
databases=my-database1,my-database2
domains=my-domain-1,my-domain-2 (new in 3.5.0)
groups=my-group (new in 3.2.0)
pipelines=my-pipeline-1 (new in 3.5.0)
privilegesExecute=my-privilege-1
privilegesUri=my-privilege-2
roles=my-role-1,my-role-2
servers=my-server-1,my-server-2
tasks=/path/to/task.xqy,/path/to/other/task.xqy
triggers=my-trigger-1,my-trigger-2 (new in 3.5.0)
users=user1,user2

Note that privileges are separated into "privilegesExecute" and "privilegesUri", as the Manage API requires specifying the kind of privilege when exporting it.

By default, resources are exported to files in mlConfigDir, which defaults to src/main/ml-config. You can override this too:

gradle -PexportPath=/some/other/path -Pprefix=test mlExportResources

Note that with Java 11, if you're using the Gradle daemon, then the path you provide will be relative to the directory that the daemon is launched from. Thus, you most likely want to use an absolute path when providing a value for exportPath.

And to see what ml-gradle is up to while exporting, just include the Gradle "-i" or "--info" flag - every call to the Manage API will be logged, along with what files are being written:

gradle -i -Pprefix=test mlExportResources

Notes

1. Generally, prefer the regex selector over the prefix selector.
2. The prefix selector above may not work on the command line with Gradle, as if a task path begins with "/", Gradle thinks it's something else and prepends other text to it. It's better to use a regex for selecting tasks.
3. When an export finishes, it will print all the files that were written, along with a set of messages. These messages often provide warnings about the exported resources, such as how exported users are missing their passwords (as passwords cannot be retrieved via the Manage API, for good reason - though in version 2.9.0, a default password is now set). Pay attention to these, as you'll most likely need to make some changes to the exported files in order for them to be deployable.
4. After an export, consider whether you should set mlNoRestServer to true. If your application does not have a need a REST API server, then you should set this property so that ml-gradle doesn't try to create one (along with a content and modules database) by default.