MarkLogic Server
XQUERY/XSLT API DOCUMENTATION
5.0
All XQuery & XSLT Functions
MarkLogic Built-In Functions
XQuery Library Modules
CPF Functions
W3C-Standard Functions
  W3C XQuery/XSLT Reference
W3C XQuery Functions
W3C XQuery Language
W3C XSLT Language
This page was generated
March  13,  2012
4:48  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Security

The security function module is installed as the following file:

install_dir/Modules/MarkLogic/security.xqy

where install_dir is the directory in which MarkLogic Server is installed.

To use the security.xqy module in your own XQuery modules, include the following line in your XQuery prolog:

import module "http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy"

The library uses the sec: namespace, predefined in the server.

NOTE:    When using these functions to administer security for an application, be sure to execute them against the security database configured for your application's database. Function calls in this library can only be executed against a a security database (for example, Security); the database named Security is automatically configured when MarkLogic Server is installed, and it is the default security database. To execute these functions against the security database, you can specify the database option in xdmp:eval or xdmp:invoke, or you can run it in an App Server that has your security database configured as its database.

Function Summary
sec:amp-add-roles Adds the roles ($role-names) to the list of roles granted to the amp ($namespace, $local-name, $document-uri).
sec:amp-doc-collections Returns a sequence of strings corresponding to the collection uri's that amps belong to.
sec:amp-doc-permissions Returns a sequence of permission elements that all newly created amp documents receive.
sec:amp-exists This function returns true if the specified amp exists in the security database.
sec:amp-get-roles Returns a sequence of role names for the roles directly assigned to the amp ($namespace, $local-name, $document-uri).
sec:amp-remove-roles Removes a role ($role-name) from the set of roles included by the amp ($namespace, $local-name, $document-uri).
sec:amp-set-roles Assigns the amp identified by $namespace, $local-name and $document-uri to have the roles identified by $roles-names.
sec:amps-collection Returns a string corresponding to the uri for the amps collection.
sec:check-admin Throws an error if the current user does not have the admin role.
sec:collection-add-permissions Add the permissions $permissions to the protected collection identified by $uri.
sec:collection-get-permissions Returns a sequence of permission elements corresponding to the current permissions granted to the protected collection identified by $uri.
sec:collection-remove-permissions Removes the permissions $permissions from the protected collection identified by $uri.
sec:collection-set-permissions Sets the permissions of a protected collection identified by $uri to $permissions.
sec:collections-collection Returns a string corresponding to the uri for the protected collections collection.
sec:compartment-get-roles This function returns a list of roles in the specifed compartment.
sec:create-amp Creates a new amp in the system database for the context database.
sec:create-privilege Creates a new privilege and returns the new privilege-id.
sec:create-role Creates a new role in the system database for the context database.
sec:create-user Creates a new user in the system database for the context database.
sec:create-user-with-role Creates a new user in the system database for the context database.
sec:get-amp Returns an sec:amp element corresponding to an amp identified by ($namespace, $local-name, $document-uri).
sec:get-collection Gets the security document corresponding to a protected collection with uri equal to $uri.
sec:get-compartments This function returns a list of all of the compartments.
sec:get-distinct-permissions Returns a sequence of permission elements made up of a concatenation of $output-perms and the distinct permission elements of $input-perms.
sec:get-privilege Returns a sec:privilege element corresponding to a privilege identified by ($action,$kind).
sec:get-role-ids Returns a sequence of unique sec:role-id elements that corresponds to the sequence of role names $role-names.
sec:get-role-names Returns sequence of unique sec:role-name's that corresponds to the sequence of role IDs $role-ids.
sec:get-user-names Returns sequence of unique sec:user-name's that corresponds to the sequence of user IDs $user-ids.
sec:priv-doc-collections Returns a sequence of strings corresponding to the collection uri's that privileges belong to.
sec:priv-doc-permissions Returns a sequence of permission elements that all newly created privilege documents receive.
sec:privilege-add-roles Adds the roles ($role-names) to the list of roles assigned to the privilege ($action,$kind).
sec:privilege-exists This function returns true if the specified privilege exists.
sec:privilege-get-roles Returns a sequence of role names for the roles assigned to the privilege ($action,$kind).
sec:privilege-remove-roles Removes roles ($role-names) from the roles assigned to the privilege ($action,$kind).
sec:privilege-set-name Changes the sec:privilege-name of a sec:privilege to $new-privilege-name.
sec:privilege-set-roles Assigns the privilege ($action,$kind) to have the roles identified by $role-names.
sec:privileges-collection Returns a string corresponding to the uri for the privileges collection.
sec:protect-collection Protects a collection $uri with the given permissions ($permissions).
sec:remove-amp Removes the amp ($namespace, $local-name, $document-uri, $database) and returns true after completion.
sec:remove-privilege Removes the privilege identified by ($action,$kind).
sec:remove-role Removes the role ($role-name).
sec:remove-role-from-amps Removes references to the role ($role-name) from all amps.
sec:remove-role-from-privileges Removes references to the role ($role-name) from all privileges.
sec:remove-role-from-roles Removes references to the role ($role-name) from all other roles.
sec:remove-role-from-users Removes references to the role ($role-name) from all users.
sec:remove-user Removes the user with name $user-name.
sec:role-add-roles Adds new roles ($new-roles) to the role specified by $role-name.
sec:role-doc-collections Returns a sequence of strings corresponding to the collection uri's that roles belong to.
sec:role-doc-permissions Returns a sequence of permission elements that all newly created role documents receive.
sec:role-exists This function returns true if the specified role exists in the security database.
sec:role-get-compartment This function returns the compartment for the specified role.
sec:role-get-default-collections Returns a sequence of strings correspondinig to the uri's of the role's default collections.
sec:role-get-default-permissions Returns a sequence of permission elements correspondinig to the role's default permissions.
sec:role-get-description Returns the description for the specified role.
sec:role-get-roles Returns a sequence of role names for the roles directly assigned to the given role ($role-name).
sec:role-privileges Returns a set of privilege elements corresponding to all privileges that a role has.
sec:role-remove-roles Removes the roles ($role-names) from the set of roles included by the role ($role-name).
sec:role-set-default-collections Sets the default collections of a role with name $role-name to $collections.
sec:role-set-default-permissions Sets the default permissions for a role with name $role-name.
sec:role-set-description Changes the description of the role identified by $role-name to $description.
sec:role-set-name Changes the sec:role-name of a role from $role-name to $new-role-name.
sec:role-set-roles Assigns roles (named $role-names) to be the set of included roles for the role ($role-name).
sec:roles-collection Returns a string corresponding to the uri for the roles collection.
sec:security-collection Returns a string corresponding to the uri for the Security collection.
sec:security-installed Returns fn:true() if security has been installed on the current database.
sec:security-namespace Returns a string corresponding to the uri of the security namespace.
sec:security-version Returns the current version of the security database.
sec:set-realm Changes the realm of this security database to $realm.
sec:uid-for-name Returns the uids for the named user or () if no such user exists.
sec:unprotect-collection Removes the protection of a collection $uri.
sec:user-add-roles Adds the roles ($role-names) to the list of roles granted to the user ($user-name).
sec:user-doc-collections Returns a sequence of strings corresponding to the collection uri's that users belong to.
sec:user-doc-permissions Returns a sequence of permission elements that all newly created user documents receive.
sec:user-exists This function returns true if the specified user exists in the security database.
sec:user-get-default-collections Returns a sequence of strings correspondinig to the uri's of the user's default collections.
sec:user-get-default-permissions Returns a sequence of permission elements correspondinig to the user's default permissions.
sec:user-get-description Returns the user's description.
sec:user-get-password-extra This function returns the extra information for the specified user.
sec:user-get-roles Returns a sequence of role names for the roles directly assigned to the user ($user-name).
sec:user-privileges Returns a set of privilege elements corresponding to all privileges that a user has.
sec:user-remove-roles Removes the roles ($role-names) from the list of roles granted to the user ($user-name).
sec:user-set-default-collections Sets the default collections of a user with name $user-name to $collections.
sec:user-set-default-permissions Sets the default permissions for a user with name $user-name.
sec:user-set-description Changes the description of the user identified by $user-name to $description.
sec:user-set-name Changes the name of the user from $user-name to $new-user-name.
sec:user-set-password Changes the password for the user identified by $user-name to $password.
sec:user-set-password-extra This function sets extra information for the specified user.
sec:user-set-roles Assigns the user with name $user-name to have the roles identified by $role-names.
sec:users-collection Returns a string corresponding to the uri for the users collection.
sec:validate-permissions This function throws the SEC_NOPERMCAP exception if a permission has no capability specified and it throws the SEC-NOPERMROLEID exception if there is no role specified in the permission.
Function Detail
sec:amp-add-roles(
$namespace as xs:string,
$local-name as xs:string,
$document-uri as xs:string,
$database as xs:unsignedLong,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Adds the roles ($role-names) to the list of roles granted to the amp ($namespace, $local-name, $document-uri).

Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify xs:unsignedLong(0).
$role-names : Roles that should be temporarily assumed while the amp is in effect.

Required Privilege:

http://marklogic.com/xdmp/privileges/amp-add-roles
and for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

If an amp with the given identifiers ($namespace, $local-name, $document-uri) is not found, an error is returned.

If one of $role-names does not correspond to an existing role, an error is returned.

If the current user is limited to granting only his/her roles, and $role is not a subset of the current user's roles, then an error is returned.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:amp-add-roles(
    "http://marklogic.com/my_modules/myspace",
    "my-amp",
    "/MarkLogic/MyModule.xqy",
    0,
    "Contractor")

(: Adds the "Contractor" role to the list of roles granted to the "my-amp" amp. :)
sec:amp-doc-collections(  ) as  xs:string*
Summary:

Returns a sequence of strings corresponding to the collection uri's that amps belong to.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:amp-doc-collections()

=>

http://marklogic.com/xdmp/security
http://marklogic.com/xdmp/amps
sec:amp-doc-permissions(  ) as  element(sec:permission)*
Summary:

Returns a sequence of permission elements that all newly created amp documents receive.

sec:amp-exists(
$namespace as xs:string,
$local-name as xs:string,
$document-uri as xs:string,
$database as xs:unsignedLong
)  as   xs:boolean
Summary:

This function returns true if the specified amp exists in the security database.

Parameters:
$namespace : The namespace for the amped function.
$local-name : The local-name of the amped function.
$document-uri : The URI of the module containing the amped function.
$database : The database ID of the module containing the amped function.

Usage Notes:

This function must be executed against the security database.
Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

   sec:amp-exists("my/namespace/uri", "my-function", "/my/module.xqy",
      xdmp:database("my-database"))
sec:amp-get-roles(
$namespace as xs:string,
$local-name as xs:string,
$document-uri as xs:string,
$database as xs:unsignedLong
)  as   xs:string*
Summary:

Returns a sequence of role names for the roles directly assigned to the amp ($namespace, $local-name, $document-uri).

Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify xs:unsignedLong(0).

Required Privilege:

http://marklogic.com/xdmp/privileges/amp-get-roles
Usage Notes:

If an amp is not found with the given identifiers, an error is returned.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
 
sec:amp-get-roles(
    "http://marklogic.com/my_modules/myspace",
    "my-amp",
    "/MarkLogic/MyModule.xqy",
    0)
=>

Contractor
Developer
Temporary
sec:amp-remove-roles(
$namespace as xs:string,
$local-name as xs:string,
$document-uri as xs:string,
$database as xs:unsignedLong,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Removes a role ($role-name) from the set of roles included by the amp ($namespace, $local-name, $document-uri).

Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify xs:unsignedLong(0).
$role-names : Roles that should be temporarily assumed while the amp is in effect.

Required Privilege:

http://marklogic.com/xdmp/privileges/amp-remove-roles
and for role removal:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

If one of $role-names does not correspond to an existing role, an error is returned.

If an amp idnetified by ($namespace, $local-name, $document-uri) is not found then an error is returned.

If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
  
sec:amp-remove-roles(
    "http://marklogic.com/my_modules/myspace",
    "my-amp",
    "/MarkLogic/MyModule.xqy",
    0,
    "Developer")

(: Removes the "Developer" role from the list of roles granted to the "my-amp" amp. :)
sec:amp-set-roles(
$namespace as xs:string,
$local-name as xs:string,
$document-uri as xs:string,
$database as xs:unsignedLong,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Assigns the amp identified by $namespace, $local-name and $document-uri to have the roles identified by $roles-names. Removes previously assigned roles.

If an amp with the given identifiers does not exist, an error is returned.

If a role name in $role-names does not correspond to an existing role, an error is returned.

If $role-names is the empty sequence, all roles assigned to the amp are removed.

If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.

Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify xs:unsignedLong(0).
$role-names : Roles that should be temporarily assumed while the amp is in effect.

Required Privilege:

http://marklogic.com/xdmp/privileges/amp-set-roles
and for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:amp-set-roles(
    "http://marklogic.com/my_modules/myspace",
    "my-amp",
    "/MarkLogic/MyModule.xqy",
    0,
    ("Developer", "Temporary"))
 
(: Sets the "Developer" and "Temporary" rolea as the roles granted to the "my-amp" amp. 
   Any other roles previously in the list are removed. :)
sec:amps-collection(  ) as  xs:string
Summary:

Returns a string corresponding to the uri for the amps collection.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:amps-collection( )

=>

http://marklogic.com/xdmp/amps
sec:check-admin(  ) as  empty-sequence()
Summary:

Throws an error if the current user does not have the admin role.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";

import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:check-admin()

=>  [0.9-ml] SEC-NOADMIN: User does not have admin role.
sec:collection-add-permissions(
$uri as xs:string,
$permissions as element(sec:permission)*
)  as   empty-sequence()
Summary:

Add the permissions $permissions to the protected collection identified by $uri.

Parameters:
$uri : The URI of a collection.
$permissions : New permissions to add to that protected collection. If $permissions is the empty sequence, the function will have no effect.

Required Privilege:

http://marklogic.com/xdmp/privileges/collection-add-permissions

Usage Notes:

If a protected collection with uri equal to $uri is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:collection-add-permissions("http://marklogic.com/dev_modules",
                               (xdmp:permission("Developer", "insert")))

(: Adds the Developer(insert) permission to the "dev_modules" collection. :)
sec:collection-get-permissions(
$uri as xs:string
)  as   element(sec:permission)*
Summary:

Returns a sequence of permission elements corresponding to the current permissions granted to the protected collection identified by $uri.

Parameters:
$uri : The URI of a collection.

Required Privilege:

http://marklogic.com/xdmp/privileges/collection-get-permissions

Usage Notes:

If a protected collection with uri equal to $uri is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";
  
sec:collection-get-permissions("http://marklogic.com/dev_modules")

=>
 
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:capability>read</sec:capability>
  <sec:role-id>5444982746628127945</sec:role-id>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:capability>insert</sec:capability>
  <sec:role-id>5444982746628127945</sec:role-id>
</sec:permission>
sec:collection-remove-permissions(
$uri as xs:string,
$permissions as element(sec:permission)*
)  as   empty-sequence()
Summary:

Removes the permissions $permissions from the protected collection identified by $uri.

Parameters:
$uri : The URI of a collection.
$permissions : Permissions to be removed from that protected collection. If $permissions is the empty sequence, the function will have no effect.

Required Privilege:

http://marklogic.com/xdmp/privileges/collection-remove-permissions

Usage Notes:

If a protected collection with uri equal to $uri is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";
 
sec:collection-remove-permissions("http://marklogic.com/dev_modules",
                                  (xdmp:permission("Developer", "update")))
  
(: Removes the Developer(update) permission from the "dev_modules" collection. :)
sec:collection-set-permissions(
$uri as xs:string,
$permissions as element(sec:permission)*
)  as   empty-sequence()
Summary:

Sets the permissions of a protected collection identified by $uri to $permissions.

Parameters:
$uri : The URI of a collection.
$permissions : New permissions. If the empty sequence is provided, deletes the existing permissions.

Required Privilege:

http://marklogic.com/xdmp/privileges/collection-set-permissions

Usage Notes:

If a protected collection with uri equal to $uri is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:collection-set-permissions("http://marklogic.com/dev_modules",
                               (xdmp:permission("Developer", "read"), 
                                xdmp:permission("Developer", "update")))

(: Sets the permissions on "dev_modules" to Developer(read) and Developer(update).
   Any previous permissions on the collection are removed. :)
sec:collections-collection(  ) as  xs:string
Summary:

Returns a string corresponding to the uri for the protected collections collection.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
 
sec:collections-collection( )

=>

http://marklogic.com/xdmp/collections
sec:compartment-get-roles(
$compartment-name as xs:string
)  as   element(sec:role)*
Summary:

This function returns a list of roles in the specifed compartment.

Parameters:
$compartment-name : The name of the compartment.

Required Privilege:

http://marklogic.com/xdmp/privileges/compartment-get-roles

Usage Notes:

This function must be executed against the security database.
Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

  sec:compartment-get-roles("my-compartment")
sec:create-amp(
$namespace as xs:string,
$local-name as xs:string,
$document-uri as xs:string,
$database as xs:unsignedLong,
$role-names as xs:string*
)  as   xs:unsignedLong
Summary:

Creates a new amp in the system database for the context database.

If the tuple ($namespace, $local-name, $document-uri, $database) is not unique, an error is returned.

If one of the $role-names does not identify a role, an error is returned.

If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.

Returns the amp-id.
Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the module in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify xs:unsignedLong(0).
$role-names : Roles that should be temporarily assumed while the amp is in effect.

Required Privilege:

http://marklogic.com/xdmp/privileges/create-amp
and for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
 
sec:create-amp(
    "http://marklogic.com/my_modules/myspace",
    "my-amp",
    "/MarkLogic/MyModule.xqy",
    0,
    "Developer")
    
 (: Creates an amp for the function "my-amp" in the MyModule.xqy module that
    temporarily grants users the "Developer" role. :)
sec:create-privilege(
$privilege-name as xs:string,
$action as xs:string,
$kind as xs:string,
$role-names as xs:string*
)  as   xs:unsignedLong
Summary:

Creates a new privilege and returns the new privilege-id.

For execute privileges, the privilege is initially nothing more than a name. Use the xdmp:security-assert() function in your code to associate the privilege with a protected operation.

For URI privleges, the $action parameter identifies the base URI to be protected. Users must have this privilege to access any of the documents or code under the specified URI.

If $action is not unique, an error is returned.

If $kind is not one of ("execute", "uri") then en error is returned.

If one of the $role-names names a role that does not exist, an error is returned.

If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.

Parameters:
$privilege-name : The name of the privilege to create (unique within security database).
$action : Action protected by this privilege. For an Execute Privilege, this is usually a URI describing an activity. For a URI Privilege, this is a base URI used to filter database activities with certain document URIs.
$kind : Either "execute" or "uri".
$role-names : The names of the roles which can perform this action.

Required Privilege:

http://marklogic.com/xdmp/privileges/create-privilege
and for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:create-privilege("mypriv", 
                     "http://marklogic.com/xdmp/privileges/mypriv", 
                     "execute", 
                     "Developer")

(: Creates an execute privilege, named "mypriv," and assigns it to the
   "Developer" role. :)
sec:create-role(
$role-name as xs:string,
$description as xs:string?,
$role-names as xs:string*,
$permissions as element(sec:permission)*,
$collections as xs:string*,
[$compartment as xs:string?]
)  as   xs:unsignedLong
Summary:

Creates a new role in the system database for the context database.

If $role-name is not unique, an error is returned.

If one of the $role-names does not identify a role, an error is returned.

If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.

Returns the role-id.

Parameters:
$role-name : The name of the role to be created.
$description : A description of the role to be created.
$role-names : A sequence of role names to which the role is assigned.
$permissions : The default permissions for the role.
$collections : The default collections for the role.
$compartment (optional): The compartment to assign to the role.

Required Privilege:

http://marklogic.com/xdmp/privileges/create-role
and for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:create-role(
    "Temporary",
    "Temporary worker access",
    ("filesystem-access"),
    (),
    ("testDocument"))
   
(: Creates a new role, named "Temporary," with the default collection, 
   named testDocument. :)
sec:create-user(
$user-name as xs:string,
$description as xs:string?,
$password as xs:string,
$role-names as xs:string*,
$permissions as element(sec:permission)*,
$collections as xs:string*
)  as   xs:unsignedLong
Summary:

Creates a new user in the system database for the context database. Returns the user ID of the created user.

Parameters:
$user-name : A unique username. If $user-name is not unique, an error is returned.
$description : A description of the user.
$password : The initial password for this user.
$role-names : The roles (if any) assigned to this user. If one of the $role-names names a role that does not exist, an error is returned.
$permissions : The default permissions granted to this user.
$collections : The URIs for the default collections to which this user has access.

Required Privilege:

http://marklogic.com/xdmp/privileges/create-user
and, for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:create-user(
    "Jim",
    "Jim the temp",
    "newtemp",
    "Temporary",
    (xdmp:permission("security", "read")),
    ("http://marklogic.com/dev_modules"))
 
 (: Creates a new user, named "Jim," with the role, "Temporary."  "Jim" 
    is assigned the default permission, security(read), and the default 
    collection, "http://marklogic.com/dev_modules". :)
sec:create-user-with-role(
$user-name as xs:string,
$description as xs:string?,
$password as xs:string,
$role-names as xs:string*,
$permissions as element(sec:permission)*,
$collections as xs:string*
)  as   xs:unsignedLong
Summary:

Creates a new user in the system database for the context database. Returns the user ID of the created user. Also creates a role by the same name and assigns the newly-created user to the newly-created role. Parameters that define roles, permissions, and collections are only applied to the new user.

Parameters:
$user-name : A unique username. If $user-name is not unique, an error is returned.
$description : A description of the user.
$password : The initial password for this user.
$role-names : Additional roles (if any) assigned to this user. If one of the $role-names names a role that does not exist, an error is returned.
$permissions : The default permissions granted to this user.
$collections : The URIs for the default collections to which this user has access.

Required Privilege:

http://marklogic.com/xdmp/privileges/create-user
http://marklogic.com/xdmp/privileges/create-role
and, for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:create-user-with-role(
    "Jim",
    "Jim the temp",
    "newtemp",
    "Temporary",
    (xdmp:permission("security", "read"),
     xdmp:permission("security", "update")),
    ("http://marklogic.com/dev_modules"))
 
(: Creates a new user, named Jim, with the roles, Jim and Temporary.  
   Jim is assigned the default permissions, security(read) and security(update),
   and the default collection, "http://marklogic.com/dev_modules". :)
sec:get-amp(
$namespace as xs:string,
$local-name as xs:string,
$document-uri as xs:string,
$database as xs:unsignedLong
)  as   element(sec:amp)?
Summary:

Returns an sec:amp element corresponding to an amp identified by ($namespace, $local-name, $document-uri). If no such amp is found, an error is returned.

Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify xs:unsignedLong(0).

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:get-amp(
    "http://marklogic.com/xdmp/alert",
    "action-insert",
    "/MarkLogic/alert.xqy",
    0) 
=>

<sec:amp xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:amp-id>2840630016131588040</sec:amp-id>
  <sec:namespace>http://marklogic.com/xdmp/alert</sec:namespace>
  <sec:local-name>action-insert</sec:local-name>
  <sec:document-uri>/MarkLogic/alert.xqy</sec:document-uri>
  <sec:database>0</sec:database>
  <sec:role-ids>
    <sec:role-id>4235709426772438321</sec:role-id>
  </sec:role-ids>
</sec:amp>
sec:get-collection(
$uri as xs:string
)  as   element(sec:collection)
Summary:

Gets the security document corresponding to a protected collection with uri equal to $uri.

Parameters:
$uri : The URI of a collection.

Required Privilege:

http://marklogic.com/xdmp/privileges/unprotect-collection or
http://marklogic.com/xdmp/privileges/collection-set-permissions or
http://marklogic.com/xdmp/privileges/collection-add-permissions or
http://marklogic.com/xdmp/privileges/collection-remove-permissions

Usage Notes:

If a protected collection with uri equal to $uri is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";
 
sec:get-collection("http://marklogic.com/cpf/domains")

=>
  
<sec:collection xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:collection-id>403495114666638078</sec:collection-id>
  <sec:uri>http://marklogic.com/cpf/domains</sec:uri>
</sec:collection>
sec:get-compartments(  ) as  xs:string*
Summary:

This function returns a list of all of the compartments.

Required Privilege:

http://marklogic.com/xdmp/privileges/get-compartments

Usage Notes:

This function must be executed against the security database.
Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

  sec:get-compartments()
sec:get-distinct-permissions(
$input-perms as element(sec:permission)*,
$output-perms as element(sec:permission)*
)  as   element(sec:permission)*
Summary:

Returns a sequence of permission elements made up of a concatenation of $output-perms and the distinct permission elements of $input-perms.

Parameters:
$input-perms : The input permissions.
$output-perms : The output permissions. This is typically an empty sequence.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
 
sec:get-distinct-permissions(
    (xdmp:permission("security", "read"), 
     xdmp:permission("security", "update")),
     ())
=>

<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:capability>update</sec:capability>
  <sec:role-id>16363340809666818373</sec:role-id>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:capability>read</sec:capability>
  <sec:role-id>16363340809666818373</sec:role-id>
</sec:permission>
sec:get-privilege(
$action as xs:string,
$kind as xs:string
)  as   element(sec:privilege)?
Summary:

Returns a sec:privilege element corresponding to a privilege identified by ($action,$kind). If no such privilege is found, an error is returned.

Parameters:
$action : Action protected by this privilege. For an Execute Privilege, this is usually a URI describing an activity. For a URI Privilege, this is a base URI used to filter database activities with certain document URIs.
$kind : Either "execute" or "uri".

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:get-privilege(
    "http://marklogic.com/xdmp/privileges/admin-module-read",
    "execute")

=>

<sec:privilege xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:privilege-id>17293336516617295309</sec:privilege-id>
  <sec:privilege-name>admin-module-read</sec:privilege-name>
  <sec:action>http://marklogic.com/xdmp/privileges/admin-module-read</sec:action>
  <sec:role-ids>
    <sec:role-id>5444982746628127945</sec:role-id>
    <sec:role-id>6629014463670416824</sec:role-id>
  </sec:role-ids>
  <sec:kind>execute</sec:kind>
</sec:privilege>
sec:get-role-ids(
[$role-names as xs:string*]
)  as   element(sec:role-id)*
Summary:

Returns a sequence of unique sec:role-id elements that corresponds to the sequence of role names $role-names.

Duplicate names return a single ID.

If $role-names is omitted, returns all of the sec:role-id elements in the database.

If a role name in $role-names does not correspond to an existing role, an error is returned.
Parameters:
$role-names (optional): A sequence of role names. If omitted, returns all of the sec:role-id elements in the database.

Required Privilege:

http://marklogic.com/xdmp/privileges/get-role-ids

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
   "/MarkLogic/security.xqy";
   
sec:get-role-ids(("writer", "editor"))

=>

<sec:role-id xmlns:sec="http://marklogic.com/xdmp/security">6629014463670416824</sec:role-id>
<sec:role-id xmlns:sec="http://marklogic.com/xdmp/security">6615337390848046012</sec:role-id>
sec:get-role-names(
$role-ids as xs:unsignedLong*
)  as   element(sec:role-name)*
Summary:

Returns sequence of unique sec:role-name's that corresponds to the sequence of role IDs $role-ids. Duplicate IDs return a single name.

Parameters:
$role-ids : A sequence of role IDs.

Required Privilege:

http://marklogic.com/xdmp/privileges/get-role-names

Usage Notes:

If a role ID in $role-ids does not correspond to an existing role, an error is returned.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:get-role-names((6629014463670416824, 
  	             6615337390848046012)) 
=>

<sec:role-name xmlns:sec="http://marklogic.com/xdmp/security">editor</sec:role-name>
<sec:role-name xmlns:sec="http://marklogic.com/xdmp/security">writer</sec:role-name>
sec:get-user-names(
$user-ids as xs:unsignedLong*
)  as   element(sec:user-name)*
Summary:

Returns sequence of unique sec:user-name's that corresponds to the sequence of user IDs $user-ids. Duplicate IDs return a single name.

Parameters:
$user-ids : A sequence of user IDs.

Required Privilege:

http://marklogic.com/xdmp/privileges/get-user-names

Usage Notes:

If a user ID in $user-ids does not correspond to an existing user, an error is returned.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
   "/MarkLogic/security.xqy";

sec:get-user-names((18325468190304151823, 
                    5673246250406350379, 
                    11765239768744971597))

=> 

<sec:user-name xmlns:sec="http://marklogic.com/xdmp/security">Jim</sec:user-name>
<sec:user-name xmlns:sec="http://marklogic.com/xdmp/security">Sue</sec:user-name>
<sec:user-name xmlns:sec="http://marklogic.com/xdmp/security">Tom</sec:user-name>
sec:priv-doc-collections(  ) as  xs:string*
Summary:

Returns a sequence of strings corresponding to the collection uri's that privileges belong to.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:priv-doc-collections()

=>

http://marklogic.com/xdmp/security
http://marklogic.com/xdmp/privileges
sec:priv-doc-permissions(  ) as  element(sec:permission)*
Summary:

Returns a sequence of permission elements that all newly created privilege documents receive.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:priv-doc-permissions()

=>

<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>read</sec:capability>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>update</sec:capability>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>insert</sec:capability>
</sec:permission>
sec:privilege-add-roles(
$action as xs:string,
$kind as xs:string,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Adds the roles ($role-names) to the list of roles assigned to the privilege ($action,$kind).

If a privilege identified by ($action,$kind) is not found, an error is returned.

If one of $role-names does not correspond to an existing role, an error is returned.

If the current user is limited to granting only his/her roles, and $role is not a subset of the current user's roles, then an error is returned.

Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
$role-names : Additional roles for the privilege. If $role-names is the empty sequence, the function has no effect.

Required Privilege:

http://marklogic.com/xdmp/privileges/privilege-add-roles
and for role assignment: http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:privilege-add-roles(
    "http://marklogic.com/xdmp/privileges/unprotected-collections",
    "execute",
    ("Temporary"))
   
(: Adds the unprotected-collection execute privilege to the Temporary role. :)
sec:privilege-exists(
$action as xs:string,
$kind as xs:string
)  as   xs:boolean
Summary:

This function returns true if the specified privilege exists.

Parameters:
$action : The URI of the privilege.
$kind : The kind of privilege: "execute" or uri".

Required Privilege:

http://marklogic.com/xdmp/privileges/get-privilege

Usage Notes:

This function must be executed against the security database.
Example: 
xquery version "1.0-ml"; 

(: execute this against the security database :)
import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

sec:privilege-exists("http://marklogic.com/xdmp/privileges/get-privilege",
      "execute")
sec:privilege-get-roles(
$action as xs:string,
$kind as xs:string
)  as   xs:string*
Summary:

Returns a sequence of role names for the roles assigned to the privilege ($action,$kind).

If a privilege with action equal to $action is not found, an error is returned.

Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".

Required Privilege:

http://marklogic.com/xdmp/privileges/privilege-get-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:privilege-get-roles(
    "http://marklogic.com/xdmp/privileges/create-role", 
     "execute")
=>

security
sec:privilege-remove-roles(
$action as xs:string,
$kind as xs:string,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Removes roles ($role-names) from the roles assigned to the privilege ($action,$kind).

If a privilege identified by ($action,$kind) is not found, an error is returned.

If one of $role-names does not correspond to an existing role, an error is returned.

If the current user is limited to granting only his/her roles, and $role is not a subset of the current user's roles, then an error is returned.

Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
$role-names : Additional roles for the privilege. If $role-names is the empty sequence, the function has no effect.

Required Privilege:

http://marklogic.com/xdmp/privileges/privilege-remove-roles
and for role removal:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
 
sec:privilege-remove-roles(
    "http://marklogic.com/xdmp/privileges/mypriv", 
    "execute", "Contractor")
  
(: Removes the specified privilege from the "Contractor" role. :)
sec:privilege-set-name(
$action as xs:string,
$kind as xs:string,
$new-privilege-name as xs:string
)  as   empty-sequence()
Summary:

Changes the sec:privilege-name of a sec:privilege to $new-privilege-name.

If a privilege with the given $action and $kind is not found, an error is returned.

If $new-privilege-name is not unique, an error is returned.

Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
$new-privilege-name : The new name for the privilege.

Required Privilege:

http://marklogic.com/xdmp/privileges/privilege-set-name

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:privilege-set-name(
    "http://marklogic.com/xdmp/privileges/mypriv", 
    "execute", 
    "new_name")

(: Renames the execute privilege with the specified action to "new_name." :)
sec:privilege-set-roles(
$action as xs:string,
$kind as xs:string,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Assigns the privilege ($action,$kind) to have the roles identified by $role-names. Removes the prviously assigned roles.

If a privilege identified by ($action,$kind) is not found, an error is returned.

If a role name in $role-names does not correspond to an existing role, an error is returned.

If $role-names is the empty sequence, all existing roles for the privilege are removed.

If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.

Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
$role-names : New roles that can perform this action. All previously assigned roles will be removed. If $role-names is the empty sequence, the privilege will have no roles assigned.

Required Privilege:

http://marklogic.com/xdmp/privileges/privilege-set-roles
and for role assignment ($role-names not empty sequence):
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
 
sec:privilege-set-roles(
    "http://marklogic.com/xdmp/privileges/mypriv", 
     "execute", "Contractor")

(: Assigns the privilege with the specified action to the "Contractor" role.
   The privilege is removed from any other roles that had previously been  
   assigned the privilege. :)
sec:privileges-collection(  ) as  xs:string
Summary:

Returns a string corresponding to the uri for the privileges collection.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:privileges-collection( )

=>

http://marklogic.com/xdmp/privileges
sec:protect-collection(
$uri as xs:string,
$permissions as element(sec:permission)*
)  as   xs:unsignedLong
Summary:

Protects a collection $uri with the given permissions ($permissions). Returns the unique id of the protected collection. If the protected collection at the specified URI does not exist, it is created.

Parameters:
$uri : The URI of a collection.
$permissions : Permissions governing the collection.

Required Privilege:

http://marklogic.com/xdmp/privileges/protect-collection

Usage Notes:

If $uri is empty or can not be cast as an xs:AnyURI, an error is raised.

If a collection with the same uri is already protected, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:protect-collection("http://marklogic.com/dev_modules", 
                       (xdmp:permission("Developer", "read"), 
                        xdmp:permission("Developer", "insert"))) 

(: Users with the "Developer" role can read and insert files in "dev_modules." :)
sec:remove-amp(
$namespace as xs:string,
$local-name as xs:string,
$document-uri as xs:string,
$database as xs:unsignedLong
)  as   empty-sequence()
Summary:

Removes the amp ($namespace, $local-name, $document-uri, $database) and returns true after completion.

Parameters:
$namespace : The namespace of the function to which the amp applies.
$local-name : The name of the function to which the amp applies.
$document-uri : The URI of the module in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify xs:unsignedLong(0).

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-amp

Usage Notes:

If an amp ($namespace, $local-name, $document-uri) is not found, an error is returned.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:remove-amp(
    "http://marklogic.com/my_modules/myspace",
    "my-amp",
    "/MarkLogic/MyModule.xqy",
    0)
   
(: Removes the "my-amp" amp. :)
sec:remove-privilege(
$action as xs:string,
$kind as xs:string
)  as   empty-sequence()
Summary:

Removes the privilege identified by ($action,$kind).

If a privilege identified by ($action,$kind) is not found, an error is returned.

Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-privilege

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
  
sec:remove-privilege(
    "http://marklogic.com/xdmp/privileges/mypriv", 
    "execute")
 
(: Removes the execute privilege with the specified action. :)
sec:remove-role(
$role-name as xs:string
)  as   empty-sequence()
Summary:

Removes the role ($role-name).

If a role with name equal to $role-name is not found, an error is returned.

This function also removes all references to the role (privileges, amps, permissions and users).

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-role

Usage Notes:

This function must be executed against the security database.
Example: 
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:remove-role("Temporary")
 
(: Removes the role, named Temporary. :)
sec:remove-role-from-amps(
$role-name as xs:string
)  as   empty-sequence()
Summary:

Removes references to the role ($role-name) from all amps.

If a role with name equal to $role-name is not found, an error is returned.

If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-role-from-amps
and for role removal:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:remove-role-from-amps("Developer")

(: Removes the "Developer" role from all amps. :)
sec:remove-role-from-privileges(
$role-name as xs:string
)  as   empty-sequence()
Summary:

Removes references to the role ($role-name) from all privileges.

If a role with name equal to $role-name is not found, an error is returned.

If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-role-from-privileges
and for role removal:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:remove-role-from-privileges("Developer")

(: Removes the "Developer" role from all privileges. :)
sec:remove-role-from-roles(
$role-name as xs:string
)  as   empty-sequence()
Summary:

Removes references to the role ($role-name) from all other roles.

If a role with name equal to $role-name is not found, an error is returned.

If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-role-from-users
and for role removal:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
  
sec:remove-role-from-roles("Developer")

(: Removes the "Developer" role from all other roles. :)
sec:remove-role-from-users(
$role-name as xs:string
)  as   empty-sequence()
Summary:

Removes references to the role ($role-name) from all users.

If a role with name equal to $role-name is not found, an error is returned.

If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-role-from-users
and for role removal:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:remove-role-from-users("Contractor")

(: Removes the "Contractor" role from all users. :)
sec:remove-user(
$user-name as xs:string
)  as   empty-sequence()
Summary:

Removes the user with name $user-name.

If a user with name equal to $user-name is not found, an error is returned.

Parameters:
$user-name : The name of a user.

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-user

Usage Notes:

This function must be executed against the security database.
Example: 
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:remove-user("Jim")
 
(: Removes the user, named Jim. :)
sec:role-add-roles(
$role-name as xs:string,
$new-roles as xs:string*
)  as   empty-sequence()
Summary:

Adds new roles ($new-roles) to the role specified by $role-name.

If a role with name equal to $role-name is not found, an error is returned.

If one of $new-roles does not correspond to an existing role, an error is returned.

If the current user is limited to granting only his/her roles, and $new-role is not a subset of the current user's roles, then an error is returned.

Parameters:
$role-name : The name of the role.
$new-roles : The roles to add to the role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-add-roles
and for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:role-add-roles("Contractor", "filesystem-access")

(: Adds the "filesystem-access" role to the "Contractor" role and leaves
   any previously assigned roles intact. :)
sec:role-doc-collections(  ) as  xs:string*
Summary:

Returns a sequence of strings corresponding to the collection uri's that roles belong to.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
 
sec:role-doc-collections()

=>

http://marklogic.com/xdmp/security
http://marklogic.com/xdmp/roles
sec:role-doc-permissions(  ) as  element(sec:permission)*
Summary:

Returns a sequence of permission elements that all newly created role documents receive.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
  
sec:role-doc-permissions()

=>

<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>read</sec:capability>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>update</sec:capability>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>insert</sec:capability>
</sec:permission>
sec:role-exists(
$role-name as xs:string
)  as   xs:boolean
Summary:

This function returns true if the specified role exists in the security database.

Parameters:
$role-name : The role name.

Required Privilege:

http://marklogic.com/xdmp/privileges/get-role

Usage Notes:

This function must be executed against the security database.
Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

  sec:role-exists("my-role")
sec:role-get-compartment(
$role-name as xs:string
)  as   xs:string?
Summary:

This function returns the compartment for the specified role.

Parameters:
$role-name : The name of the role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-get-compartment

Usage Notes:

This function must be executed against the security database.
Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

  sec:role-get-compartment("my-compartmented-role")
sec:role-get-default-collections(
$role-name as xs:string
)  as   xs:string*
Summary:

Returns a sequence of strings correspondinig to the uri's of the role's default collections.

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-get-default-collections

Usage Notes:

If a role with name $role-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:role-get-default-collections("Developer")

=>

http://marklogic.com/dev_modules
http://marklogic.com/dev_docs
sec:role-get-default-permissions(
$role-name as xs:string
)  as   element(sec:permission)*
Summary:

Returns a sequence of permission elements correspondinig to the role's default permissions.

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-get-default-permission

Usage Notes:

If a role with name $role-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:role-get-default-permissions("Developer")

=>

<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:capability>update</sec:capability>
  <sec:role-id>16363340809666818373</sec:role-id>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:capability>read</sec:capability>
  <sec:role-id>16363340809666818373</sec:role-id>
</sec:permission>
sec:role-get-description(
$role-name as xs:string
)  as   xs:string
Summary:

Returns the description for the specified role.

Parameters:
$role-name : The name of the role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-get-description

Usage Notes:

If a role with name equal to $role-name is not found, an error is returned.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:role-get-description("Developer")

=> Developer-level access
sec:role-get-roles(
$role-name as xs:string
)  as   xs:string*
Summary:

Returns a sequence of role names for the roles directly assigned to the given role ($role-name).

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-get-roles

Usage Notes:

If a role with name equal to $role-name is not found, an error is returned.

If a role is assigned to itself, the sequence returned from sec:role-get-roles does not include itself.

To find all of the roles this role inherits (that is, the roles assigned directly to this role, the roles assigned to those roles, and so on), use the xdmp:role-roles built-in function.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
 xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:role-get-roles("Developer")

=>

filesystem-access
pipeline-execution
sec:role-privileges(
$role-name as xs:string
)  as   element(sec:privilege)*
Summary:

Returns a set of privilege elements corresponding to all privileges that a role has. (Roles are flattened to give a complete set of privileges).

Parameters:
$role-name : The name of a role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-privileges if the current role is not $role-name.

Usage Notes:

If a role with name equal to $role-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";
 
sec:role-privileges("Developer")
  
=>

<sec:privilege xmlns:sec="http://marklogic.com/xdmp/security">
 <sec:privilege-id>12387631775818383068</sec:privilege-id>
  <sec:privilege-name>xdmp:save</sec:privilege-name>
  <sec:action>http://marklogic.com/xdmp/privileges/xdmp-save</sec:action>
  <sec:role-ids>
    <sec:role-id>13749738523688002780</sec:role-id>
  </sec:role-ids>
  <sec:kind>execute</sec:kind>
</sec:privilege>
(:  ..... and all other privileges assigned to "Developer." :)
sec:role-remove-roles(
$role-name as xs:string,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Removes the roles ($role-names) from the set of roles included by the role ($role-name).

If a role with name equal to $role-name is not found, an error is returned.

If one of $role-names does not correspond to an existing role, an error is returned.

If the current user is limited to granting only his/her roles, and $old-role is not a subset of the current user's roles, then an error is returned.

Parameters:
$role-name : The name of a role.
$role-names : The name of the roles to remove from the role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-remove-roles
and for role removal:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:role-remove-roles("Contractor", ("Developer", "alert-internal"))

(: Removes the "Developer" and "alert-internal" roles from the "Contractor" role. :)
sec:role-set-default-collections(
$role-name as xs:string,
$collections as xs:string*
)  as   empty-sequence()
Summary:

Sets the default collections of a role with name $role-name to $collections.

Parameters:
$role-name : The name of a role.
$collections : A sequence of collections.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-set-default-collections

Usage Notes:

If a role with name $role-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:role-set-default-collections("Developer", 
    ("http://marklogic.com/dev_modules", 
     "http://marklogic.com/dev_docs"))

(: Sets the default collections for the role, "Developer," to 
"http://marklogic.com/dev_modules" and "http://marklogic.com/dev_docs".
 Any other previously set collections are removed.
sec:role-set-default-permissions(
$role-name as xs:string,
$permissions as element(sec:permission)*
)  as   empty-sequence()
Summary:

Sets the default permissions for a role with name $role-name.

Parameters:
$role-name : The name of the role to which the default permissions are set.
$permissions : New permissions. If the empty sequence is provided, deletes the existing permissions.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-set-default-permissions

Usage Notes:

If a role with name $role-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:role-set-default-permissions(
    "Developer",
     (xdmp:permission("security", "read"), 
      xdmp:permission("security", "update")))

(: Sets the default permissions for the "Developer" role to security(read) and
   security(update). :)
sec:role-set-description(
$role-name as xs:string,
$description as xs:string
)  as   empty-sequence()
Summary:

Changes the description of the role identified by $role-name to $description.

Parameters:
$role-name : The name of the role.
$description : A description of the role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-set-description if the currrent role is not $role-name.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:role-set-description(
    "Developer",
    "Developer-level access")
  
(:  Changes the description of the role, "Developer." :)
sec:role-set-name(
$role-name as xs:string,
$new-role-name as xs:string
)  as   empty-sequence()
Summary:

Changes the sec:role-name of a role from $role-name to $new-role-name.

If $new-role-name is not unique, an error is returned.

Parameters:
$role-name : The name of the role to change.
$new-role-name : The new name for the role.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-set-name

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
 
sec:role-set-name("Temporary", "Contractor")  

(: Changes the name of the "Temporary" role to "Contractor."  :)
sec:role-set-roles(
$role-name as xs:string,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Assigns roles (named $role-names) to be the set of included roles for the role ($role-name). Removes previously assigned roles.

If a role with name equal to $role-name is not found, an error is returned.

If a role name in $role-names does not correspond to an existing role, an error is returned.

If $role-names is the empty sequence, all included roles for the role are removed.

If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.
Parameters:
$role-name : The name of a role.
$role-names : A sequence containing the names of roles to assign to $role-name.

Required Privilege:

http://marklogic.com/xdmp/privileges/role-set-roles
and for role assignment ($role-names not empty sequence):
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:role-set-roles("Contractor", ("Developer", "alert-internal"))

(: Assigns the "Developer" and "alert-internal" roles to the "Contractor" 
   role and removes any other roles previously assigned to "Contractor." :)
sec:roles-collection(  ) as  xs:string
Summary:

Returns a string corresponding to the uri for the roles collection.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
  
sec:roles-collection( )

=>

http://marklogic.com/xdmp/roles
sec:security-collection(  ) as  xs:string
Summary:

Returns a string corresponding to the uri for the Security collection.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:security-collection()

=>

http://marklogic.com/xdmp/security
sec:security-installed(  ) as  xs:boolean
Summary:

Returns fn:true() if security has been installed on the current database. Otherwise, returns false.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:security-installed()

=> true
sec:security-namespace(  ) as  xs:string
Summary:

Returns a string corresponding to the uri of the security namespace.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:security-namespace()

=>

http://marklogic.com/xdmp/security
sec:security-version(  ) as  xs:double
Summary:

Returns the current version of the security database.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";

import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:security-version()

=> 40100
sec:set-realm(
$realm as xs:string
)  as   empty-sequence()
Summary:

Changes the realm of this security database to $realm. If the realm is different from the old value this function also invalidates all the existing digest passwords since they will no longer work with the new realm. Warning: this invalidates all user's digest passwords, including the user running this function and users of the Admin Interface (if the Admin Interface is set to digest authentication, which is the default setting); once a user's digest password is invalidated, that user will no longer be able to log in with digest authentication.

Parameters:
$realm : The new realm name to which the security database name is changed.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:set-realm("public")

(: Sets the realm to "public." :)
sec:uid-for-name(
$name as xs:string
)  as   xs:unsignedLong*
Summary:

Returns the uids for the named user or () if no such user exists.

Parameters:
$name : The named user.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:uid-for-name("Jim")

=>

18325468190304151823
sec:unprotect-collection(
$uri as xs:string
)  as   empty-sequence()
Summary:

Removes the protection of a collection $uri. This does not remove the collection or any of its documents, but it does remove the protected collection from the security database.

Parameters:
$uri : The URI of the collection from which to remove protections.

Required Privilege:

http://marklogic.com/xdmp/privileges/unprotect-collection

Usage Notes:

If a protected collection with uri equal to $uri is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:unprotect-collection("http://marklogic.com/dev_modules")

(: Removes protection from the "dev_modules" collection. :)
sec:user-add-roles(
$user-name as xs:string,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Adds the roles ($role-names) to the list of roles granted to the user ($user-name).

If a user with name equal to $user-name is not found, an error is returned.

If one of the $role-names does not correspond to an existing role, an error is returned.

If the current user is limited to granting only his/her roles, and $role is not a subset of the current user's roles, then an error is returned.


Parameters:
$user-name : The name of a user.
$role-names : A sequence of role names.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-add-roles
and for role assignment:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:user-add-roles("Jim", ("merge", "alert-user"))

(:  Adds the roles, "merge" and "alert-user," to Jim's existing roles. :)
sec:user-doc-collections(  ) as  xs:string*
Summary:

Returns a sequence of strings corresponding to the collection uri's that users belong to.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
  
sec:user-doc-collections()

=>

http://marklogic.com/xdmp/security
http://marklogic.com/xdmp/users
sec:user-doc-permissions(  ) as  element(sec:permission)*
Summary:

Returns a sequence of permission elements that all newly created user documents receive.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
  
sec:user-doc-permissions()

=>

<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>read</sec:capability>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>update</sec:capability>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:role-id>16363340809666818373</sec:role-id>
  <sec:capability>insert</sec:capability>
</sec:permission>
sec:user-exists(
$user-name as xs:string
)  as   xs:boolean
Summary:

This function returns true if the specified user exists in the security database.

Parameters:
$user-name : The user name.

Required Privilege:

http://marklogic.com/xdmp/privileges/get-user

Usage Notes:

This function must be executed against the security database.
Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

  sec:user-exists("my-user")
sec:user-get-default-collections(
$user-name as xs:string
)  as   xs:string*
Summary:

Returns a sequence of strings correspondinig to the uri's of the user's default collections.

Parameters:
$user-name : The name of a user.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-get-default-collections

Usage Notes:

If a user with name $user-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:user-get-default-collections("Jim")

=>

http://marklogic.com/jims_modules
http://marklogic.com/jims_docs
sec:user-get-default-permissions(
$user-name as xs:string
)  as   element(sec:permission)*
Summary:

Returns a sequence of permission elements correspondinig to the user's default permissions.

Parameters:
$user-name : The name of a user.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-get-default-permission

Usage Notes:

If a user with name $user-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:user-get-default-permissions("Jim")

=>

<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:capability>update</sec:capability>
  <sec:role-id>16363340809666818373</sec:role-id>
</sec:permission>
<sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
  <sec:capability>read</sec:capability>
  <sec:role-id>16363340809666818373</sec:role-id>
</sec:permission>
sec:user-get-description(
$user-name as xs:string
)  as   xs:string
Summary:

Returns the user's description. If a user with name equal to $user-name is not found, an error is returned.

Parameters:
$user-name : The name of a user.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-get-description
or the current user is the same as the $user-name.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:user-get-description("Jim")

=>

Jim the temp
sec:user-get-password-extra(
$user-name as xs:string
)  as   element(sec:password-extra)?
Summary:

This function returns the extra information for the specified user. If the user does not exist, an exception is thrown.

Parameters:
$user-name : The name of the user for whom to return the extra information.

Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

  sec:user-get-password-extra("Jim")

  (: Returns the extra information for the user, Jim. :)
sec:user-get-roles(
$user-name as xs:string
)  as   xs:string*
Summary:

Returns a sequence of role names for the roles directly assigned to the user ($user-name). Does not flatten the roles to include "inherited roles."

If a user with name equal to $user-name is not found, an error is returned.

Parameters:
$user-name : The name of a user.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-get-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:user-get-roles("Jim")

=>

Developer
admin
admin-builtins
sec:user-privileges(
$user-name as xs:string
)  as   element(sec:privilege)*
Summary:

Returns a set of privilege elements corresponding to all privileges that a user has. (roles are flattened to give a complete set of privileges).

Parameters:
$user-name : The name of a user.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-privileges if the current user is not $user-name.

Usage Notes:

If a user with name equal to $user-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:user-privileges("Jim")

=>

<sec:privilege xmlns:sec="http://marklogic.com/xdmp/security">
 <sec:privilege-id>12387631775818383068</sec:privilege-id>
  <sec:privilege-name>xdmp:save</sec:privilege-name>
  <sec:action>http://marklogic.com/xdmp/privileges/xdmp-save</sec:action>
  <sec:role-ids>
    <sec:role-id>13749738523688002780</sec:role-id>
  </sec:role-ids>
  <sec:kind>execute</sec:kind>
</sec:privilege>
(:  ..... and all other privileges assigned to "jim." :)
sec:user-remove-roles(
$user-name as xs:string,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Removes the roles ($role-names) from the list of roles granted to the user ($user-name).

If a user with name equal to $user-name is not found, an error is returned.

If one of $role-names does not correspond to an existing role, an error is returned.

If the current user is limited to granting only his/her roles, and one of $role-names is not a subset of the current user's roles, then an error is returned.


Parameters:
$user-name : The name of a user.
$role-names : A sequence of role names.

Required Privilege:

http://marklogic.com/xdmp/privileges/remove-role-from-user
and for role removal:
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:user-remove-roles("Jim", ("admin", "admin-builtins"))
 
(: Removes the "admin" and "admin-builtins" roles from the user, "Jim." :)
sec:user-set-default-collections(
$user-name as xs:string,
$collections as xs:string*
)  as   empty-sequence()
Summary:

Sets the default collections of a user with name $user-name to $collections.

Parameters:
$user-name : The name of a user.
$collections : A sequence of collections.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-set-default-collections

Usage Notes:

If a user with name $user-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
     "/MarkLogic/security.xqy";

sec:user-set-default-collections("Jim", 
    ("http://marklogic.com/jim_modules", 
     "http://marklogic.com/jim_docs"))

(: Sets the default collections for the user, "Jim," to "http://marklogic.com/jim_modules"
   and "http://marklogic.com/jim_docs". Any other previously set collections are removed.
sec:user-set-default-permissions(
$user-name as xs:string,
$permissions as element(sec:permission)*
)  as   empty-sequence()
Summary:

Sets the default permissions for a user with name $user-name.

Parameters:
$user-name : The name of the user.
$permissions : New permissions. If the empty sequence is provided, deletes the existing permissions.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-set-default-permissions

Usage Notes:

If a user with name $user-name is not found, an error is raised.

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:user-set-default-permissions(
   "Jim", 
    (xdmp:permission("security", "read"),
     xdmp:permission("security", "update")))

(: Sets the security(read) and security(update) permissions for user, "Jim." :)
sec:user-set-description(
$user-name as xs:string,
$description as xs:string
)  as   empty-sequence()
Summary:

Changes the description of the user identified by $user-name to $description.

Parameters:
$user-name : The name of the user.
$description : A description of the user.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-set-description if the current user is not $user-name.

Usage Notes:

This function must be executed against the security database.
Example: 
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:user-set-description(
    "Bill",
    "Senior QA Engineer")
  
(:  Changes the description of the user, "Bill." :)
sec:user-set-name(
$user-name as xs:string,
$new-user-name as xs:string,
$password as xs:string
)  as   empty-sequence()
Summary:

Changes the name of the user from $user-name to $new-user-name.

Parameters:
$user-name : The existing name of the user.
$new-user-name : The new name of the user.
$password : The password to set for the user. This can be either the original password for the user or a new password.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-set-name if the currrent user is not $user-name.

Usage Notes:

If a user with name equal to $user-name is not found, an error is returned.

If $new-user-name is not unique, an error is returned.

This function must be executed against the security database.
Example: 
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";

sec:user-set-name(
    "William",
    "Bill",
    "temp")
   
(: Changes the username from "Wiiliam" to "Bill" and resets the password to
   "temp". :)
sec:user-set-password(
$user-name as xs:string,
$password as xs:string
)  as   empty-sequence()
Summary:

Changes the password for the user identified by $user-name to $password.

Parameters:
$user-name : The name of the user.
$password : The new password. If $password is the empty string, an error is returned.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-set-password if the currrent user is not $user-name.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:user-set-password("Jim", "temp")

(: Changes the password for the user, "Jim," to "temp." :)
sec:user-set-password-extra(
$user-name as xs:string,
$extra as element(sec:password-extra)
)  as   empty-sequence()
Summary:

This function sets extra information for the specified user. If the user does not exist, an exception is thrown.

Parameters:
$user-name : The name of the user for whom to set the extra information.
$extra : The extra information to be set for the user.

Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

  let $extra := <sec:password-extra>
                   <p>Change this password in 30 days</p>
                </sec:password-extra>

  return sec:user-set-password-extra("Jim", $extra)

  (: Sets the extra information for the user, Jim. :)
sec:user-set-roles(
$user-name as xs:string,
$role-names as xs:string*
)  as   empty-sequence()
Summary:

Assigns the user with name $user-name to have the roles identified by $role-names. Removes previously assigned roles.

If a user with name equal to $user-name is not found, an error is returned.

If a role name in $role-names does not correspond to an existing role, an error is returned.

If $role-names is the empty sequence, all existing roles for the user are removed.

If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles or one of the removed roles is not a subset of the current user's roles, then an error is returned.

Parameters:
$user-name : The name of a user.
$role-names : A sequence of role names.

Required Privilege:

http://marklogic.com/xdmp/privileges/user-set-roles
and for role assignment ($role-names not empty sequence):
http://marklogic.com/xdmp/privileges/grant-all-roles or
http://marklogic.com/xdmp/privileges/grant-my-roles

Usage Notes:

This function must be executed against the security database.
Example: 
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
   
sec:user-set-roles("Jim", ("Developer", "Temporary"))

(:  Resets the roles for "Jim" to "Developer" and "Temporary. :)
sec:users-collection(  ) as  xs:string
Summary:

Returns a string corresponding to the uri for the users collection.

Usage Notes:

This function must be executed against the security database.
Example: 
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at 
    "/MarkLogic/security.xqy";
  
sec:users-collection( )

=>

http://marklogic.com/xdmp/users
sec:validate-permissions(
$permissions as element(sec:permission)*
)  as   node()*
Summary:

This function throws the SEC_NOPERMCAP exception if a permission has no capability specified and it throws the SEC-NOPERMROLEID exception if there is no role specified in the permission.

Parameters:
$permissions : Zero or more permission elements to check.

Usage Notes:

This function must be executed against the security database.
Example: 
  xquery version "1.0-ml"; 

  import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

  sec:validate-permissions(xdmp:permission("my-role", "read"))
Copyright  © 2012 MarkLogic Corporation.    All rights reserved.