Generating new resources

Starting in release 3.6.0, ml-gradle provides several tasks for generating new resource files. These tasks have two goals:

1. Create a new resource file in the appropriate directory so that a user doesn't have to figure out the right directory to use
2. Provide some sensible default properties in the resource file so that a user can more easily create the resource without having to read the Manage API docs and/or configure the resource via the Admin UI first

The following tasks are provided - see below for usage details:

• mlNewAmp
• mlNewDatabase
• mlNewExternalSecurity
• mlNewGroup
• mlNewPrivilege
• mlNewProtectedCollection
• mlNewRole
• mlNewServer
• mlNewTask
• mlNewTrigger - new in 3.14.0, and requires the name of a triggers database via -Pdatabase=
• mlNewUser

Usage

Let's use mlNewDatabase for these examples - the tasks all behave the same way, they just generate different resources.

You can run mlNewDatabase with no arguments:

gradle mlNewDatabase

This will generate a new file named "Database-(system timestamp).json". The "system timestamp" bit is included to minimize the chance of overwriting an existing file. You'll most likely want to name this to something more meaningful (though you don't have to). The file is created in the "databases" directory within the first directory defined by the "mlConfigPaths" property (which allows multiple configuration directories). This defaults to src/main/ml-config, so the file will be written to src/main/ml-config/databases.

The new database file will have the following contents:

{
  "database-name" : "CHANGEME-name-of-database",
  "forest" : [ ],
  "enabled" : true,
  "element-word-query-through" : [ ],
  "phrase-through" : [ ],
  "phrase-around" : [ ],
  "range-element-index" : [ {
    "scalar-type" : "string",
    "namespace-uri" : "CHANGEME-namespace-of-element",
    "localname" : "CHANGEME-name-of-element",
    "collation" : "http://marklogic.com/collation/",
    "range-value-positions" : false
  } ],
  "field" : [ ]
}

For every resource, ml-gradle will include a handful of fields to get you started with configuring the resource (the work is actually done by the ml-app-deployer library that ml-gradle depends on, in case you're looking to customize this behavior). Some notes about what's in this resource file:

1. "CHANGEME" is used for every property value that most likely needs to be changed
2. For most resources, the list properties will be stubbed out so it's obvious which properties require an array of values or objects.
3. Not all of the properties are stubbed out because either the Manage API doesn't allow an empty string, or doing so would require selecting a value that may not apply to the resource.
4. Because it's very common to add one or more range indexes to a database, this resource file has one range index defined so you can e.g. copy/paste it to add more.

You can also specify values for any simple resource property (anything that's not an array). To do so, use the Gradle property flag ("-P") plus the property name with a prefix of "ml-":

gradle mlNewDatabase -Pml-triple-index=true -Pml-database-name="my-database"

These Gradle properties will be used in addition to the default properties, with the Gradle properties overriding the default properties (e.g. "ml-database-name" will override the default value of "database-name").

The "ml-" prefix is needed so that resource properties like "description", which match the name of default Gradle properties, can be specified. The mlNewDatabase task, like all other resource tasks, will only apply Gradle properties starting with "ml-".