domino-db Reference

This page describes each domino-db class and function in detail. To navigate between sections, use the table of contents on the right.

DominoDB class

The DominoDB class is the single export of this module. You use DominoDB to obtain references to other classes.

useServer

A factory function for instantiating a Server instance.

NOTE: This function does not make any requests to Domino for verification of the configuration.

Parameters

configuration {Object}: The configuration passed for binding

• hostName {string}: The host name of the Domino server (ex: "demo.host.com")
• connection {Object}: The connection properties used for requests sent to the Domino server
  • port {string}: The Proton port
  • secure {boolean}: true if TLS is enabled on the above port
• credentials {Object}: The credentials used for secure requests.
  • rootCertificate {Buffer}: Required if TLS is enabled.
  • clientCertificate {Buffer}: Required if TLS is enabled.
  • clientKey {Buffer}: Required if TLS is enabled.
  • idFilePassword {string}: Required only if you intend to use this server instance to encrypt and decrypt documents. This feature assumes the target server has access to an ID vault and the identity specified by clientCertificate has an ID file in the vault. See Item encryption and decryption for details.

Return Value

{Promise<Server>}

A promise resolved with a deeply frozen Server class reference. If the configuration parameters are invalid, the promise will be rejected with an error message.

Example

const { useServer } = require('@domino/domino-db');

const config = {
  hostName: 'www.demo.domain.com',
};

useServer(config)
  .then(server => {
    // server is available for use. See "Server" docs for class members
  })
  .catch(error => {
    // server configuration is malformed
    console.log(error);
  });

---

Server class

You obtain an instance of Server by calling DominoDB::useServer. You use Server::useDatabase to obtain a reference to a Database. See below for a description of additional Server functions.

useDatabase

A factory function for instantiating a Database instance that is bound to a specific database.

NOTE: This function does not make any requests to Domino for verification of the configuration.

Parameters

configuration {Object} The configuration passed for binding

• filePath {string} The path to the database, relative to the Domino data directory

Return Value

{Promise<Database>} A promise resolved with an instance of the Database class, bound with the configuration information.

Example

const { useServer } = require('@domino/domino-db');
const config = require('./server-config.js');

useServer(config)
  .then(async server => {
    const database = await server.useDatabase({
      filePath: '/example/directory/demo.nsf',
    });
    // database is available for use. See "Database" docs for class members
  })
  .catch(error => {
    // Either "config" is malformed OR databaseConfig is malformed.
    console.log(error);
  });

createDatabase

A function which creates a new database in the Domino data directory, using the identity of the application's ID. If a template is not specified, the database is blank. The database ACL is set to:

• -Default-: No Access
• Server: Manager access
• LocalDomainServers: Manager access
• OtherDomainSevers: No Access

If the server document has a names list for "Create databases & templates", the application's ID must be included in that list to be able to create a database.

This feature is disabled by default. See Administrative Operations for details on how to enable it.

Parameters

options {Object}

• accessToken {string} Optional - An optional access token. See Act-as-User for details.
• filePath {string} REQUIRED - The path to the database relative to the Domino data directory. Only paths within the Domino data directory are allowed.
• title {string} REQUIRED - The title of the database.
• template {string} Optional - The path to a template to use, relative to the Domino data directory. If not included, a blank database is created.

Return Value

{Promise<undefined>} A promise resolved with undefined

Example

const { useServer } = require('@domino/domino-db');
const config = require('./server-config.js');

useServer(config)
  .then(async server => {
    await server.createDatabase({
      filePath: 'example/demo-database.nsf',
      title: 'Example Node Discussion Database',
      template: 'discussion11.ntf',
    });
    const database = await server.useDatabase({
      filePath: 'example/demo-database.nsf',
    });
    // New database is available.
  })
  .catch(error => {
    // Either "config" is malformed OR there was an error creating the database
    console.log(error);
  });

deleteDatabase

A function which deletes a database in the Domino data directory, using the identity of the application's ID. The application must have Manager access to the database and access to the server. Replicas of the database are not deleted.

This feature is disabled by default. See Administrative Operations for details on how to enable it.

Parameters

options {Object}

• accessToken {string} Optional - An optional access token. See Act-as-User for details.
• filePath {string} REQUIRED - The path to the database relative to the Domino data directory. Only paths within the Domino data directory are allowed.

Return Value

{Promise<undefined>} A promise resolved with undefined

Example

const { useServer } = require('@domino/domino-db');
const config = require('./server-config.js');

useServer(config)
  .then(async server => {
    await server.deleteDatabase({
      filePath: 'example/demo-database.nsf',
    });
    // Database has been deleted successfully.
  })
  .catch(error => {
    // Either "config" is malformed OR there was an error deleting the database
    console.log(error);
  });

getFileSystemList

A function to get the list of database files in the specified directory. The application must have the access to the server. The list contains the following types of files:

• database file (.nsf)
• template file (.ntf)
• mailbox file (.box)
• database directory

Notes:

• Directory path must be in the Domino data directory or its subdirectories.
• A list of files is returned for the specified directory only. Call this function recursively to list files for sub-directories.
• To return a list of files, the .ACL file(directory ACL) in the directory must allow access.

Parameters

options {Object}

• accessToken {string} Optional - An optional access token. See Act-as-User for details.
• dirPath {string} REQUIRED - The path to the database directory relative to the Domino data directory. Only paths within the Domino data directory are allowed. To specify the Domino data directory, provide an empty string.

Return Value

This function will return promise of FileSystemResponse

Example

const { useServer } = require("@domino/domino-db");
const config = require("./server-config.js");

useServer(config)
  .then(async (server) => {
    await server.getFileSystemList({
      dirPath: "",
    });
  })
  .catch((error) => {
    // Either "config" is malformed OR there was an error in getting file system list
    console.log(error);
  });

getHostName

Gets the Domino server host name.

Return Value

{Promise<string>} A promise resolved with the Domino server host name.

Example

const { useServer } = require('@domino/domino-db');
const config = require('./server-config.js'); // { ... "hostName": "foo.bar" }

useServer(config).then(async server => {
  const hostName = await server.getHostName();
  console.log(hostName); // foo.bar
});

getConnection

A getter function which returns the connection properties used to access the Domino server.

Return Value

{Promise<Object>} A promise resolved with the value of the connection object.

Example

const { useServer } = require('@domino/domino-db');

// { ... "connection": {
//   "port": "3003",
// }
const config = require('./server-config.js');

useServer(config).then(async server => {
  const connection = await server.getConnection();
  console.log(connection.port); // 3003
});

---

Database class

You obtain an instance of Database by calling Server::useDatabase. You use Database::useDocument to obtain an instance of a Document. See below for a description of other Database functions.

useDocument

A factory function for instantiating a Document instance that is bound to a specific document.

NOTE: This function does not make any requests to Domino for verification of the configuration.

Parameters

configuration {Object}

• unid {string} The unid of the document.

Return Value

{Promise<Document>} A promise resolved with an instance of the Document class, bound with the unid provided.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '12345678901234567890123456789012',
  });
  // document is available for use. See "Document" docs for class members
});

useAgent

A factory function for instantiating an Agent instance that is bound to a specific agent.

NOTE: This function does not make any requests to Domino for verification of the configuration.

Parameters

configuration {Object}

• name {string} The Agent name or alias.

Return Value

{Promise<Agent>} A promise that resolves to an instance of the Agent class, bound with the name provided.

Example

const { useServer } = require('@domino/domino-db');
const fs = require('fs');

const serverConfig = {
  hostName: 'dev1',
  connection: {
    port: 3003,
    secure: true,
  },
  credentials: {
    rootCertificate: fs.readFileSync('rootca.crt'),
    clientCertificate: fs.readFileSync('app.crt'),
    clientKey: fs.readFileSync('app.key'),
  },
};

const agentUseExample = async () => {
  const server = await useServer(serverConfig);
  const database = await server.useDatabase({ filePath: 'node-demo.nsf' });
  const agent = await database.useAgent({ name: 'MyAgent' });
  // agent is available for use
};

createDocument

Creates a document.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• document {Object} REQUIRED - The new document contents. See domino-db document schema for information about representing a document as a JavaScript object.
• computeOptions {Object} An optional object specifying how to compute items on the new document. See Compute with form for details.
• duplicateItems {boolean} An optional boolean value used to create duplicate items in the new document. See Duplicate items for details.

Return Value

{Promise<string>} A promise resolved with the UNID of the new document

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const unid = await database.createDocument({
    document: {
      Form: 'Contact',
      FirstName: 'Aaron',
      LastName: 'Aardman',
      City: 'Arlington',
      State: 'MA',
    },
  });
  // unid is the unique identifier of the new  document
});

bulkCreateDocuments

Creates multiple documents. To create a single document, see Database::createDocument.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• documents {Array<Object>} REQUIRED - An array of new documents
• computeOptions {Object} An optional object specifying how to compute items on the new documents. See Compute with form for details.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
• duplicateItems {boolean} An optional boolean value used to create duplicate items in the new documents. See Duplicate items for details.

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const response = await database.bulkCreateDocuments({
    documents: [
      {
        Form: 'Contact',
        FirstName: 'Aaron',
        LastName: 'Aardman',
        City: 'Arlington',
        State: 'MA',
      },
      {
        Form: 'Contact',
        FirstName: 'Brian',
        LastName: 'Aardman',
        City: 'Andover',
        State: 'MA',
      },
    ],
  });

  // response.documents is an array of objects. Map to an
  // array of UNIDs.
  const unids = response.documents.map(doc => doc['@unid']);
});

bulkCreateAttachmentStream

Creates a stream for writing one or more attachments

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.

Return Value

{Promise<Object>} A promise resolved with a writable attachment stream. See Writing attachments for details on writing to the stream.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const writable = await database.bulkCreateAttachmentStream({});

  // writable is an output stream for writing attachments
});

bulkCreateRichTextStream

Creates a stream for writing one or more rich text fields.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.

Return Value

{Promise<Object>} A promise resolved with a writable rich text stream. See Writing rich text for details on writing to the stream.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const writable = await database.bulkCreateRichTextStream({});

  // writable is an output stream for writing rich text
});

bulkReadDocuments

Reads all documents matching a query string. For the query syntax, see Domino Query Langauge.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.

• query {string} REQUIRED - A query string.

• queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.

• queryLimits {Object} An optional set of limits on the query.

  • maxViewEntriesScanned {number} The maximum number of view entries to scan.
  • maxDocumentsScanned {number} The maximum number of documents to scan.
  • maxMilliSeconds {number} The maximum number of milliseconds to spend executing the query.

• itemNames {Array<string>} An optional array of item names. Use this option to read selected items. The default is to read no document items.

• start {number} An optional zero-based start index. Use this to page through a large set of matching documents.

• count {number} An optional count of the maximum number of documents to read.

  Note: If you don't specify the optional count, the default value is 100. The "DOCUMENT LIMITS" configuration setting determines the maximum number of documents that can be read, up to 1000.

• computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.

• readAttachmentSummaries {boolean} An optional boolean value specifying whether to read attachment summaries as described in @attachments.

• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

• canonicalFormat {boolean} An optional boolean value used to return item properties in canonical format, as objects. See Reading items in canonical format for details.

• duplicateItems {boolean} An optional boolean value used to return duplicate items. See Duplicate items for details.

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const documents = await database.bulkReadDocuments({
    query: "Form = 'Contact' and LastName = 'Aardman'",
  });

  // documents is an array of documents -- one for each
  // document that matches the query
});

bulkReadDocumentsByUnid

Reads multiple documents by UNID. To read a single document, see Document::read.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• unids {Array<string>} REQUIRED - An array of UNIDs.
• itemNames {Array<string>} An optional array of item names. Use this option to read selected items. The default is to read no document items.
• computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
• readAttachmentSummaries {boolean} An optional boolean value specifying whether to read attachment summaries as described in @attachments.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
• canonicalFormat {boolean} An optional boolean value used to return item properties in canonical format, as objects. See Reading items in canonical format for details.
• duplicateItems {boolean} An optional boolean value used to return duplicate items. See Duplicate items for details.

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const documents = await database.bulkReadDocumentsByUnid({
    unids: [
      '28438659F50E2637852582C600038599',
      '5B5544335FA7D893852582C60003859A',
    ],
  });

  // documents is an array of documents -- one for each
  // UNID in the unids array
});

bulkReadAttachmentStream

Reads attachments from all documents matching a query string.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• query {string} REQUIRED - A query string.
• queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.
• queryLimits {Object} An optional set of limits on the query.
  • maxViewEntriesScanned {number} The maximum number of view entries to scan.
  • maxDocumentsScanned {number} The maximum number of documents to scan.
  • maxMilliSeconds {number} The maximum number of milliseconds to spend executing the query.
• fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are streamed. If not specified, ALL attachments are streamed.
• chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

{Promise<Object>} A promise resolved with a readable attachment stream. See Reading attachments for details on reading from the stream.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Read all attachments matching photo.jpg or photo.png
  // from documents matching the given query
  const readable = await database.bulkReadAttachmentStream({
    query: "Form = 'Contact' and LastName = 'Aardman'",
    fileNames: ['photo.jpg', 'photo.png'],
    chunkSizeKb: 16
  });

  // readable is a stream of attachments
});

bulkReadAttachmentStreamByUnid

Reads attachments from a set of documents specified by UNID.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• unids {Array<string>} REQUIRED - An array of UNIDs.
• fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are streamed. If not specified, ALL attachments are streamed.
• chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

{Promise<Object>} A promise resolved with a readable attachment stream. See Reading attachments for details on reading from the stream.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Read all attachments from documents matching the
  // given UNIDs
  const readable = await database.bulkReadAttachmentStreamByUnid({
    unids: [
      '28438659F50E2637852582C600038599',
      '5B5544335FA7D893852582C60003859A',
    ],
  });

  // readable is a stream of attachments
});

bulkReadRichTextStream

Reads rich text from all documents matching a query string.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• query {string} REQUIRED - A query string.
• queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.
• queryLimits {Object} An optional set of limits on the query.
  • maxViewEntriesScanned {number} The maximum number of view entries to scan.
  • maxDocumentsScanned {number} The maximum number of documents to scan.
  • maxMilliSeconds {number} The maximum number of milliseconds to spend executing the query.
• fields {Array<string>} REQUIRED - An array of rich text item names. Repeating items with the same name will be concatenated into a single stream without the data type word.
• chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

{Promise<Object>} A promise resolved with a readable rich text stream. See Reading Rich Text for details on reading from the stream.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Read all rich text from items named body1 and body2
  // from documents matching the given query
  const readable = await database.bulkReadAttachmentStream({
    query: "Form = 'Contact' and LastName = 'Aardman'",
    fields: ['body1', 'body2'],
    chunkSizeKb: 16
  });

  // readable is a stream of rich text
});

bulkReadRichTextStreamByUnid

Reads rich text from a set of documents specified by UNID.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• unids {Array<string>} REQUIRED - An array of UNIDs.
• fields {Array<string>} REQUIRED - An array of rich text item names. Repeating items with the same name will be concatenated into a single stream without the data type word.
• chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

{Promise<Object>} A promise resolved with a readable rich text stream. See Reading Rich Text for details on reading from the stream.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Read all attachments from documents matching the
  // given UNIDs
  const readable = await database.bulkReadRichTextStreamByUnid({
    unids: [
      '28438659F50E2637852582C600038599',
      '5B5544335FA7D893852582C60003859A',
    ],
    fields: ['body1', 'body2'],
  });

  // readable is a stream of rich text
});

bulkDeleteDocuments

Deletes all documents matching a query string.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• query {string} REQUIRED - A query string.
• queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.
• queryLimits {Object} An optional set of limits on the query. See bulkReadDocuments for details.
• start {number} An optional zero-based document start index.
• count {number} An optional count of the maximum number of documents to delete.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const response = await database.bulkDeleteDocuments({
    query: "Form = 'Contact' and LastName = 'Aardman'",
  });

  // response.documents is an array of objects -- one for each
  // document matching the query.
});

bulkDeleteDocumentsByUnid

Deletes multiple documents by UNID. To delete a single document, see Document::delete.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• unids {Array<string>} REQUIRED - An array of UNIDs.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const response = await database.bulkDeleteDocumentsByUnid({
    unids: [
      '28438659F50E2637852582C600038599',
      '5B5544335FA7D893852582C60003859A',
    ],
  });

  // response.documents is an array of objects -- one for each
  // UNID in the unids array.
});

bulkDeleteItems

Deletes selected items in all documents matching a query string.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• query {string} REQUIRED -- A query string.
• queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.
• queryLimits {Object} An optional set of limits on the query. See bulkReadDocuments for details.
• itemNames {Array<string>} REQUIRED - An array of item names
• start {number} An optional zero-based document start index.
• count {number} An optional count of the maximum number of documents to process.
• computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Delete the EMail and Phone items for each document
  // matching the query
  const response = await database.bulkDeleteItems({
    query: "Form = 'Contact' and LastName = 'Aardman'",
    itemNames: ['EMail', 'Phone'],
  });

  // response.documents is an array of objects -- one for each
  // document matching the query.
});

bulkDeleteItemsByUnid

Deletes selected items in multiple documents.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• unids {Array<string>} REQUIRED - An array of UNIDs.
• itemNames {Array<string>} REQUIRED - An array of item names
• computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Delete the EMail and Phone items for each document
  // in the unids array
  const response = await database.bulkDeleteItemsByUnid({
    unids: [
      '28438659F50E2637852582C600038599',
      '5B5544335FA7D893852582C60003859A',
    ],
    itemNames: ['EMail', 'Phone'],
  });

  // response.documents is an array of objects -- one for each
  // UNID in the unids array.
});

bulkDeleteAttachments

Deletes attachments in documents matching a query string.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• query {string} REQUIRED -- A query string.
• queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.
• queryLimits {Object} An optional set of limits on the query. See bulkReadDocuments for details.
• fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are deleted. If not specified, ALL attachments are deleted.
• start {number} An optional zero-based document start index.
• count {number} An optional count of the maximum number of documents to process.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Delete the photo.jpg attachment for each document
  // matching the query
  const response = await database.bulkDeleteAttachments({
    query: "Form = 'Contact' and LastName = 'Aardman'",
    fileNames: ['photo.jpg'],
  });

  // response.documents is an array of objects -- one for each
  // document matching the query. If at least one attachment
  // was deleted from a document, the corresponding object includes
  // an @attachments property.
});

bulkDeleteAttachmentsByUnid

Deletes attachments in multiple documents.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• unids {Array<string>} REQUIRED - An array of UNIDs.
• fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are deleted. If not specified, ALL attachments are deleted.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Delete ALL attachments from each document in the unids array
  const response = await database.bulkDeleteAttachmentsByUnid({
    unids: [
      '28438659F50E2637852582C600038599',
      '5B5544335FA7D893852582C60003859A',
    ],
    // No fileNames property means ALL attachments
  });

  // response.documents is an array of objects -- one for each
  // document in the unids array. If at least one attachment
  // was deleted from a document, the corresponding object includes
  // an @attachments property.
});

bulkReplaceItems

Replaces selected items in all documents matching a query.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• query {string} REQUIRED - A query string.
• queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.
• queryLimits {Object} An optional set of limits on the query. See bulkReadDocuments for details.
• replaceItems {Object} REQUIRED - An object containing items to replace in all matching documents.
• start {number} An optional zero-based document start index.
• count {number} An optional count of the maximum number of documents to process.
• computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
• duplicateItems {boolean} An optional boolean value used to create duplicate items in the matching documents. See Duplicate items for details.

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Replace City and State with same values for all
  // matching documents.
  const response = await database.bulkReplaceItems({
    query: "Form = 'Contact' and LastName = 'Aardman'",
    replaceItems: {
      City: 'Chelmsford',
      State: 'MA',
    },
  });

  // response.documents is an array of objects -- one for each
  // document matching the query.
});

bulkReplaceItemsByUnid

Replaces selected items in multiple documents by UNID.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• replaceItemsByUnid {Array<string>} REQUIRED - An array of document objects. Each document object must include at least an @unid property.
• replaceItems {Object} An optional object containing items to replace in all matching documents.
• computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
• duplicateItems {boolean} An optional boolean value used to create duplicate items in the matching documents. See Duplicate items for details.

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);

  // Replace FirstName and LastName with different values
  // per document. Replace City and State with same values
  // for all documents.
  const response = await database.bulkReplaceItemsByUnid({
    replaceItemsByUnid: [
      {
        '@unid': 'F0C617C4AF746BED852582B9006819F9',
        FirstName: 'Aaron',
        LastName: 'Aardman',
      },
      {
        '@unid': '3EB633978241DD02852582B9006819FE',
        FirstName: 'Brian',
        LastName: 'Zelnick',
      },
    ],
    replaceItems: {
      City: 'Chelmsford',
      State: 'MA',
    },
  });

  // response.documents is an array of objects -- one for each document
  // in the replaceItemsByUnid array.
});

bulkReplaceDocumentsByUnid

Replaces multiple documents.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• documents {Array<Object>} REQUIRED - An array of documents to update. Each document object must include an @unid property.
• computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
• onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
• duplicateItems {boolean} An optional boolean value used to create duplicate items in the matching documents. See Duplicate items for details.

Return Value

{Promise<Object>} A promise resolved with a BulkResponse object.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const response = await database.bulkReplaceDocumentsByUnid({
    documents: [
      {
        '@unid': 'F0C617C4AF746BED852582B9006819F9',
        Form: 'Contact',
        FirstName: 'Aaron',
        LastName: 'Aardman',
        City: 'Arlington',
        State: 'MA',
      },
      {
        '@unid': '3EB633978241DD02852582B9006819FE',
        Form: 'Contact',
        FirstName: 'Brian',
        LastName: 'Aardman',
        City: 'Andover',
        State: 'MA',
      },
    ],
  });

  // response.documents is an array of objects -- one for each
  // document in the documents array.
});

explainQuery

Explains how a query string is processed.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• query {string} REQUIRED - A query string.
• queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.
• queryLimits {Object} An optional set of limits on the query. See bulkReadDocuments for details.

Return Value

{Promise<string>} A promise resolved with explanation string

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const explain = await database.explainQuery({
    query: "Form = 'Contact' and LastName = 'Aardman'",
  });

  // explain is a string explaining how the query was
  // processed on the server
});

exportDXL

Exports a Domino database to DXL.

Parameters

options {Object}

• accessToken {string} Optional - An optional access token. See Act-as-User for details.
• exportOptions {exportDxlOptions} An optional value that controls how the export is performed.

exportDXLOptions

exportDXLOptions are a set of constant values defined in constants.js that control how documents are exported.

• 'EXPORT_ALL' - This is the default value. Exports all documents from the database.
• 'EXPORT_DESIGN' - Exports all non-data documents from the database.

The following code snippet demonstrates how exportDXLOptions are passed to exportDXL:

  const result = await database.exportDXL({ exportOptions: exportDxlOptions.EXPORT_DESIGN });

Return Value

{Promise<Object>} A promise resolved with an EventEmitter object. Callers should implement the following events:

• .on('stream', (xmlStream) => {...} - xmlStream is a Stream class with the DXL data.
• .on('error_log', (errorLogStream) => {...} - errorLogStream is a Stream class with the XML error log when there are errors from the DXL Export operation.
• .on('error', (error) => {...} - error is a DominoDBError with the details of the error from the Domino server.
• .on('end', () => {...} - The final event to indicate that the export operation has completed.

Expect these possible sequence of events:

• A stream event, followed by an end event. This is a normal completion of the exportDXL() function. The xmlStream in the stream event is a Stream object with the DXL document from the export function.

• An error_log event when the DXL exporter encounters an error, followed by an error event with an error object. In this case, you may or may not receive a stream event. The errorLogStream is a Stream object with the detailed description of the export error in XML format.

• An error event. This indicates that the export request or the export operation failed. The error object has the details for the failure. It is possible to receive an error event without an error_log event, which means that the request failed before the export operation began.

Example

const { useServer } = require('@domino/domino-db');
const Promise = require('bluebird');
const fs = require('fs');

// This object contains the configuration details required to access the
// Domino server.
const serverConfig = {
  hostName: 'dev1',
  connection: {
    port: 3003,
    secure: true,
  },
  credentials: {
    rootCertificate: fs.readFileSync('rootca.crt'),
    clientCertificate: fs.readFileSync('app.crt'),
    clientKey: fs.readFileSync('app.key'),
  },
};

// Write stream to a file, be sure to close it.
const writeToFile = (stream, fileName) => {
  const file = fs.createWriteStream(fileName);
  return new Promise((resolve, reject) => {
    stream.on('end', () => file.close(resolve(file)));
    stream.on('error', (err) => file.close(reject(err)));
    stream.pipe(file);
  });
};

// This function takes the file name of a database on the Domino server. When
// called it creates the file called 'dxl.xml' with the DXL of the
// database. If there are export errors, then it creates the file 'err.xml'
// with details of the export errors.
const exportExample = async (filePath) => {
  const server = await useServer(serverConfig);
  const database = await server.useDatabase({ filePath });
  const exporter = await database.exportDXL({});

  return new Promise((resolve, reject) => {
    const fileProms = [];
    exporter.on('stream', (stream) =>
      fileProms.push(writeToFile(stream, 'dxl.xml')),
    );
    exporter.on('error_log', (stream) =>
      fileProms.push(writeToFile(stream, 'err.xml')),
    );
    exporter.on('error', (error) => reject(error));
    exporter.on('end', async () => {
      await Promise.all(fileProms);
      resolve({ result: 'done', proms: fileProms });
    });
  });
};

getServer

A getter function which returns a reference to the Server instance this Database is bound to.

Return Value

{Promise<Server>} A promise resolved with the Server class instance

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const databaseServer = await database.getServer();
  console.log(databaseServer === server); // true
});

getFilePath

A getter function which returns the database's path, relative to the data directory. This is a getter function for the value passed to Server::useDatabase when creating this Database class.

Return Value

{Promise<string>} A promise resolved with the path of the database

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
// { filePath: 'projects/foo/test.nsf' }
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const path = await database.getFilePath();
  console.log(path); // projects/foo/test.nsf
});

upsertDocument

UpsertDocument API Searches for a document matching a query string, then updates the selected items. If no document is found, creates a new document with the items instead.

Parameters

options {Object}

• accessToken {string} Optional - An optional access token. See Act-as-User for details.
• query {string} REQUIRED - The query to search the document. The search query must find one document. If it finds multiple documents, upsertDocument fails with NOT_UNIQUE_SEARCH error.
• document {document} REQUIRED - The document object which will be used for upsert operation.
• queryArgs {Array<Object>} Optional - An optional array of values to substitute in the query string. See Query arguments for details.
• queryLimits {Object} Optional - An optional set of limits on the query. See bulkReadDocuments for details.
• computeOptions {Object} Optional - An optional object specifying how to compute items on the specified documents. See Compute with form for details.

Return Value

{Promise<Document>} A Promise resolved with a Document.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async (server) => {
  const database = await server.useDatabase(databaseConfig);

  const contactDocument = {
    Form: 'Contact',
    FirstName: 'Joe', // same as contactDocument.FirstName
    LastName: 'Upser't'", // same as contactDocument.LastName
    City: 'Chelmsford', // Different than contactDocument.City
    State: 'MA', // same as contactDocument.State
  };

  const response = await database.upsertDocument({
    query: "Form = 'Contact' and LastName = 'Upsert'",
    upsertNote: contactDocument,
  });

  // response.document is document containing metadata
  // for document updated/created.
});

getACL

GetACL API returns ACL entries and roles for a given database. Uses a database file path relative to the Domino data directory. Application requires at least Read access to the database.

Parameters

options {Object}

• accessToken {string} Optional - An optional access token. See Act-as-User for details.

Return Value

{Promise<Object>} A Promise resolved with a AclResponse object.

Example

const { useServer } = require("@domino/domino-db");
const serverConfig = require("./server-config.js");
const databaseConfig = require("./database-config.js");

useServer(serverConfig).then(async (server) => {
  const database = await server.useDatabase(databaseConfig);

  const response = await database.getAcl();

  // response.aclEntryList contains ACL entry details.
  // response.roleList contains list of roles.
});

editAcl

The editAcl API is used to modify database ACL entries and roles. Use it to do the following operations:

1. Add roles to a database ACL.
2. Delete roles from a database ACL.
3. Upsert (update or insert) an entry in a database ACL.
4. Delete an entry in a database ACL.

The application-id or identity derived from the access token requires Manager access to the database.

Parameters

options {Object}

• accessToken {string} Optional - An optional access token. See Act-as-User for details.

Return Value

{Promise<AclEditor>} A promise resolved with the AclEditor class instance. Using this instance we can perform edit ACL operations.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async (server) => {
  const database = await server.useDatabase(databaseConfig);
  const aclEditorObj = await database.editAcl();

  aclEditorObj.addRole('[Role1]', '[Role2]', '[Role3]');
  aclEditorObj.deleteRole('[Role5]');
  const aclEntry = {
    name: 'CN=IAMAccessor/O=hclpnp',
    accessLevel: ACLEntryAccessLevel.MANAGER,
    type: ACLEntryType.PERSON,
    roleList: ['[Role1]'],
  };
  aclEditorObj.upsertEntry(aclEntry);
  aclEditorObj.deleteEntry('CN=user01/O=hclpnp');
  const response = await aclEditorObj.apply();
});

setACL

The setACL API deletes existing database ACL entries and roles and inserts new ones. On successful call to the API will result in database ACL having only passed roles and ACL entries. If permissions are not passed explicitly then default access level based permissions will be assigned.

The application-id or identity derived from the access token must have Manager access to the database.

Parameters

options {Object}

• entries {{Array.<AclEntry>}} REQUIRED - An array of unique ACLEntry objects.
• roles {Array.<string>} Optional - An optional array of unique database roles. Duplicate role names are ignored.
• accessToken {string} Optional - An optional access token. See Act-as-User for details.

Return Value

{Promise<undefined>} A Promise resolved with undefined.

The requirements to call setACL successfully are:

1. -Default- must be present in the entries parameter, otherwise the API throws an exception.
2. At least one ACL entry must have Manager access, otherwise the API throws an exception.
3. The roles parameter is optional. If specified AclEntry contains the role, then roles parameter is mandatory otherwise the API throws an exception. Role name comparison is case-sensitive.
4. Role names must be enclosed in [] brackets, e.g. [_ActAsUser].
5. Specifying permissions is optional. If not specified, default permissions are used. The following combinations of access level and permission are not allowed and throw an exception:

• Access level: No Access; permission: CREATE_DOCUMENTS
• Access level: NO Access or Depositor; Permission REPLICATE_OR_COPY_DOCUMENTS without READ_PUBLIC_DOCUMENTS

Caution - To allow the application that is adding entries to access the database after the ACL change other than through the -Default- access, pass its application-id in the entries parameters list.

AclEntry object

• name {string} REQUIRED - Name of ACL entry
• permissions {Array.<ACLEntryPermission>} Optional - An array of permissions
• accessLevel {ACLEntryAccessLevel} REQUIRED - An access level
• type {ACLEntryType} REQUIRED - ACL entry type
• roleList {Array.<string>} Optional - An array of entitled roles for given ACL entry, these roles will be enabled/checked.

ACLEntryPermission values

• CREATE_DOCUMENTS - Create documents
• DELETE_DOCUMENTS - Delete documents
• CREATE_PRIVATE_AGENTS - Create private agents
• CREATE_PERSONAL_FOLDERS_VIEWS - Create personal folders/views
• CREATE_SHARED_FOLDERS_VIEWS - Create shared folders/views
• CREATE_LOTUSSCRIPT_JAVA_AGENTS - Create LotusScript/Java agents
• READ_PUBLIC_DOCUMENTS - Read public documents
• WRITE_PUBLIC_DOCUMENTS - Write public documents
• REPLICATE_OR_COPY_DOCUMENTS - Replicate or copy documents

You can select REPLICATE_OR_COPY_DOCUMENTS permission for all access levels. However, for users with access levels of Depositor and 'No Access', you can only enable this if READ_PUBLIC_DOCUMENTS is also passed.

ACLEntryAccessLevel values

• NO_ACCESS
• DEPOSITOR
• READER
• AUTHOR
• EDITOR
• DESIGNER
• MANAGER

ACLEntryType values

• UNSPECIFIED
• PERSON
• SERVER
• MIXED_GROUP
• PERSON_GROUP
• SERVER_GROUP

Example-1 setACL without roles

In this example setACL API is called using certificate for 'CN=IAMAccessor/O=hclpnp' which currently has Manager access in the database ACL. After a successful call to this API, three ACL entries are created and all previous entries and roles are deleted.

const { useServer } = require("@domino/domino-db");
const serverConfig = require("./server-config.js");
const databaseConfig = require("./database-config.js");

useServer(serverConfig).then(async (server) => {
  const database = await server.useDatabase(databaseConfig);
  const response = await database.setAcl({
      entries: [
        {
          name: '-Default-',
          accessLevel: ACLEntryAccessLevel.NO_ACCESS,
          type: ACLEntryType.UNSPECIFIED,
        },
        {
          name: 'CN=IAMAccessor/O=hclpnp',
          accessLevel: ACLEntryAccessLevel.MANAGER,
          type: ACLEntryType.PERSON,
        },
        {
          name: 'CN=User1/O=hclpnp',
          accessLevel: ACLEntryAccessLevel.AUTHOR,
          type: ACLEntryType.PERSON,
        },
      ],
    });
  console.log(response);
}).catch((error) => {
    console.error('Exception:', error);
  });

Example-2 setACL with roles

In this example, setACL API is called using the certificate for 'CN=IAMAccessor/O=hclpnp' which currently has Manager access in the database ACL. After a successful call to this API, three ACL entries and three roles are created. 'Role1' is selected for 'CN=IAMAccessor/O=hclpnp' and 'Role2' is selected for 'CN=User1/O=hclpnp'.

const { useServer } = require("@domino/domino-db");
const serverConfig = require("./server-config.js");
const databaseConfig = require("./database-config.js");

useServer(serverConfig).then(async (server) => {
  const database = await server.useDatabase(databaseConfig);
  const response = await database.setAcl({
      roles:['[Role1]','[Role2]','[Role3]'],
      entries: [
        {
          name: '-Default-',
          accessLevel: ACLEntryAccessLevel.NO_ACCESS,
          type: ACLEntryType.UNSPECIFIED,
        },
        {
          name: 'CN=IAMAccessor/O=hclpnp',
          accessLevel: ACLEntryAccessLevel.MANAGER,
          type: ACLEntryType.PERSON,
          roleList:['[Role1]']
        },
        {
          name: 'CN=User1/O=hclpnp',
          accessLevel: ACLEntryAccessLevel.AUTHOR,
          type: ACLEntryType.PERSON,
          roleList:['[Role2]']
        },
      ],
    });
  console.log(response);
}).catch((error) => {
    console.error('Exception:', error);
  });

Troubleshooting

Following are the few known errors/exceptions and their cause.

Error: Proton (582)

Error message: You are not authorized to perform that operation

• Detail error info:

Appliation-id or identity derived from access token(callee) is not a Manager.

Error: Proton (1068)

Error message: Access control list must contain at least one Manager

• Detail error info:

None of the passed ACL entries has the access level Manager.

Error message: ACL Entry role should match with Database roles

• Detail error info:

Role name passed in roleList is not present in roles.
The role name comparison is case-sensitive.

Error message: ACL permission not supported

• Detail error info:

An ACL permission was passed that is not supported for the selected access level.
For example, specifying NO_ACCESS and the CREATE_DOCUMENTS permission causes this exception.

---

AclEditor class

A helper class for editing the ACL entries and roles on the database.

addRole

This function adds roles to a database ACL.

Parameters

• roles {{Array.<string>} Array of roles to be added. Role names cannot contain special characters, such as ~, !, @, # etc.

Return value

Returns the ACLEditor class object.

deleteRole

This function deletes roles from a database ACL.

Parameters

• roles {{Array.<string>} Array of roles to be deleted. Role names cannot contain special characters, such as ~, !, @, # etc.

Return value

Returns the ACLEditor class object.

upsertEntry

This function updates or inserts an entry in a database ACL.

Note:

When entry with the given name already exists:

• Access level will set to the level provided to API.
• Permissions will be changed according to the new access level and the permissions list provided to API. If no permissions are provided only default permissions for a particular access level will be set.
• If provided ACL entry has roles, only those roles will be enabled and all other roles will be disabled. Provided role list should include all roles that need to be enabled.

Parameters

entry {ACLEntry}

• ACLEntry to upsert on the database ACLs.

Return value

Returns the ACLEditor class object.

deleteEntry

This function deletes an entry from a database ACL.

Parameters

aclEntryName {string}

• Name of the ACL entry to delete.

Return value

Returns the ACLEditor class object.

apply

This functions applies changes to a database ACL.

Return value

{Promise<undefined>} A Promise resolved with a undefined.

---

Document class

You obtain an instance of Document by calling Database::useDocument. See below for a description of each Document function.

getDatabase

A getter function which returns a reference to the Database class instance that this Document is bound to

Return Value

{Promise<Server>} A promise resolved with the Database class instance

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  const myDatabase = await document.getDatabase();
  console.log(myDatabase === database); // true
});

getUnid

A getter function which returns the unid of the document. This is a getter function for the value passed to Database::useDocument when creating this Database class.

Return Value

{Promise<string>} A promise resolved with the unid of this document

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '5B5544335FA7D893852582C60003859A',
  });
  const documentUnid = await document.getUnid();
  console.log(documentUnid); // 5B5544335FA7D893852582C60003859A
});

read

Reads the specific document

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• itemNames {Array<string>} - Specifies the list of items expected in the response. For example, { itemNames: ['FirstName', 'LastName'] } requests items matching those item names. If the document includes items named EMail and Photo, they are not included in the response.
• computeOptions {Object} An optional object specifying how to compute items on the specified document. See Compute with form for details.
• readAttachmentSummaries {boolean} An optional boolean value specifying whether to read attachment summaries as described in @attachments.
• canonicalFormat {boolean} An optional boolean value used to return item properties in canonical format, as objects. See Reading items in canonical format for details.
• duplicateItems {boolean} An optional boolean value used to return duplicate items. See Duplicate items for details.

Return Value

{Promise<Object>} A promise resolved with the document retrieved from the Domino server.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  try {
    const myDocument = await document.read();
    /* myDocument:
        {
          @created  string
            The date the document was created.
          @modified string
            The last modification date of the document.
          @unid string
            The universal ID of the document.
          < * >:    {...}
        }
      */
  } catch (e) {
    // network Error or Domino Error
  }
});

readAttachmentStream

Reads attachments from the document

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are streamed. If not specified, ALL attachments are streamed.
• chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

{Promise<Object>} A promise resolved with a readable attachment stream. See Reading attachments for details on reading from the stream.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  try {
    // Read the attachment named photo.jpg
    const readable = await document.readAttachmentStream({
      fileNames: ['photo.jpg'],
    });

    // readable is a stream of attachments
  } catch (e) {
    // network Error or Domino Error
  }
});

readRichTextStream

Reads rich text data from the document

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• fields {Array<string>} REQUIRED - An array of rich text item names. Repeating items with the same name will be concatenated into a single stream without the data type word.
• chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used. The minimum and maximum possible is 1 and 64 respectively.

Return Value

{Promise<Object>} A promise resolved with a readable rich text stream. See Reading Rich Text for details on reading from the stream.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  try {
    // Read the attachment named photo.jpg
    const readable = await document.readRichTextStream({
      fields: ['body'],
    });

    // readable is a stream of rich text
  } catch (e) {
    // network Error or Domino Error
  }
});

replaceItems

Updates selected items in a document

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• replaceItems {Object} REQUIRED - A partial document object, the portion of the document to update
• computeOptions {Object} An optional object specifying how to compute items on the specified document. See Compute with form for details.
• duplicateItems {boolean} An optional boolean value used to create duplicate items in the document. See Duplicate items for details.

Return Value

{Promise<undefined>} A promise resolved with undefined

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  await document.replaceItems({
    replaceItems: { demoMessage: 'This is a demo message' },
  });
});

replace

Replaces all items in a document.

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• document {Object} REQUIRED - The new document contents
• computeOptions {Object} An optional object specifying how to compute items on the specified document. See Compute with form for details.
• duplicateItems {boolean} An optional boolean value used to create duplicate items in the document. See Duplicate items for details.

Return Value

{Promise<undefined>} A promise resolved with undefined

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  await document.replace({
    document: { demoMessage: 'This is a demo message' },
  });
});

delete

Deletes a document

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.

Return Value

{Promise<undefined>} A promise resolved with undefined

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  await document.delete();
});

deleteItems

Deletes selected items from the document

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• itemNames {Array<string>} REQUIRED - Specifies the list of items to delete. For example, { itemNames: ['FirstName', 'LastName'] } deletes items matching those item names. If the document includes items named EMail and Photo, they are not deleted.
• computeOptions {Object} An optional object specifying how to compute items on the specified document. See Compute with form for details.

Return Value

{Promise<undefined>} A promise resolved with undefined

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  document.deleteItems({
    itemNames: ['FirstName', 'LastName'],
  });
});

deleteAttachments

Deletes attachments from the document

Parameters

options {Object}

• accessToken {string} An optional access token. See Act-as-User for details.
• fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are deleted. If not specified, ALL attachments are deleted.

Return Value

{Promise<array<Object>>} A promise resolved with an array of objects. Each object is a summary of a deleted attachment.

Example

const { useServer } = require('@domino/domino-db');
const serverConfig = require('./server-config.js');
const databaseConfig = require('./database-config.js');

useServer(serverConfig).then(async server => {
  const database = await server.useDatabase(databaseConfig);
  const document = await database.useDocument({
    unid: '28438659F50E2637852582C600038599',
  });
  // Delete photo.jpg from the document
  const attachments = await document.deleteAttachments({
    fileNames: ['photo.jpg'],
  });

  // If photo.jpg was deleted, attachments is an array of
  // one object. The object is a summary of the deleted
  // attachment (fileName, fileSize, etc.).
});

---

BulkResponse class

Many functions return a promise that is resolved with a BulkResponse object. For example, bulkCreateDocuments, bulkReadDocuments, and bulkDeleteDocuments each return such a promise.

BulkResponse Properties

The format of the BulkResponse object is basically the same regardless of the operation:

• documents {Array<Object>} An array of objects representing the documents affected by the operation. The contents of each object depends on the operation.
• documentRange {Object} An object describing the range of documents affected by the operation. This property is undefined for a bulkCreateDocuments response.
  • start {number} The start index relative to the entire set.
  • count {number} The number of items in the documents array.
  • total {number} The total number of documents in the set. For example, for a bulkReadDocuments response, this is the total number of documents matching the given query. The value of count might be less than total.
• errors {number} The number of errors in the documents array.

Of course, the exact content of the object depends on the operation. See below for some sample responses.

BulkResponse Examples

Here's an example of a bulkCreateDocuments response (in JSON format). The response contains the UNIDs of the new documents and no errors:

{
  "documents": [
    {
      "@unid": "D586D2E2EE19F1F685258301006EEDFD"
    },
    {
      "@unid": "2569C7A4AD97F90785258301006EEDFE"
    }
  ],
  "errors": 0
}

Here's an example of a bulkReadDocuments response. Each object in the documents array contains metadata (@unid, @created, @modified) and document items (FirstName, LastName). There are no errors in the response:

{
  "documents": [
    {
      "@unid": "D586D2E2EE19F1F685258301006EEDFD",
      "@created": {
        "type": "datetime",
        "data": "2018-09-07T20:11:38.85Z"
      },
      "@modified": {
        "type": "datetime",
        "data": "2018-09-07T20:11:38.86Z"
      },
      "FirstName": "Sally",
      "LastName": "Smith"
    },
    {
      "@unid": "2569C7A4AD97F90785258301006EEDFE",
      "@created": {
        "type": "datetime",
        "data": "2018-09-07T20:11:38.86Z"
      },
      "@modified": {
        "type": "datetime",
        "data": "2018-09-07T20:11:38.88Z"
      },
      "FirstName": "Bob",
      "LastName": "Smith"
    }
  ],
  "documentRange": {
    "total": 2,
    "start": 0,
    "count": 2
  },
  "errors": 0
}

Here's an example of a bulkReadDocumentsByUnid response. The first object in the documents array contains metadata and document items. The second object indicates there was an error reading the document. In this case, the request included an invalid UNID:

{
  "documents": [
    {
      "@unid": "2569C7A4AD97F90785258301006EEDFE",
      "@created": {
        "type": "datetime",
        "data": "2018-09-07T20:11:38.86Z"
      },
      "@modified": {
        "type": "datetime",
        "data": "2018-09-07T20:11:38.88Z"
      },
      "FirstName": "Bob",
      "LastName": "Smith"
    },
    {
      "@error": {
        "message": "Proton (65541): Bad note UNID",
        "code": "ERR_BAD_REQUEST",
        "cause": {
          "name": "ProtonError",
          "code": 65541
        }
      }
    }
  ],
  "documentRange": {
    "total": 2,
    "start": 0,
    "count": 2
  },
  "errors": 1
}

It's important to understand, when errors > 0, the documents array contains at least one error. The error is represented by an @error property whose value is a DominoDbError object. The following sample code shows one way to filter the errors from the documents array.

const { errors, documents } = response;
if (errors) {
  documents.filter(document => document['@error']).forEach(error => {
    // Handle error
  });
}

---

Agent class

You obtain an instance of Agent by calling Database::useAgent. See below for a description of each Agent function.

run

Runs the named agent. See admin section for additional information about this feature.

There are two options that the caller may specify when calling Agent.run().

A document context which provides access to data between the caller and the agent. The caller may write data to a document. The agent can read that data when it runs and then in return may write additional data to the document which the caller may read. This is called the document context and its an optional parameter that the caller provides in the run options. The document is identified by it's unid. The agent code has access to this document via the AgentContext.

A document selection which provides a selection of documents to the agent as a target for the run. The agent code has access to the document selection as UnprocessedDocuments. There are two ways to specify a document selection.

1. The caller provides a list of unids.
2. The caller provides a query. The server executes the query before running the agent. The found set is then passed to the agent.

Parameters

options {Object} -- optional run parameters for invoking the agent.

• selection {Object} optional document selection criteria. Determines the list of selected documents that will be provided to the Agent as UnprocessedDocuments
  • search {Object} optional search parameters to be used for selecting documents
    • query {string} REQUIRED - A query string.
    • queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details.
    • queryLimits {Object} An optional set of limits on the query.
      • maxViewEntriesScanned {number} The maximum number of view entries to scan.
      • maxDocumentsScanned {number} The maximum number of documents to scan.
      • maxMilliSeconds {number} The maximum number of milliseconds to spend executing the query.
  • unids {Array<string>} optional array of UNIDs.
• context {Object} optional document that is provided to the Agent as AgentContext.
  • unid {string} The UNID of the agent context document.

You may provide either options.selection.search or options.selection.unids, but not both.

Return Value

{Promise<AgentRunResponse>} -- A promise that resolves with an AgentRunResponse object. This object does not have any properties, but it may in a future release.

Example

const { useServer } = require('@domino/domino-db');
const fs = require('fs');

const serverConfig = {
  hostName: 'dev1',
  connection: {
    port: 3003,
    secure: true,
  },
  credentials: {
    rootCertificate: fs.readFileSync('rootca.crt'),
    clientCertificate: fs.readFileSync('app.crt'),
    clientKey: fs.readFileSync('app.key'),
  },
};

const agentRunExample = async () => {
  // Initialize the Server, Database and Agent objects.
  const server = await useServer(serverConfig);
  const database = await server.useDatabase({ filePath: 'node-demo.nsf' });
  const agent = await database.useAgent({ name: 'agent-with-selection-java' });

  // Create the context document with data to pass to the agent.
  const contextUnid = await database.createDocument({
    document: {
      param1: 'aa',
      param2: 'bb',
    },
  });

  // Invoke the agent and provide the following:
  // * a DQL query to build the document selection that
  //   will be passed to the Agent.
  // * a context document that the agent can read/write
  await agent.run({
    selection: { search: { query: "State = 'VA'" } },
    context: { unid: contextUnid },
  });

  // Agent invocation is complete. Read the context document. The
  // sample agent updates the 'found_docs' item.

  const result = await database.bulkReadDocumentsByUnid({
    unids: [contextUnid],
    itemNames: ['found_docs'],
  });

  // Return the latest copy of the context document.
  const [doc] = result.documents;
  return doc;
};

---

DominoDbError class

When a domino-db function fails, it throws an instance of DominoDbError. You use following properties to determine the cause of the failure.

DominoDbError Properties

• name {string} Always equals 'DominoDbError'.
• code {string} A general error code. This string is never translated. Therefore your application can compare error code values in any locale. See Error codes for a complete list of codes.
• message {string} A description of the error. This string may be translated to the locale of the remote Domino server. Therefore your application should avoid displaying this string to an end user.
• cause {Object} The root cause of the error or undefined. When this property is defined, the value is usually a sub-class of Error. Examples include ProtonError and GrpcError. These objects can help determine the cause of a failure in a particular environment, but they should not be considered a fixed part of the domino-db interface. For any given error condition, a newer version of the domino-db module may expose a different cause object.
• stack {string} A backtrace of functions on the stack at the time this DominoDbError object was created.

Error codes

• 'ERR_BAD_REQUEST' - The request was malformed. For example, when reading view entries, options.count === 'foo' produces this error code because count is the wrong type.
• 'ERR_FORBIDDEN' - The server denied access to the requested resource.
• 'ERR_INTERNAL_ERROR' - An internal error occurred. This should happen relatively rarely.
• 'ERR_NOT_AUTHORIZED' - The request was not authenticated or the authenticated identity does not have access to the requested resource.
• 'ERR_NOT_CONNECTED' - The domino-db module could not connect to the target server.
• 'ERR_NOT_FOUND' - The requested resource could not be found.
• 'ERR_NOT_MODIFIED' - When conditionally reading a resource (e.g. options.ifModifiedSince), the resource has not been modified. Therefore there is nothing to read.
• 'ERR_PRECONDITION_FAILED' - When conditionally modifying a resource (e.g. options.ifUnmodifiedSince), the precondition failed. Therefore the operation failed.

FileSystemResponse object

The FileSystemResponse object contains the list of FileSystemEntry objects as follows:

• entries {Array.} List of FileSystemEntry objects

FileSystemEntry

The FileSystemEntry object contains database file or database directory information as follows:

• path {string} The path of the file or directory relative to the Domino data directory.
• title {string} A file title. Not required for a database directory.
• type {FileSystemEntryType} The file or directory type, one of the following:
  • DATABASE - Database file (.nsf)
  • TEMPLATE - Template file (.ntf)
  • MAILBOX - Mailbox file (.box)
  • DIRECTORY - Database directory
• size {int} The size of a file, 0 for a directory.
• createdDate {string} The creation date of a file or directory. modifiedDate {string} The last modified date of a file or directory.

FileSystemResponse Examples

{
  "entries": [
    {
        "path":"testdb.nsf",
        "title":"test database",
        "createdDate":"2021-02-23T09:02:41.798Z",
        "modifiedDate":"2021-02-23T09:02:41.798Z",
        "size":589824,
        "type" : FileSystemEntryType.DATABASE
   },
   {
        "path":"dbtemplate.ntf",
        "title":"test template",
        "createdDate":"2021-02-23T09:02:41.798Z",
        "modifiedDate":"2021-02-23T09:02:41.798Z",
        "size":589824,
        "type" : FileSystemEntryType.TEMPLATE
   },
   {
        "path":"test",
        "type" : FileSystemEntryType.DIRECTORY
   },
  ]
}

---

AclResponse class

GetACL returns a promise that is resolved with a AclResponse object.

AclResponse Properties

The format of the AclResponse object:

• aclEntryList {Array<AclEntry>} An array of AclEntry objects representing the ACL entry affected by the operation.
• roleList {Array<string>} List of database roles.

AclResponse Examples

Here's an example of a AclResponse response (in JSON format).

{
  aclEntryList: [
    {
      name: '-Default-',
      permissions: [Array],
      type: Symbol(PERSON),
      accessLevel: Symbol(MANAGER),
      roleList: []
    },
    {
      name: 'CN=IAMAccessor/O=hclpnp',
      permissions: [Array],
      type: Symbol(UNSPECIFIED),
      accessLevel: Symbol(MANAGER),
      roleList: []
    },
    {
      name: 'CN=testapp4/O=hclpnp',
      permissions: [Array],
      type: Symbol(PERSON),
      accessLevel: Symbol(MANAGER),
      roleList: []
    }
  ],
  roleList: [ '[testRole2]', '[testRole1]' ]
}

---