Collections

Availability table

Controller availability
Module	Available
module.scripts
module.keycloak

collections controller

This controller expose operation to manipulate Collections

collections.delete(schema: string, documentId: string)

Delete a record from a collection by its document id.

The record is soft-deleted: it no longer appears in list() / get() results but can be brought back with restore().

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
documentId – Mongo _id of the record to delete.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the result of the query:

content.documentId (string) Mongo _id of the deleted record.
content.operation (string) the operation performed, here delete.

collections.deleteWithCustomFilter(schema: string, filter: string)

Delete every record matching a custom MongoDB filter.

Matching records are soft-deleted and can be brought back with restore().

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
filter – A MongoDB filter, given as a string, that may use the filter placeholder. See filter placeholder. Every record matching it is deleted.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the result of the query:

content.documentIds (array) Mongo _id of every deleted record.
content.operation (string) the operation performed, here delete.

collections.get(schema: string, documentId: string)

Fetch a single record of a collection by its Mongo document id.

The caller access-rights filters are applied, so a record that exists but is not readable by the caller is not returned.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
documentId – Mongo _id of the document to fetch.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the matching document itself (its fields, including _id). When no readable document matches the id, success is false and content is empty.

collections.getHistory(schema: string, documentId: string)

Get the history of every revision of a document.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
documentId – Mongo _id of the document whose revisions are requested.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the result of the query:

content.collections (array) every stored revision of the document linked with documentId.

collections.getUserAttributeFromPreferences(attribute: string, defaultValue?: any)

Get the value associated with an attribute from the preferences of the user that triggered the script.

The lookup only works when the script was started by a front-end action (a menu, a button, …), because it relies on the authenticated username. When the script runs without a user context, the preferences cannot be resolved and defaultValue is returned.

Arguments:

attribute – Name of the user-preference entry to read.
defaultValue – Optional value returned when the attribute cannot be resolved (unknown attribute, no authenticated user, or failed request). Defaults to null when not provided.

Returns:

Return the value of attribute from the preferences of the user that initiated the action which triggered the script (like pressing a button). If no value is found, defaultValue is returned instead; when defaultValue is not specified, null is returned.

collections.getUsername()

This method allow to get username of user that is authenticated and did an action that run the script. This information is accessible only if the script is trigger by a front-end action, like a menu for example. Otherwise, this will return an empty string.

Returns:: Return a string that represent username that triggered the script.

collections.getWithCustomFilter(schema: string, filter: string)

Same as get() but selects the record with a custom MongoDB filter string. The first record matching the filter (AND-ed with the caller access rights) is returned.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
filter – A MongoDB filter, given as a string, that may use the filter placeholder. See filter placeholder. An invalid filter fails the request with an invalid filter error.

Returns:

Same as get(): content holds the matching document, or is empty when nothing matches.

collections.getWithFilterId(schema: string, filter: string)

Same as get() but selects the record with a filter declared in the configuration instead of a document id. The first record matching the configured filter (within the caller access rights) is returned.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
filter – Id of the filter declared in the configuration of schema.collections or schema.ospp. An unknown id fails the request.

Returns:

Same as get(): content holds the matching document, or is empty when nothing matches.

collections.insert(schema: string, data: object)

Insert a new record into a collection.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
data – The document to insert, as an object. Values produced by the script are unwrapped before being stored.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the result of the query:

content.documentId (string) Mongo _id of the inserted record.
content.document (object) the stored document.
content.operation (string) the operation performed, here insert.

collections.insertMany(schema: string, data: object[])

Insert several records into a collection in a single request.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
data – The list of documents to insert. Each document’s script values are unwrapped before being stored.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the result of the query:

content.documentIds (array) Mongo _id of every inserted record, in insertion order.
content.operation (string) the operation performed, here insert.

collections.list(schema: string, pageSize: number, pageNumber: number, filterId?: string)

List the records of a collection, one page at a time.

Only records the caller is allowed to read are returned: the collection access-rights filters are always AND-ed with the query. By default only active records (not deleted, see delete()) are listed and the page is sorted by modified_at in descending order (most recently modified first).

An optional filterId further restricts the result to a filter declared in the schema configuration.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection. An unknown id fails the request with a schema is not defined error.
pageSize – Maximum number of documents returned for a single page (applied as a MongoDB $limit). content.collections never holds more than pageSize documents.
pageNumber – Zero-based index of the page to return. Documents are skipped using pageNumber * pageSize (MongoDB $skip): 0 returns the first page, 1 the second, and so on.
filterId – Optional id of a filter declared in the schema.collections / schema.ospp configuration. When provided, its query (and scope) is combined with the access-rights filters; when omitted, every readable active record is listed.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the result of the query:

content.totalCount (number) total number of records matching the filter, independent of pageSize and pageNumber.
content.collections (array) the documents of the requested page.

collections.listCustomFilter(schema: string, pageSize: number, pageNumber: number, filter: string)

Same as list() but the page is filtered with a custom MongoDB query string instead of a configured filter id.

The custom filter is AND-ed with the caller access-rights filters. Only active records are returned and the page is sorted by modified_at descending, exactly like list().

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection. An unknown id fails the request with a schema is not defined error.
pageSize – Maximum number of documents returned for a single page (applied as a MongoDB $limit).
pageNumber – Zero-based index of the page to return. Documents are skipped using pageNumber * pageSize (MongoDB $skip).
filter – A MongoDB filter, given as a string, that may use the filter placeholder. See filter placeholder. An invalid filter fails the request with an invalid filter error.

Returns:

Same as list(): content.totalCount and content.collections.

collections.restore(schema: string, documentId: string)

Restore a previously deleted record of a collection, making it active again (reverse of delete()).

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
documentId – Mongo _id of the record to restore.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the result of the query:

content.documentId (string) Mongo _id of the restored record.
content.operation (string) the operation performed, here update.

collections.update(schema: string, document: object)

Update a record by giving its complete object.

When document carries a non-empty _id, the matching record is updated; otherwise the object is inserted as a new record.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
document – The complete collection object. A non-empty _id triggers an update, its absence triggers an insert.

Returns:

Same as update().

collections.update(schema: string, documentId: string, data: object[])

Update the record identified by documentId by applying a list of field-level updates.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
documentId – Mongo _id of the record to update.
data – List of updates to apply on the record. Each entry is an object with three properties: field (the field to update), operation (the update operation to apply) and content (the value). Entries that miss any of these three properties are ignored. You can look at the collection documentation to see how to define an update object.

Returns:

Same as insert().

collections.updateMany(schema: string, filter: string, data: object[])

Apply the same list of field-level updates to every record matching a custom MongoDB filter.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
filter – A MongoDB filter, given as a string, that may use the filter placeholder. See filter placeholder. Every record matching it is updated.
data – List of updates to apply on every matching record. Each entry is an object with three properties: field (the field to update), operation (the update operation) and content (the value). Entries that miss any of these three properties are ignored. You can look at the collection documentation to see how to define an update object.

Returns:

An object with attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content (object) Data returned from a successful request.

Type of the data is different for each request type. Each operation presented below explain what you should expect from the content of the request

content holds the result of the query:

content.documentIds (array) Mongo _id of every updated record.
content.operation (string) the operation performed, here update.

collections.updateWithCustomFilter(schema: string, filter: string, data: object[])

Update the single record matching a custom MongoDB filter by applying a list of field-level updates.

Unlike updateMany(), the filter must match exactly one record: the request fails when no record matches and fails as well when several records match. Only active records readable by the caller are considered.

Arguments:

schema – Item ID of the schema.collections configuration identifying the target collection.
filter – A MongoDB filter, given as a string, that may use the filter placeholder. See filter placeholder. It must match exactly one record.
data – List of updates to apply on the matching record. Each entry is an object with three properties: field (the field to update), operation (the update operation) and content (the value). Entries that miss any of these three properties are ignored. You can look at the collection documentation to see how to define an update object.

Returns:

Same as insert().