Roles

Roles are a more complex resource to deploy via the Manage API. That roles can depend on each other and also on themselves (via default permissions) means that care must be taken to deploy them in the correct order.

This page will eventually document all the concerns for deploying roles, but in the meantime, please see the source code for DeployRolesCommand to understand the various issues that must be handled.

Roles with capability queries

MarkLogic 10.0-7 supports defining capability queries as part of a role. However, there are some issues with both JSON and XML payloads to be aware of.

JSON payloads

A typical approach for knowing what to put into a resource file is to create the resource via the Admin UI and then perform a GET on it via the Manage API. However, a bug in ML 10.0-7 results in the wrong JSON being returned for the "query" portion of a capability query (bug #56738). To generate the correct JSON representation of a query, you should use either https://docs.marklogic.com/xdmp:to-json-string or https://docs.marklogic.com/xdmp.toJsonString on your query, which can be easily done via QConsole.

An example of using xdmp.toJsonString:

xdmp.toJsonString(cts.wordQuery("hello"))

This produces an output of:

{"wordQuery":{"text":["hello"], "options":["lang=en"]}}

That JSON can then be inserted into your role file as the "query" portion of a capability query:

{
	"role-name": "a-qbac-role",
	"capability-query": [
		{
			"capability": "read",
			"query": {"wordQuery":{"text":["hello"], "options":["lang=en"]}}
		},
		{
			"capability": "update",
			"query": {"wordQuery":{"text":["hello"], "options":["lang=en"]}}
		}
	]
}

XML payloads

An XML payload runs into an issue with capability queries when the role is deployed via CMA (the Configuration Management API). Thus, in order for an XML payload to be deployed, you must disable CMA usage for roles. In ml-gradle, that is done via the following property:

mlDeployRolesWithCma=false

Or just turn off all CMA usage:

mlDeployWithCma=false

If you're using ml-app-deployer libraries directly, you can do the following your with AppConfig instance:

appConfig.getCmaConfig().setDeployRoles(false);

For reference, here's an example of an XML payload with a capability query:

<role-properties xmlns="http://marklogic.com/manage">
	<role-name>a-qbac-xml-role</role-name>
	<queries>
		<capability-query>
			<capability>read</capability>
			<query>
				<cts:word-query xmlns:cts="http://marklogic.com/cts">
					<cts:text xml:lang="en">hello</cts:text>
				</cts:word-query>
			</query>
		</capability-query>
		<capability-query>
			<capability>update</capability>
			<query>
				<cts:word-query xmlns:cts="http://marklogic.com/cts">
					<cts:text xml:lang="en">world</cts:text>
				</cts:word-query>
			</query>
		</capability-query>
	</queries>
</role-properties>