Starting version 3.2.0, all Gradle properties will automatically be added to the tokens map, with each property being given a default prefix and suffix of "%%". So for example, the ml-gradle property "mlHost" will be added to the token map as "%%mlHost%%". A custom Gradle property named "myProperty" will be added to the token map as "%%mlHost%%".

This behavior is turned on by default in version 3.2.0. To turn it off, set mlPropsAsTokens to "false".

To customize the prefix and suffix, set the mlTokenPrefix and mlTokenSuffix properties.

For users familiar with Roxy token replacement, you can achieve the same behavior via these properties:

mlTokenPrefix=@ml.
mlTokenSuffix=

There's nothing special about "%%" as the default prefix and suffix; they're just the default because it's not likely to have that character string appearing in your payloads or modules.

To see all of the tokens that will be used for replacement, just run this task:

gradle mlPrintTokens

Prior to version 3.2.0

You can add your own tokens via the "customTokens" Map<String, String> that's available on the mlAppConfig object. Example:

ext {
  customTokens.put("%%MY_TOKEN%%", "someValue")
  customTokens.put("ANOTHER_TOKEN", someGradleProperty)
}

Note that you don't need to use the "%%" prefix and suffix - tokens can be any string. ml-gradle just uses "%%" to make it more obvious that tokens are in fact tokens.

Also see this Wiki page in ml-app-deployer about tokens.

Replacing tokens in modules

A "custom tokens" map can be populated to specify tokens in resource payloads that will be replaced. These tokens will also be replaced in module files - but as of version 3.2.0, this is only done in "asset" modules, not yet REST API modules (services, options, and transforms).

Two properties control this behavior that are worth noting:

1. mlReplaceTokensInModules - controls whether tokens are replaced or not, defaults to true
2. mlUseRoxyTokenPrefix - (see the note below about how this property changes in 3.2.0) expects tokens to start with "@ml.", mirroring Roxy's behavior. This defaults to true; if you don't need these prefixes in place, be sure to set this property to false.

NEW in version 3.2.0 - as described on the Configuring payloads page, all Gradle properties will be added to the tokens map by default. And, mlUseRoxyTokenPrefix now defaults to false, effectively deprecating that feature. You can emulate that behavior by setting the following properties to mirror Roxy's behavior:

mlTokenPrefix=@ml.
mlTokenSuffix=

Thus, in 3.2.0, with mlPropsAsTokens and mlReplaceTokensInModules both defaulting to true, the default behavior is that all Gradle properties are used as tokens (with "%%" as the default prefix and suffix), and these tokens will be replaced in modules if they exist.

Referring to a resource by its ID

In some cases, a resource - such as an app server - must refer to another resource - such as a certificate template - by its MarkLogic-generated ID instead of by the resource name. This creates a problem - what value do you put into the app server config file for the "ssl-certificate-template" field?

See how ml-app-deployer supports this.

The sample-project includes an example of this too.

Examples

databases

{
  "database-name": "%%DATABASE%%",
  "schema-database": "%%SCHEMAS_DATABASE%%",
  "triggers-database": "%%TRIGGERS_DATABASE%%",
  "stemmed-searches" : true
}

roles

{
  "role-name" : "%%mlAppName%%-role",
  "role" : [ "rest-writer", "rest-reader" ],
  "privilege" : [ {
    "privilege-name" : "any-uri",
    "action" : "http://marklogic.com/xdmp/privileges/any-uri",
    "kind" : "execute"
  }, {
    "privilege-name" : "xdbc:insert-in",
    "action" : "http://marklogic.com/xdmp/privileges/xdbc-insert-in",
    "kind" : "execute"
  }, {
    "privilege-name" : "xdmp:eval-in",
    "action" : "http://marklogic.com/xdmp/privileges/xdmp-eval-in",
    "kind" : "execute"
  } ]
}

user

{
  "user-name": "%%mlAppName%%-user",
  "description": "Test user for %%mlAppName%%",
  "password": "%%mlAppName%%-password",
  "role": ["%%mlAppName%%-role"]
}