Retrieving a Document (persistent.getDocument)

You can use persistent.getDocument to retrieve a specific document from the environments database using its unique identifier (id).

Syntax

persistent.getDocument(ddName, documentId, queryOptions);

Parameters

The getDocument function takes the following parameters:

Parameter	Type	Required	Description
ddName	String or null	Yes	If the value is null, BizzStream will use the name of the document from which the script was started.
documentId	String	Yes	The unique identifier (ID) of the document to retrieve.
queryOptions	Object	No	The options that can be used in the Mongo query. See Query options.

Query options

Query Parameter	Type	Description	Validation Rules
fields	object	Dictionary of fields to include or exclude. This is an object that contains the field names, each with the value 1 (include) or 0 (exclude). Use it to avoid loading large line blocks you do not need. A single line field can be listed as lineName.fieldName.	Field projection values must all be 1 or all be 0. _id and _hash cannot be excluded

A field list either includes or excludes, never both: give every field the value 1, or give every field the value 0. An empty field list ({ fields: {} }) returns the full document, the same as passing no options at all.

_id and _hash are always returned and cannot be excluded, so the result can be passed to persistent.saveDocument without losing the check that guards against overwriting concurrent changes. Fields that were not returned are left untouched by such a save. When a line field is listed, the id of the line is returned as well, so the line is updated rather than replaced when the document is saved back.

Return value

Returns an object representing the requested document if found. The structure of this document object is similar to the objects used when saving or finding documents. Returns an error if no document with the specified ID is found.

{
  "_id": "String id",
  "status": "ready",
  "accessGroups": [
    {
      "_id": ["OBJECT"],
      "memberUserIds": ["Array"],
      "memberGroupIds": ["Array"],
      "memberRelatedAccessGroupIds": []
    }
  ],
  "_documentDefinitionId": "String id",
  "_environmentId": "String id",
  "_createdByUserId": "String id",
  "_lastModifiedOn": "Date",
  "_createdOn": "Date",
  "_lastModifiedByUserId": "String id",
  "_hash": "String"
}

Examples

Retrieving a full document

The following example shows how to retrieve a document from the database by ID:

const doc = persistent.getDocument(serverDocument._documentDefinitionName, serverDocument._id)

if (doc) {
  console.log(doc);
  console.log('Retrieved order:', doc._environmentId);
} else {
  console.log('Order not found.');
}

Retrieving specific fields

The following example retrieves a project with only the fields that are needed:

const project = persistent.getDocument('project', serverDocument.projectId, {
  fields: {
    name: 1,
    description: 1
  }
});

// project contains name, description and the system fields; logLines is not loaded.
project.name = 'New name';
persistent.saveDocument('project', project);

Retrieving a single line field

The following example retrieves only the message field of the logLines line block. The id of each line is returned as well:

const project = persistent.getDocument('project', serverDocument.projectId, {
  fields: {
    'logLines.message': 1
  }
});

// project.logLines contains an object with _id and message for every line.

Leaving out a line block

The following example retrieves a project with everything except its logLines line block:

const project = persistent.getDocument('project', serverDocument.projectId, {
  fields: {
    logLines: 0
  }
});

// project contains every field of the project except logLines.