This page was generated
January  28,  2016
4:04  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Configuration Packaging

The Configuration Packaging API module contains functions for scripting the packaging of MarkLogic Server resource configurations, such as database and App Server settings. Use the API to create, compare, and install configuration packages.

The Configuration Packaging API is installed as the following file:


install_dir/Modules/MarkLogic/manage/package/package.xqy
  

To use the Package module as part of your own XQuery module, include the following line in your XQuery prolog:


import module namespace pkg = "http://marklogic.com/manage/package"
        at "/MarkLogic/manage/package/package.xqy";
  

The library namespace prefix pkg is not predefined in the server.

Function Summary
pkg:create Create an empty configuration for use with other packaging functions.
pkg:database-configuration Returns the configuration (in XML) of the named database.
pkg:delete Deletes the named package.
pkg:differences Determines the differences between the configuration in the package and the current configuration of the MarkLogic server on which the function is executed.
pkg:errors Check a package for errors and, if there are errors, return a description of the errors as err:configuration-error elements.
pkg:exists Checks to see if the named package exists.
pkg:get-database Returns the configuration of the named database from the named package.
pkg:get-database-list Returns the names of the databases that have configurations in the named package.
pkg:get-modules Returns the modules data for the named app server from the named package.
pkg:get-package Returns the contents of the named package.
pkg:get-package-list Returns the list of packages.
pkg:get-server Returns the configuration of the named app server from the named package.
pkg:get-server-list Returns the names of the app servers that have configurations in the named package.
pkg:install Install the named package.
pkg:installable Checks to see if the named package can be installed.
pkg:put-database Adds a database configuration to the named package.
pkg:put-modules Puts the content of the modules database used by the named app server into the named package.
pkg:put-server Adds an app server configuration to the named package.
pkg:remove-database Removes the configuration of the named database from the named package.
pkg:remove-modules Removes the modules data for the named app server from the named package.
pkg:remove-server Removes the configuration of the named app server from the named package.
pkg:revert Revert configuration settings to those prior to a particular package installation.
pkg:server-configuration Returns the configuration (in XML) of the named app server, located in the named group.
pkg:valid Test a package for consistency.
Function Detail
pkg:create(
$pkgname as xs:string,
[$pkgbody as node()]
)  as   empty-sequence()
Summary:

Create an empty configuration for use with other packaging functions.

Parameters:
$pkgname : The name of the package.
$pkgbody (optional): The contents of the package.

Example:
xquery version "1.0-ml";
import module namespace pkg = "http://marklogic.com/manage/package" 
   at "/MarkLogic/manage/package/package.xqy";

pkg:create("mypackage")
  
  => Creates an empty package, named "mypackage."
  

pkg:database-configuration(
$database as xs:string
)  as   element(db:package-database)
Summary:

Returns the configuration (in XML) of the named database.

Parameters:
$database : The name of the database.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:database-configuration("Documents")

(: Returns the configuration of the 'Documents' database. :)
    

pkg:delete(
$pkgname as xs:string
)  as   empty-sequence()
Summary:

Deletes the named package.

Parameters:
$pkgname : The name of the package to delete.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:delete("mypackage")

(: Deletes the package named, 'mypackage'. :)
    

pkg:differences(
$pkgname as xs:string,
[$only-diffs as xs:boolean]
)  as   element(pkg:package-diff)
Summary:

Determines the differences between the configuration in the package and the current configuration of the MarkLogic server on which the function is executed.

Parameters:
$pkgname : The name of the package containing the configuration to compare with the MarkLogic server.
$only-diffs (optional): By default, all of the configuration settings in the package are returned, along with what settings are to be deleted and the settings that are to replace them. Specify fn:true() to return only those settings that are to be changed when the package is installed.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:differences("mypackage", fn:true())

(: Compare the configuration in the 'mypackage' package against the current
   configuration of your MarkLogic server and return only those settings that
   differ between the packaged and current configurations. :)
    

pkg:errors(
$pkgname as xs:string
)  as   element(err:configuration-error)*
Summary:

Check a package for errors and, if there are errors, return a description of the errors as err:configuration-error elements. If no errors are detected, an empty sequence is returned.

Parameters:
$pkgname : The name of the package to check for errors.

Example:
xquery version "1.0-ml";
import module namespace pkg = "http://marklogic.com/manage/package" 
    at "/MarkLogic/manage/package/package.xqy";

pkg:errors("mypackage)

  => Returns any detected errors.  If no errors are detected, 
     an empty sequence is returned.
  

pkg:exists(
$pkgname as xs:string
)  as   xs:boolean
Summary:

Checks to see if the named package exists. Returns true if the package exists and false if the package does not exist.

Parameters:
$pkgname : The package to check.

Required Privilege:

http://marklogic.com/xdmp/privileges/manage

Example:
xquery version "1.0-ml";
import module namespace pkg = "http://marklogic.com/manage/package" 
   at "/MarkLogic/manage/package/package.xqy";

pkg:exists("mypackage")
  
  => Returns 'true' if "mypackage" exists.  Otherwise returns 'false.'
  

pkg:get-database(
$pkgname as xs:string,
$database as xs:string
)  as   element(db:package-database)?
Summary:

Returns the configuration of the named database from the named package.

Parameters:
$pkgname : The name of the package from which to return the database configuration.
$database : The name of the database for which to return the configuration.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:get-database("mypackage", "Documents")

(: Returns the configuration of the 'Documents' database from the package
   named, 'mypackage'. :)
    

pkg:get-database-list(
$pkgname as xs:string,
[$start as xs:unsignedLong],
[$pageLength as xs:unsignedLong]
)  as   element(list:database-list)
Summary:

Returns the names of the databases that have configurations in the named package.

Parameters:
$pkgname : The name of the package that contains the database configurations.
$start (optional): The start position of the list of databases. For example, if there are a total of 50 databases and the pageLength is set to 5, then start=6 returns a list of 5 databases, starting with the sixth database (databases 6-10).
$pageLength (optional): The number of databases to return in each list.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:get-database-list("mypackage")

(: Returns the names of the databases that have configurations  
   in the package named, 'mypackage'.
    

pkg:get-modules(
$pkgname as xs:string,
$group as xs:string,
$server as xs:string
)  as   binary()?
Summary:

Returns the modules data for the named app server from the named package.

Parameters:
$pkgname : The name of the package containing the modules data.
$group : The name of the goup that contains the app server.
$server : The name of the app server that uses the modules data.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:get-modules("mypackage", "Default", "myserver")

(: Returns the modules data stored in the 'mypackage' package for the
   app server named, 'myserver'. :)
    

pkg:get-package(
$pkgname as xs:string,
[$mimetype as xs:string?]
)  as   xs:string?
Summary:

Returns the contents of the named package. By default, the package is returned in ZIP format.

Parameters:
$pkgname : The name of the package to return.
$mimetype (optional): The format in which to return the package. By default the package is returned in ZIP format. Specify application/xml to return the package in XML format or application/json to return the package in JSON format.

Usage Notes:

The XML and JSON formats only return the configuration of application servers and databases in the package. Packages may also contain modules, so the only reliable way to transport packages between clusters is with the ZIP format.


Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:get-package("mypackage", "application/xml")

(: Returns the contents of the 'mypackage' package in XML format. :)
    

pkg:get-package-list(
[$start as xs:unsignedLong],
[$pageLength as xs:unsignedLong]
)  as   element(list:package-list)
Summary:

Returns the list of packages.

Parameters:
$start (optional): The start position of the list of packages. For example, if there are a total of 50 packages and the pageLength is set to 5, then start=6 returns a list of 5 packages, starting with the sixth package (packages 6-10).
$pageLength (optional): The number of packages to return in each list.

Required Privilege:

http://marklogic.com/xdmp/privileges/manage

Example:
xquery version "1.0-ml";
import module namespace pkg = "http://marklogic.com/manage/package" 
    at "/MarkLogic/manage/package/package.xqy";

pkg:get-package-list()
  
  => Returns the list of packages.
  

pkg:get-server(
$pkgname as xs:string,
$group as xs:string,
$server as xs:string
)  as   element()?
Summary:

Returns the configuration of the named app server from the named package.

Parameters:
$pkgname : The name of the package from which to return the app server configuration.
$group : The name of the group that contains the app server.
$server : The name of the app server for which to return the configuration.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:get-server("mypackage", "Default", "dashml")

(: Returns the configuration of the 'dashml' app server located in the 'Default'
   group from the package named, 'mypackage'. :)
    

pkg:get-server-list(
$pkgname as xs:string,
[$start as xs:unsignedLong],
[$pageLength as xs:unsignedLong]
)  as   element(list:server-list)
Summary:

Returns the names of the app servers that have configurations in the named package.

Parameters:
$pkgname : The name of the package that contains the app server configurations.
$start (optional): The start position of the list of app servers. For example, if there are a total of 50 app servers and the pageLength is set to 5, then start=6 returns a list of 5 app servers, starting with the sixth app server (app servers 6-10).
$pageLength (optional): The number of databases to return in each list.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:get-server-list("mypackage")

(: Returns the names of the app servers that have configurations  
   in the package named, 'mypackage'.
    

pkg:install(
$pkgname as xs:string
)  as   pkgins:install($pkgname)
Summary:

Install the named package.

Parameters:
$pkgname : The name of the package to install.

Usage Notes:

Only users with the admin role may install packages.

Installing a package creates a ticket. Use info:ticket to check the status of the ticket.

Modifying some settings requires a server restart. If package installation requires a server restart to complete, the returned result directs you to restart.

The returned status reports success or failure in the pkg:result-status child element. If the installation fails, the live configuration is unchanged and errors are reported.

Attempting to install two or more packages concurrently may leave your configuration in an indeterminate state.


Example:
(: install a package previously created on the server :)
import module namespace pkg = "http://marklogic.com/manage/package" 
    at "/MarkLogic/manage/package/package.xqy";

pkg:install("mypackage")

  => The settings in "mypackage are applied and a status is
     returned, indicating success or failure. For example:

  <install-status xmlns="http://marklogic.com/manage/package">
    <success>true</success>
    <restart>false</restart>
    <ticket-id>/tickets/ticket/10368962049703559638</ticket-id>
    <revert-uri>/manage/v2/tickets/10368962049703559638/revert</revert-uri>
  </install-status>
  

pkg:installable(
$pkgname as xs:string
)  as   xs:boolean
Summary:

Checks to see if the named package can be installed. Returns true if the package is installable and false if the package is not installable.

Parameters:
$pkgname : The package to check.

Example:
xquery version "1.0-ml";

import module namespace pkg = "http://marklogic.com/manage/package" 
   at "/MarkLogic/manage/package/package.xqy";

pkg:installable("mypackage")

  => Returns 'true' if "mypackage" can be installed.  Otherwise returns 'false.' 
  

pkg:put-database(
$pkgname as xs:string,
$dbxml as element(db:package-database)
)  as   empty-sequence()
Summary:

Adds a database configuration to the named package.

Parameters:
$pkgname : The name of the package to which to add the database configuration.
$dbxml : The database configuration (in XML), such as that returned from the pkg:database-configuration function.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:put-database("mypackage", pkg:database-configuration("Documents"))

(: Add the configuration of the 'Documents' database to the package
   named, 'mypackage'. :)
    

pkg:put-modules(
$pkgname as xs:string,
$group as xs:string,
$server as xs:string
)  as   empty-sequence()
Summary:

Puts the content of the modules database used by the named app server into the named package.

Parameters:
$pkgname : The name of the package in which to put the modules data.
$group : The name of the goup that contains the app server.
$server : The name of the app server that uses the modules data.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:put-modules("mypackage", "Default", "myserver")

(: Puts the contents of the modules database used by the 'myserver' app server
   into the package named, 'mypackage'. :)
    

pkg:put-server(
$pkgname as xs:string,
$srvxml as element()
)  as   empty-sequence()
Summary:

Adds an app server configuration to the named package.

Parameters:
$pkgname : The name of the package to which to add the app server configuration.
$srvxml : The app server configuration (in XML), such as that returned from the pkg:server-configuration function.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:put-server("mypackage", pkg:server-configuration("Default", "dashml"))

(: Add the configuration of the 'dashml' app server located in the 'Default'
   group to the package named, 'mypackage'. :)
    

pkg:remove-database(
$pkgname as xs:string,
$database as xs:string
)  as   empty-sequence()
Summary:

Removes the configuration of the named database from the named package.

Parameters:
$pkgname : The name of the package from which to remove the database configuration.
$database : The name of the database for which to remove the configuration.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:remove-database("mypackage", "Documents")

(: Removes the configuration of the 'Documents' database from the package
   named, 'mypackage'. :)
    

pkg:remove-modules(
$pkgname as xs:string,
$group as xs:string,
$server as xs:string
)  as   empty-sequence()
Summary:

Removes the modules data for the named app server from the named package.

Parameters:
$pkgname : The name of the package from which to remove the modules data.
$group : The name of the group containing the app server.
$server : The name of the app server from which to remove the modules data.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:remove-modules("mypackage", "Default", "myserver")

(: Removes the modules data used by the 'myserver' app server in the
   package named, 'mypackage'. :)
    

pkg:remove-server(
$pkgname as xs:string,
$group as xs:string,
$server as xs:string
)  as   empty-sequence()
Summary:

Removes the configuration of the named app server from the named package.

Parameters:
$pkgname : The name of the package from which to remove the app server configuration.
$group : The name of the group that contains the app server.
$server : The name of the app server for which to remove the configuration.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:remove-server("mypackage", "Default", "dashml")

(: Removes the configuration of the 'dashml' app server located in the 'Default'
   group from the package named, 'mypackage'. :)
    

pkg:revert(
$ticket-id as xs:string
)  as   pkgins:revert($ticket)
Summary:

Revert configuration settings to those prior to a particular package installation.

Parameters:
$ticket-id : The id of a ticket created by a previous successful call to pkg:install.

Usage Notes:

Reverting a package installation restores all settings to their state at the time ticket was created by calling pkg:install. If other configuration changes are applied between the successful install and the attempt to revert, those changes are lost.

Successful calls to pkg:install create a ticket associated with the configuration changes. Use the revert-uri returned by pkg:install to revert the changes.

Reverting an installed package does not remove any forests associated with databases that are removed.


Example:
xquery version "1.0-ml";
import module namespace pkg = "http://marklogic.com/manage/package" 
    at "/MarkLogic/manage/package/package.xqy";

(: install a package :)
pkg:install("mypackage");

(: Produces the following for some previously saved pkg:

  <install-status xmlns="http://marklogic.com/manage/package">
    <success>true</success>
    <restart>false</restart>
    <ticket-id>/tickets/17841336193093321431</ticket-id>
    <revert-uri>/manage/v2/tickets/17841336193093321431/revert</revert-uri>
  </install-status>

:)

(: revert the above install :)
import module namespace pkg = "http://marklogic.com/manage/package" 
    at "/MarkLogic/manage/package/package.xqy";

pkg:revert("/tickets/ticket/17841336193093321431")

  
  => The changes applied by the package are reverted:

  <pkg:revert-status xmlns:pkg="http://marklogic.com/manage/package">
    <pkg:success>true</pkg:success>
    <pkg:restart>false</pkg:restart>
    <pkg:ticket-id>/tickets/ticket/5620889718989064792</pkg:ticket-id>
    <pkg:revert-uri>/manage/v2/tickets/5620889718989064792/revert</pkg:revert-uri>
  </pkg:revert-status>


  

pkg:server-configuration(
$group as xs:string,
$server as xs:string,
[$include-modules as xs:boolean]
)  as   element()
Summary:

Returns the configuration (in XML) of the named app server, located in the named group.

Parameters:
$group : The name of the group that contains the app server.
$server : The name of the app server for which to return the configuration.
$include-modules (optional): Whether or not to include any module configurations used by the app server. Specify fn:true() to include module configurations. Otherwise specify fn:false() or leave empty.

Example:

xquery version "1.0-ml"; 
 
import module namespace pkg = "http://marklogic.com/manage/package" 
      at "/MarkLogic/manage/package/package.xqy";

pkg:server-configuration("Default", "dashml")

(: Return the configuration of the 'dashml' app server located in the 'Default'
   group. :)
    

pkg:valid(
$pkgname as xs:string
)  as   xs:boolean
Summary:

Test a package for consistency. Returns true if the package is valid and false if the package is not valid.

Parameters:
$pkgname : The name of the package to check for validity.

Usage Notes:

This function returns true if the package is valid and false otherwise. Use pkg:errors to view a list of errors for an invalid package.

A package may be invalid for many reasons, including a violation of the package schema (Config/package.xsd), fields with erroneous values, or duplicate settings.


Example:
xquery version "1.0-ml";
import module namespace pkg = "http://marklogic.com/manage/package" 
    at "/MarkLogic/manage/package/package.xqy";

pkg:valid("mypackage)
  
  => Returns 'true' if "mypackage" is valid.  Otherwise returns 'false.'