×

Please give details of the problem

Skip to content

Collections

A collection is a custom database that is created, populated, and managed as a persistent data storage for a customer account in support of one or more applications. It can host any kind of data, for example, on customers, products, or assets.

DigitalSuite relies on MongoDB as a storage engine with advanced querying and aggregation capabilities.

Collections and their configuration comprise the following settings and considerations, which are described in detail in the sections below:

Collection Identification

The following settings identify a collection in DigitalSuite:

  • Name: The name of the collection.

    Naming a collection is similar to naming a table in a relational database: The name should allow to identify the data stored in the collection and never be changed. It should consist of lowercase characters only, and not include special characters other than underscore (_), for example, expenses or customer_contracts.

  • ID: A generated number used to uniquely identify the collection.

  • URL: A generated URL relative to the DigitalSuite base URL (live.runmyprocess.com). The URL can be used, for example, to address the collection in REST API calls.

Collection Contents

A collection in MongoDB is similar to a table in a relational database. It groups documents of the same type. Documents are data structures consisting of field/value pairs similar to JSON objects, for example:

{ "name":"John", "age":30, "cars":[ "Ford", "BMW" ] }

A collection contains separate data for each execution mode of DigitalSuite. Although the data may be identical, this ensures that Live data is never mixed with Test or Acceptance data.

The data in a collection can be created, accessed, and manipulated using:

  • JavaScript in web interfaces.
  • FreeMarker functions in processes.
  • REST API calls from outside DigitalSuite.

An additional way to populate a collection is the import of files containing JSON objects or BSON, the native MongoDB format. The files need to be uploaded to DigitalSuite. Similarly, collections can be exported to DigitalSuite files in JSON and BSON format.

Web interface designers are provided with several widgets that allow for easy access and use of the data in collections. For example, the first level fields (keys) of a collection can be displayed as the columns of a collection report without any programming.

Accessibility

Access to a collection can be controlled by different settings:

  • Public or private: Public collections can be used without verification while users need to authenticate and have the required permissions to access private collections.

  • Read/write or read-only: Users may be allowed to read as well as write data in a collection, or to retrieve the data only.

  • Execution mode: Access for users can be restricted for one or more of the execution modes of DigitalSuite. A restriction for Test mode means that only users with a role with Designer rights in the collection's project are authorized to access the data. A restriction for Acceptance or Live mode means that the access is restricted to users assigned to a role with Supervisor rights. These restrictions do not apply to users with an Administrator profile, who can always access the data stored for all execution modes.

Best Practices

The following best practices and recommendations should be observed when working with collections.

  • Collections in DigitalSuite project structures:

    A collection should be created in the main project of an application. A separate administrative project should be used to implement a back office with a web interface and a custom widget to maintain and display the collection's contents. The main project should be included in the administrative project as a subproject.

    With this configuration, access can be controlled in a way that the users of the main project can access the collection in read-only mode, while administrators can update its contents.

    For more details, refer to the Developer Guide.

  • Data structures in collections:

    In principle, a collection may include differing data structures. However, this should be avoided for performance reasons.

  • Import and export:

    The native storage format in MongoDB is BSON, a binary JSON format. Whenever possible, BSON should be used for importing collections, as well as for exports for backup purposes or later re-import.

    An export to JSON format is preferable if the data is to be post-processed, for example, by means of a script.

    While it is technically possible to import/export a collection on a running application or process, it is best practice to stop all activities on the collection for the time it takes to perform the operation.

Limitations

DigitalSuite restricts the number and size of collections a customer can use in DigtialSuite. For details, refer to execution limits.

DigitalSuite Studio provides an immediate overview of the size of each collection and its contents.