View Source

Understanding the Document Repository CRUD Tool

The Document Repository CRUD Tool uses MongoDB Javascript-based querying to perform actions like creating, updating, or deleting LLM-friendly MongoDB document style data in document repositories. For a similar tool that uses graphical-based querying on record type data created from traffic, see the Data Repository CRUD Tool. You can add it to a test or responder via the Add Output wizard (SOAtest or Virtualize) or as a standalone test in SOAtest.

Configuring the Document Repository CRUD Tool

The Document Repository CRUD Tool executes a MongoDB script to perform CRUD operations on the document repository. It has three built-in arguments: db, input, and context. When it is attached to a responder, there is a fourth built-in argument: request.

Typically, you will want to organize your script in three parts:

Part one extracts the relevant values from request, input, and context. Make sure the values are converted to the data type expected for the documents.
Part two executes commands on db to add, update, or perform other operations on the documents as necessary.
Part three retrieves the document whose content will become the input to tools chained to this one or, if attached to a responder, will be used as the data to compose the response.

Know the MongoDB version of the repository you are using and only use commands that your version supports.
Use javascript syntax that is supported by ECMAScript 5.1 (ES5). Do not use ES6-specific syntax (for example, spread notation).
Use var instead of const for values in the global scope.
Do not start a command in the global scope with return. The result of the last command in the script is automatically returned as the return value of the script.
Do not call db.dropDatabase() unless it is the last step of your workflow and the repository will no longer be used. If you need to remove all the documents and collections in the beginning or middle of your workflow, delete the collection one by one instead, like this:
for (const coll of db.getCollectionNames()) { db[coll].drop() }
Click Run the Script to test your script before deploying it.

Built-in Arguments

db

The db argument is the interface through which MongoDB script commands are performed on the document repository. Some examples include:

To create a collection named "items":
db.createCollection("items")
To add a document to the collection:
db.items.insertOne({ id: 1, name: "Wireless Headphones", price: 79.99 })
To retrieve a specific document:
db.items.findOne({ id: 1 })
To update a specific document:
db.items.updateOne({ id: 1 }, { $set: { price: 69.99 } })
To delete a specific document:
db.items.deleteOne({ id: 1 })

This argument supports most MongoDB script commands and options. For more information, refer to the official MongoDB documentation.

request

The request argument is a JSON object that contains the incoming request if this tool is attached to a responder. It includes the headers, the path parameters, the query parameters, and the body (converted to JSON). The JSON object looks like this:

    {
      "headers": {
        "Host": "localhost:9080",
        "Accept": "application/json"
      },
      "pathParams": {
        "accountId": "3455532744"
      },
      "queryParams": {
        "keyword": "Electronics",
        "limit": "25"
      },
      "body": {
        "startDate": "2026-01-01",
        "endDate": "2026-03-31"
      }
    }

input

The input argument is the content to which this tool is chained. For example, when the tool is chained to an Incoming Transport Header the value of input is the request header or, when it is chained to an Incoming Request, it's the request payload.

When the tool is used as a standalone test, the content is defined on the Input tab.

context

The context argument is an instance of ExtensionToolContext through which you can access suite variables and data banks. To learn more about ExtensionToolContext or ScriptingContext, go to Parasoft > Help or Help > Help Contents, depending on your installation, and look for the Extensibility API books.

Returning an Error Response

You can configure virtual assets that use a Document Repository CRUD Tool to return an HTTP error response when certain conditions exist in the repository. For example, you might want to see an "HTTP 404" error when an item does not exist in the repository. To do this:

Add a throw statement to your Document Repository CRUD Tool script in the format:
throw "<httpStatusCode>_<errorMessage>";
For example:
var item = db.items.findOne({ id: 1 }) if (item == null) { throw "404_Item does not exist"; }
Virtualize will put the HTTP status code and the error message into variables named crudToolErrorCode and crudToolErrorMessage.
Go to the Document Repository CRUD Tool's parent responder and confirm that Continue searching for a matching responder if data source correlation fails is enabled under Failover Options in the Data Source Correlation tab.
Add a new responder to the asset and in the Request Correlation tab, add an xpath on the Request Body like:
"404" = "${crudToolErrorCode}"
This will capture the request that failed over from the earlier responder. You can configure this responder further, just like any other responder. For example, you could configure the Return Status under the Options tab to use the variable crudToolErrorCode as the HTTP response code. See Message Responder Overview for more information about configuring responders.