Skip to content

Saving a document asynchronously (persistent.saveDocumentLazy)

You can use persistent.saveDocumentLazy to save a document in the database. You can use this method to create a new document or to update an already existing document.

You can save documents via scripts in BizzStream in two different methods.

persistent.saveDocument: When a document is saved in a script, a REST call is executed in the background. The script only continues when the REST call returned a response.

persistent.saveDocumentLazy: The document will be saved after the script has been executed. BizzStream doesn't wait for a response because the script doesn't use the response. With this method you can save documents in scripts lazily so that the script execution time will be reduced.

You can use the following method in your script

persistent.saveDocumentLazy(ddName, document, overwritePrevious, async);
Parameter Type Required Description
ddName String Yes The name of the document definition. If the value is null, BizzStream will use the name of the document from which the script was started.
document Object Yes The JSON object that contains the document you wish to save. In case the document does not contain an _id-field or in case no document with the entered ID exists, a new document will be created. In the other case an existing document will be updated.
overwritePrevious Boolean No A boolean that indicates whether a previous version of the same document in the queue should be overwritten.
async Boolean No A boolean that indicates whether the document should be saved asynchronously after completing the script. By setting this parameter to true, you ensure that BizzStream places the document in a queue after completing the script. BizzStream will continue with the next rules in the action, while the documents in the queue are saved in the background.

Example

You can use the following method to save a document in BizzStream ID 2FwMgqxxPv6i4j8rc:

persistent.saveDocument("project",
    {   "_id":"2FwMgqxxPv6i4j8rc",
        "_documentDefinitionId":"iaK8uBLxDqmTJzYdL",
        "_environmentId":"a83rh4aX5nzBsGL3S",
        "accessGroups":[],
        "code":"12345",
        "name":"Constructing Highway",
        "companyId":"a6PbuPzkoRp3Czqcv",
        "externalId":"bdr:200¡adm:05¡prj:6"
    },
    false,
    false
);

This statement adds a document to a queue. Documents in the queue are saved on the application server when the script finishes. If you provide an ID for which no document exists, BizzStream throws an error.

The overwritePrevious parameter

If the overwritePrevious parameter is true and a previous version of the document is already in the queue, the previous version is removed and the new version is added to the back of the queue.

A previous version is available if:

  • There is a document, based on the same document definition, that has the same _id field.
  • There is a document, based on the same document definition, that has the same externalId field.
project.externalId = "12345";
project.code = "1000";

persistent.saveDocumentLazy("project", project);

project.code = "2000";

persistent.saveDocumentLazy("project", project, true);

This results in a 'queue' of 1 items: * Project

project.externalId = "12345";
project.code = "1000";

persistent.saveDocumentLazy("project", project);

project.code = "2000";

persistent.saveDocumentLazy("project", project, false);

This results in a queue of 2 items:

  • Project (version 1)
  • Project (version 2)

This can be desirable because of referencefield validations

Saving new documents

New documents are documents that do not have an _id or externalId field. New documents are always added to the queue, regardless of the value of the overwritePrevious parameter.

var project1 = {"name": "New project 1"};
persistent.saveDocumentLazy("project", project1, true);

var project2 = {"name": "New project 2"};
persistent.saveDocumentLazy("project", project2, true);

Results in a queue with two documents:

  • New project 1
  • New project 2

A couple of important notes:

  • Documents are saved in the order in which they are added to the queue. BizzStream uses First In, First Out.
  • If a document cannot be saved synchronously (validation fails), BizzStream will add the validation error to the log of the script execution and:
    • Does not store the remaining documents in the queue.
    • Will terminate the action so that the next rules are not executed.
  • If a document cannot be saved asynchronously (validaiton fails), BizzStream will add a validation error in a separate log entry. BizzStream continues to process the other documents in the queue and the action is not terminated.
  • If a document is sucessfully saved asynchronously, BizzStream adds the success message in a separate log entry.