Configuration Management API

The MarkLogic Configuration Management API - CMA - provides a mechanism for creating and updating many resources in a single request to MarkLogic. This can make deployments significantly faster, as potentially dozens of requests can be combined into a single request.

Supported resource types

CMA usage was first introduced in version 3.8.0 of ml-app-deployer, where it was used to speed up the creation of forests. Support for amps and privileges was added in 3.11.0. Support for databases, protected paths, query rolesets, roles, servers, and users was added in 3.15.0.

The 3.15.0 release also defaults to using CMA for all supported resource types except servers. This support has been tested extensively, but if you run into any problems with it, you can turn off CMA usage completely by setting the "mlDeployWithCma" property to "false" (and please file an issue too).

CMA and the MarkLogic version you're using

The 3.15.0 release and higher should be used with MarkLogic 9.0-9 or higher. This is due to some bugs in CMA pertaining to users in versions of MarkLogic prior to 9.0-9. If you're not yet on 9.0-9, you should disable deploying users with CMA via the "mlDeployUsersWithCma" property.

Combined requests

Version 3.15.0 also introduces the concept of combining certain resource types into a single CMA request for further performance gains. In 3.15.0, the following combined requests are submitted:

• Privileges, protected paths, query rolesets, roles, and users are all combined into a single request and submitted
• Databases and forests created via properties are submitted in a single request (custom forests are still submitted separately, along with sub-databases and their forests)

A note about roles - before roles are submitted, ml-app-deployer will check each role to see if it refers to itself (via permissions) and does not exist in MarkLogic yet. Each such role will first be created in a separate request, as otherwise, the combined CMA request will fail to create the role correctly.

Properties

The table below lists all properties available for configuring CMA usage.

Property	Description
mlDeployWithCma	New in 3.15.0 - controls whether CMA is used for any resource types. This property is applied before all other "*WithCma" properties, such that you could set it to false but still enable certain resource types to use CMA. Defaults to false (as servers are not deployed with CMA by default).
mlCombineCmaRequests	New in 3.15.0 - controls whether certain resource types (listed above) will be combined into requests for better performance. Defaults to true.
mlDeployAmpsWithCma	New in 3.11.0 - deploy amps via CMA. In 3.15.0, defaults to true; before that, defaults to false.
mlDeployDatabasesWithCma	New in 3.15.0 - deploy databases (excluding sub-databases) via CMA. Defaults to true.
mlDeployForestsWithCma	New in 3.11.0 (replaces mlOptimizeWithCma) - deploy forests via CMA. Note that prior to 3.15.0, forests for the default content database are excluded. In 3.15.0, defaults to true; before that, defaults to false.
mlDeployPrivilegesWithCma	New in 3.11.0 - deploy privileges via CMA. In 3.15.0, defaults to true; before that, defaults to false.
mlDeployProtectedPathsWithCma	New in 3.15.0 - deploy protected paths via CMA. Defaults to true.
mlDeployQueryRolesetsWithCma	New in 3.15.0 - deploy query rolesets via CMA. Defaults to true.
mlDeployRolesWithCma	New in 3.15.0 - deploy roles via CMA. Defaults to true.
mlDeployServersWithCma	New in 3.15.0 - deploy servers via CMA. Defaults to false, as testing hasn't shown this to always help with performance, and certain changes to servers will fail via CMA as well.
mlDeployUsersWithCma	New in 3.15.0 - deploy users via CMA. Defaults to true.
mlOptimizeWithCma	New in 3.8.0, but deprecated in 3.11.0 - when using ML 9.0-5 or greater, you can set this to true to optimize the creation of forests via a CMA (Configuration Management API) package. Defaults to false.