Scheduled Tasks

This page has been started for the 3.10.0 release and will eventually document as many of the features as possible specific to deploying scheduled tasks.

Deploying multiple tasks with the same task-path

Release 3.10.0 introduces support for deploying multiple scheduled tasks with the same task-path. ml-app-deployer now uses both the task-path and the task-database properties to determine if a task has already been deployed. The thought behind this is that it is very unlikely to want to run the same scheduled task against the database, but at different times. If you do have a need to do so, please create an issue to explain your use case. As a workaround, you can create two separate scheduled task modules that invoke the same library function.

Assigning scheduled tasks to groups

By default, a scheduled task will be deployed against the group defined by the "mlGroupName" property. As of 2.6.0, you can assign a scheduled task to any group by using a child directory. For example, if you want one task deployed to the Default group, which is also the value of mlGroupName, and then another task deployed to group1, and then a third task deployed to group2, you'd have the following structure under in your configuration directory (the filenames are irrelevant, it's the directory names that matter):

ml-config/tasks
  default-group-task.json
  /group1
    group1-task.json
  /group2
    group2-task.json

Creating disabled scheduled tasks

In 3.15.0, to work around a bug in the Manage API, ml-app-deployer will make a second call to the Manage API when creating a scheduled task with task-enabled = false. This is because regardless of that setting, the Manage API will always create a scheduled task in an enabled state.

Referring to host names in scheduled task files

The Manage API for creating a scheduled task accepts a property named "task-host", which must be a host name. But you rarely want to hardcode this, as those names are likely to change across environments.

For version 3.13.0 or higher

Starting with version 3.13.0, you can set the following property so that host names are automatically added to the custom tokens map before any commands are executed:

mlAddHostNameTokens=true

For each host in your cluster, a token will be added to the token map (appConfig.getCustomTokens()) with a name of "mlHostName(host index)". For example, if you have 3 hosts in your cluster with names host1, host2, and host3, the following 3 tokens will be added to the map:

mlHostName1=host1
mlHostName2=host2
mlHostName3=host3

These tokens can then be referenced in scheduled task files - e.g.

"task-host": "%%mlHostName1%%"

Note that in order for these tokens to be added, a command must be executed via a subclass of AbstractAppDeployer. In an ml-gradle context, this means you need to run a task that deploys resources (mlDeploy or any task that starts with mlDeploy*).

Prior to 3.13.0

Before version 3.13.0, you can use a script like one below to fetch the host names and set them as tokens that can be replaced in payload files (this particular script assumes there are at most 3 hosts; you can of course customize this to support any number of hosts).

task setHostTokens {
	doLast {
		def manageConfig = new com.marklogic.mgmt.ManageConfig(mlHost, 8002, mlUsername, mlPassword)
		def hostManager = new com.marklogic.mgmt.resource.hosts.HostManager(new com.marklogic.mgmt.ManageClient(manageConfig));

		hostManager.getHostNames().eachWithIndex { hostName, index ->
			mlAppConfig.customTokens.put("%%mlHostName" + index + "%%", hostName)
		}

		println "First host: " + mlAppConfig.customTokens.get("%%mlHostName0%%")
	}
}
mlDeployApp.dependsOn setHostTokens
mlDeployTasks.dependsOn setHostTokens

You can then reference the token in a scheduled task file like this:

"task-host": "%%mlHostName0%%"

Note there's nothing special about the "%%" delimiters, they're just a default way of making tokens more obvious and less susceptible to being replaced by accident.