Referring to a resource by its ID

Note - as of at least MarkLogic 11, and possibly MarkLogic 10 and earlier versions, the original use case for this - creating an app server file that references a certificate template - is no longer valid. An app server file can now reference the name of a certificate template. The information below is still accurate, but the feature in question can likely be removed.

Some resources must refer to other resources by their ID. For example, an HTTP server can reference an SSL certificate template, but this must be done using the ID of the certificate template as opposed to its name. This creates an issue when writing the configuration file - there's no way to know the ID of a certificate template that hasn't been created, as MarkLogic will generate that ID (this is contrary to what the docs currently imply - that template-id field will be ignored). This issue doesn't exist when you can refer to a resource by its name - e.g. an app server file can refer to a modules database by its name.

To resolve this, a command class that extends AbstractResourceCommand can choose to store the ID of any resource that it creates/updates as a key/value pair in the customTokens map of AppConfig. The ID can then be inserted into another resource config file via token substitution.

Here's how it works, using a certificate template and an app server as an example:

1. DeployCertificateTemplatesCommand sets storeResourceIdsAsCustomTokens to true.
2. When a cert template is created or updated, AbstractResourceCommand will store a token with a key of "%%id-(resources name)-(resource name)%%" and a value of the created/updated resource ID. Assuming a cert template name of "sample-template" and an ML-generated ID of 12345, the key will be "%%id-certificate-templates-sample-template%%" and the value will be 12345.
3. In the config file for an app server that wishes to use sample-template, a developer can include (assuming JSON) "ssl-certificate-template":"%%id-certificate-templates-sample-template%%". When that file is processed, the token will be replaced with the ID of the cert template.

Note in the above scenario, DeployServersCommand will only work if DeployCertificateTemplatesCommand has been run, as the latter needs to have populated the token. In ml-gradle terms, that means mlDeployServers will not be able to resolve the token, since that Gradle task doesn't run the command for deploying certificate templates.

As of version 2.0b3, this has only been tested on certificate templates, but it should work for most commands - just set "storeResourceIdsAsCustomTokens" to true.