Loading TOC...
Matches for cat:guide/admin-api (cat:guide/admin-api (cat:guide/admin-api (cat:guide (cat:guide)))) have been highlighted. remove
Scripting Administrative Tasks Guide (PDF)

MarkLogic Server 11.0 Product Documentation
Scripting Administrative Tasks Guide — Chapter 4

« Previous chapter
Next chapter »

Server Configuration Scripts

There are two basic approaches to creating and configuring server objects. One approach is to write a separate XQuery script for each new object, as shown in this chapter. The other approach is to write a more comprehensive XQuery program that creates all of the new server objects, as shown in the chapter. The approach you select will depend on your individual needs. The script-per-object approach is useful when making minor changes to an existing configuration. If your objective is to create a complete server configuration, you will probably want to write a complete configuration program like the sample configuration program.

The main topics in this chapter are:

Creating and Configuring Forests and Databases

The general information on forests and databases is provided in the Forests and Databases chapters in the Administrator's Guide.

This section shows individual XQuery scripts for tasks such as creating and configuring forests and databases. For more examples on how to use the Admin functions to modify your databases and monitor their operation, see Database Maintenance Operations.

The topics in this section are:

Creating Forests and Databases

The following script creates two new forests, named SampleDB-Forest and SampleModules-Forest and two new databases, named Sample-Database and Sample-Modules. Note that the $config variable holds the progressive configurations, each of which is then passed as input to the next admin function, so that the return value held by the final $config variable passed to admin:save-configuration contains the configuration data for all of the new forests and databases.

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Add new forests to the configuration :)
let $config := admin:forest-create(
  $config, 
  "SampleDB-Forest",
  xdmp:host(), (
  ))
let $config := admin:forest-create(
  $config, 
  "SampleModules-Forest",
  xdmp:host(), 
  ())   
(: Add new databases to the configuration :)
let $config := admin:database-create(
  $config,
  "Sample-Database",
  xdmp:database("Security"),
  xdmp:database("Schemas"))
let $config := admin:database-create(
  $config, 
  "Sample-Modules",
  xdmp:database("Security"),
  xdmp:database("Schemas"))
(: Save the configuration :)
return admin:save-configuration($config)

Attaching Forests to Databases

The following script attaches the SampleDB-Forest forest to the Sample-Database and the SampleModules-Forest to the Sample-Modules database:

(: Now that the database and forest have been created, we can attach the forest to the database. :)
xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
(: Get the configuration with the new forest and database :)
let $config := admin:get-configuration()
(: Attach the forest to the database :)
let $config := admin:database-attach-forest(
  $config,
  xdmp:database("Sample-Database"), 
  xdmp:forest("SampleDB-Forest"))
let $config := admin:database-attach-forest(
  $config,
  xdmp:database("Sample-Modules"), 
  xdmp:forest("SampleModules-Forest"))
(: Save the configuration :)
return admin:save-configuration($config)

Adding a Database Field and Included Element

As described in Overview of Fields in the Administrator's Guide, fields enable users to query portions of a database based on elements. If a field is configured with an included element, that element is indexed by the field so that the included element is also searched when searching for the field.

The following script adds the 'wiki-suggest' field to the Sample-Database.

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
(: Get the configuration with the new database :)
let $config := admin:get-configuration()
let $dbid := xdmp:database("Sample-Database")
let $fieldspec := admin:database-field("wiki-suggest", fn:false())
return admin:save-configuration(
  admin:database-add-field($config, $dbid, $fieldspec))

This script adds name as an included element to the wiki-suggest field :

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
(: Get the configuration with the new field :)
let $config := admin:get-configuration()
let $dbid := xdmp:database("Sample-Database")
let $fieldspec := admin:database-included-element(
  "http://marklogic.com/wikipedia", 
  "name", 
  1.0, 
  "", 
  "", 
  "")
return admin:save-configuration(
    admin:database-add-field-included-element(
  $config, 
  $dbid, 
  "wiki-suggest", 
  $fieldspec) )

Adding Indexes to a Database

As described in Understanding Range Indexes in the Administrator's Guide, you can create range indexes on elements or attributes of type xs:string to accelerate the performance of queries that sort by the string values.

The following script sets a range element index for the name element in the Sample-Database database:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
let $dbid := xdmp:database("Sample-Database")
let $rangespec := admin:database-range-element-index(
  "string", 
  "http://marklogic.com/wikipedia",
  "name", 
  "http://marklogic.com/collation/",
  fn:false() )
return admin:save-configuration(
  admin:database-add-range-element-index( 
    $config, 
    $dbid, 
    $rangespec))

The following script sets a range element attribute index for the year attribute of the nominee element in the Sample-Database database:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
let $dbid := xdmp:database("Sample-Database")
let $rangespec := admin:database-range-element-attribute-index(
  "gYear", 
  "http://marklogic.com/wikipedia",
  "nominee", 
  "", 
  "year", 
  "",
  fn:false())
return admin:save-configuration(
  admin:database-add-range-element-attribute-index(
    $config, 
    $dbid, 
    $rangespec))

Creating a Scheduled Backup of a Database

The following script creates a weekly backup of the Sample-Database database and adds it to the configuration:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
let $database := xdmp:database("Sample-Database")
let $backup := admin:database-weekly-backup(
  "c:/backup-dir", 
  "monday", 
  xs:time("09:45:00"),
  10,
  true(),
  true(),
  true())
return
  admin:save-configuration(
    admin:database-add-backup($config, $database, $backup))

Creating and Configuring Databases in a Single Transaction

In this example, we create and configure the same databases as in the previous sections. Only the databases are created and configured in a single transaction. As described in Creating and Configuring Objects in a Single Transaction, we use the admin:database-get-id function to obtain the database IDs after creating the databases to configure the newly created databases in the same transaction. This example is abbreviated for the sake of simplicity and does not check for existing objects, as described in Making Transactions Idempotent.

This example assumes the forests, SampleDB-Forest and SampleModules-Forest, have been already been created in a separate transaction.

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
         at "/MarkLogic/admin.xqy";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Add new databases to the configuration :)
let $config := admin:database-create(
  $config, 
  "Sample-Database",
  xdmp:database("Security"),
  xdmp:database("Schemas"))
let $config := admin:database-create(
  $config, 
  "Sample-Modules",
  xdmp:database("Security"),
  xdmp:database("Schemas"))
(: Obtain the database IDs to configure the databases :)
let $Sample-Database := admin:database-get-id(
  $config, 
  "Sample-Database")
let $Sample-Modules := admin:database-get-id(
  $config, 
  "Sample-Modules")
(: Attach the forest to the database. :)
let $config := admin:database-attach-forest(
  $config,
  $Sample-Database,
  xdmp:forest("SampleDB-Forest"))
let $config := admin:database-attach-forest(
  $config,
  $Sample-Modules, 
  xdmp:forest("SampleModules-Forest"))
(: Add a 'wiki-suggest' field to the Sample-Database :)
let $fieldspec := admin:database-field(
  "wiki-suggest", 
  fn:false())
let $config := admin:database-add-field(
  $config, 
  $Sample-Database, 
  $fieldspec)
(: Add included elements to 'wiki-suggest' field :)
let $incfieldspec := admin:database-included-element(
  "http://marklogic.com/wikipedia", 
  "name", 
  1.0, 
  "", 
  "", 
  "")
let $config := admin:database-add-field-included-element(
  $config, 
  $Sample-Database, 
  "wiki-suggest", 
  $incfieldspec) 
(: Add indexes to the Sample-Database :)
let $rangespec := admin:database-range-element-index(
  "string", 
  "http://marklogic.com/wikipedia",
  "name", 
  "http://marklogic.com/collation/",
  fn:false() )
let $config := admin:database-add-range-element-index(
    $config, 
    $Sample-Database, 
    $rangespec)
let $rangespec := admin:database-range-element-attribute-index(
  "gYear", 
  "http://marklogic.com/wikipedia",
  "nominee", 
  "", 
  "year", 
  "",
  fn:false())
let $config := admin:database-add-range-element-attribute-index(
  $config, 
  $Sample-Database,
  $rangespec)
(: Configure a scheduled backup of the Sample-Database :)
let $backup := admin:database-weekly-backup(
  "c:/backup-dir", 
  "monday", 
  xs:time("09:45:00"),
  10,
  true(),
  true(),
  true())
let $config := admin:database-add-backup(
  $config, 
  $Sample-Database, 
  $backup)
return
  admin:save-configuration($config)

Deleting a Forest and Database

The following script deletes the forest and database created in Creating and Configuring Databases in a Single Transaction:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Delete the database from the configuration :)
let $config := admin:database-delete(
  $config, 
  admin:database-get-id($config, "Sample-Database")) 
let $config := admin:database-delete(
  $config, 
  admin:database-get-id($config, "Sample-Modules")) 
(: Save the configuration :)
return admin:save-configuration($config);
(: Now that the database has been deleted, we can delete the forest :)
import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";
(: Get the configuration with the deleted database :)
let $config := admin:get-configuration()
(: Delete the forest from the configuration :)
let $config := admin:forest-delete(
  $config,
  admin:forest-get-id($config, "SampleDB-Forest"),
  fn:true())
let $config := admin:forest-delete(
  $config,
  admin:forest-get-id($config, "SampleModules-Forest"),
  fn:true())
(: Save the configuration :)
return admin:save-configuration($config)

Creating and Configuring Groups

The general information on groups is provided in the Groups chapter in the Administrator's Guide.

This section shows individual XQuery scripts that create and configure groups. See Group Maintenance Operations for more examples on how to use the Admin functions to modify your groups and monitor their operation.

The topics in this section are:

Creating a Group

The following script creates a new group, named Sample:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
return
  admin:save-configuration(
    admin:group-create($config, "Sample"))

Enabling Auditing on a Group

The following script enables auditing of user-configuration-change and user-role-addition events on the Sample group:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Sample")
(: Set user-configuration-change and user-role-addition events to be audited in the Sample group. :)
let $config := 
  admin:group-enable-audit-event-type(
    $config, 
    $groupid, 
    ("user-configuration-change", "user-role-addition"))
(: Enable auditing for the Sample group. :)
return 
  admin:save-configuration(
    admin:group-set-audit-enabled($config, $groupid, fn:true()))

Creating a New Namespace for a Group

The following script creates a new namespace, named myprefix, and adds it to the Sample group:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Sample")
return
  admin:save-configuration(
    admin:group-add-namespace(
      $config, 
      $groupid,
      admin:group-namespace("myprefix", "http://myuri/namespace")))

Creating and Configuring a Group in a Single Transaction

In this example, we create and configure the same group as in the previous sections. Only the group is created and configured in a single transaction. As described in Creating and Configuring Objects in a Single Transaction, we use the admin:group-get-id function to obtain the group ID after creating the group to configure the newly created group in the same transaction. This example is abbreviated for the sake of simplicity and does not check for existing objects, as described in Making Transactions Idempotent.

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
(: Create the Sample group :)
let $config := admin:group-create($config, "Sample")
(: Obtain the group ID to configure the group :)
let $SampleGroup := admin:group-get-id($config, "Sample") 
(: Set user-configuration-change and user-role-addition events to be    audited in the Sample group. :)
let $config := admin:group-enable-audit-event-type(
  $config, 
  $SampleGroup, 
  ("user-configuration-change", "user-role-addition"))
(: Enable auditing for the Sample group. :)
let $config := admin:group-set-audit-enabled(
  $config, 
  $SampleGroup, 
  fn:true())
(: Add a namespace to the Sample group. :)
let $config := admin:group-add-namespace(
  $config, 
  $SampleGroup,
  admin:group-namespace("myprefix", "http://myuri/namespace"))
return admin:save-configuration($config)

Deleting a Group

The following script deletes the group created in Creating and Configuring a Group in a Single Transaction:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
return admin:save-configuration(
  admin:group-delete(
    $config, 
    admin:group-get-id($config, "Sample")))

Creating and Configuring App Servers

The general information on App Servers is provided in the HTTP Servers, XDBC Servers, and WebDAV Servers chapters in the Administrator's Guide.

This section shows individual XQuery scripts for tasks such as creating and configuring App Servers. See App Server Maintenance Operations for more examples on how to use the Admin functions to modify your App Servers and monitor their operation.

This section describes:

Creating an App Server

The following script creates a new HTTP server in the Sample group, named Sample-Server, at port 8016. The application/ directory is the root, the Sample-Database is the content database and Sample-Modules is the modules database:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Get the group under which to create the App Server :)
let $groupid := admin:group-get-id($config, "Sample")
(: Add the new App Server to the configuration :)
let $server := admin:http-server-create(
  $config, 
  $groupid,
  "Sample-Server", 
  "application/",
  8016,
  admin:database-get-id($config, "Sample-Modules"),
  admin:database-get-id($config, "Sample-Database"))
(: Save the configuration :)
return admin:save-configuration($server);

Setting a URL Rewriter on an App Server

The following script sets the rewriter.xqy module to rewrite the URL from clients to an internal URL:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
(: Get the configuration containing the new App Server :)
let $config := admin:get-configuration()
(: Get the group for the App Server :)
let $groupid := admin:group-get-id($config, "Sample")
(: Set the URL rewriter :)
let $urlrewriter := admin:appserver-set-url-rewriter(
  $config,
  admin:appserver-get-id($config, $groupid, "Sample-Server"),
  "rewriter.xqy")
(: Save the configuration :)
return admin:save-configuration($urlrewriter)

Setting the Concurrent Request Limit on an App Server

The following script sets the Concurrent Request Limit for the Sample-Server App Server to 15:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Sample")
return
  admin:save-configuration(
    admin:appserver-set-concurrent-request-limit(
    $config, 
    admin:appserver-get-id($config, $groupid, "Sample-Server"),
    5))

Enabling Display Last-Login on an App Server

The following script enables Display Last Login on the Sample-Server App Server, using the Last-Login database:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Sample")
let $config2 := admin:appserver-set-last-login(
  $config, 
  admin:appserver-get-id($config, $groupid, "Sample-Server"),
  xdmp:database("Last-Login"))
return admin:save-configuration(
  admin:appserver-set-display-last-login(
    $config2,
    admin:appserver-get-id($config, $groupid, "Sample-Server"),
    fn:true()))

Creating and Configuring an App Server in a Single Transaction

In this example, we create and configure the same App Server as in the previous sections. Only the App Server is created and configured in a single transaction. As described in Creating and Configuring Objects in a Single Transaction, we use the admin:appserver-get-id function to obtain the App Server ID after creating the App Server to configure the newly created App Server in the same transaction. This example is abbreviated for the sake of simplicity and does not check for existing objects, as described in Making Transactions Idempotent.

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Get the group under which to create the App Server :)
let $groupid := admin:group-get-id($config, "Sample")
(: Add the new App Server to the configuration :)
let $config := admin:http-server-create(
  $config, 
  $groupid,
  "Sample-Server", 
  "application/",
  8016,
  admin:database-get-id($config, "Sample-Modules"),
  admin:database-get-id($config, "Sample-Database"))
let $Sample-Server := admin:appserver-get-id(
  $config, 
  $groupid, 
  "Sample-Server")
(: Set the URL rewriter :)
let $config := admin:appserver-set-url-rewriter(
  $config,
  $Sample-Server,
  "rewriter.xqy")
let $config := admin:appserver-set-concurrent-request-limit(
  $config, 
  $Sample-Server,
  15)
let $config := admin:appserver-set-last-login(
  $config, 
  $Sample-Server,
  xdmp:database("Last-Login"))
let $config := admin:appserver-set-display-last-login(
  $config,
  $Sample-Server,
  fn:true())
return admin:save-configuration($config)

Deleting an App Server

The following script deletes the HTTP server created in Creating and Configuring an App Server in a Single Transaction:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Get the group from which to delete the App Server :)
let $groupid := admin:group-get-id($config, "Default")
(: Delete the App Server from the configuration :)
let $config := admin:appserver-delete(
  $config, 
  admin:appserver-get-id($config, $groupid, "Sample-Server"))
(: Save the configuration :)
return admin:save-configuration($config)

Creating and Configuring Roles and Users

The general information on users and roles is provided in the Security Administration chapter in the Administrator's Guide.

This section shows an individual XQuery script that creates a new role, named Temporary, and two new users, named Tom and Sue. The new role is given the default collection, testDocument, and is assigned the privilege, unprotected-collections. Jim is given the default permission, security(read). See User Maintenance Operations for more examples on how to use the Security library functions to modify security objects and monitor their operation.

Security objects must be created in the Security database. See Executing Queries in Select Databases for techniques on how to execute queries in a database other than the one set for your App Server.

(: run this against the Security database :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" 
  at "/MarkLogic/security.xqy";
(: Create new role :)
sec:create-role(
  "Temporary",
  "Temporary worker access",
  ("filesystem-access"),
  (),
  ("testDocument"));
(: Now that the role is created, we can assign it a new privilege and assign the role to new users :)
xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" 
  at "/MarkLogic/security.xqy";
(: Add the 'Temporary' role to the list of roles with 'unprotected-collections' privilege :)
sec:privilege-add-roles(
  "http://marklogic.com/xdmp/privileges/unprotected-collections",
  "execute",
  ("Temporary")),
(: Create two new users with the role, 'Temporary'. :)
sec:create-user(
  "Jim",
  "Jim the temp",
  "newtemp",
  "Temporary",
  (xdmp:permission("security", "read")),
  ()),
sec:create-user(
  "Sue",
  "Sue the temp",
  "newtemp",
  "Temporary",
  (),
  ())

« Previous chapter
Next chapter »