Collections

Functions for collections' management based on MongoDB

Methods

aggregate_collection(name, pipeline, pipelineX) → {array}

Run an aggregation query over a collection

Run an aggregation query over a collection. Aggregation is a powerful, yet sometimes complex, way to calculate aggregated values of a MongoDB collection. It is recommended to read with care the [MongoDB documentation](http://docs.mongodb.org/manual/applications/aggregation/ )
Parameters:
Name Type Argument Description
name string Name of a collection
pipeline object | array First pipeline. An aggregation requires at least one pipeline. This can be a single object or an array of objects, each object being a pipeline.
pipelineX object | array <optional>
Second and other optional pipelines. This can be a single object or an array of objects, each object being a pipeline.
Throws:
Invalid pipeline at position N
Returns:
The list of the documents, result of this aggregate (the system limits the result to the 1000 first documents).
Type
array
Example
${aggregate_collection('my_collection', {"$match":{"customerId":123456}},{"$group":{"_id":{"user":"$user"}}, "total":{"$sum":"$amount"}}, {"$project":{"user":"$_id.user", "total":"$total", "_id":0}},{"$sort":{"total":1}},{"$limit":100})}
  

count_objects(where, name) → {integer}

Count documents verifying a condition in a collection

Parameters:
Name Type Description
where object A where clause. Please refer to [MongoDB documentation](http://docs.mongodb.org/manual/core/read-operations/)
name string Name of a collection
Throws:
Cannot count objects with an empty condition.
Returns:
Number of documents matching the `where` clause
Type
integer

create_collection(name, is_public, is_readonly) → {boolean}

Create a new collection

Parameters:
Name Type Description
name string Name of a collection
is_public boolean If `true` the collection can be accessed publicly, without checking rights
is_readonly boolean If `true` the collection can only be modified by an administrator of the customer account
Returns:
Collection successfully created or not
Type
boolean

drop_collection(name) → {boolean}

Drop the content a collection

Drop the content of a collection: the collection still exists, but with an empty content. Use with care!
Parameters:
Name Type Description
name string Name of a collection
See:
  • collections#remove_collection
Returns:
Collection successfully dropped or not
Type
boolean

import_objects(file, name, options, drop) → {integer}

Import objects in a collection from a file

Parameters:
Name Type Argument Default Description
file string Reference of an uploaded file
name string Name of a collection
options object options to be used during the call, all values are optional
Properties
Name Type Argument Default Description
format string <optional>
CSV format of the file content, may be `CSV` or `JSON`
separator string <optional>
, separator between two values (for example `;` or `,`)
delimiter string <optional>
" delimiter used to allow values containing the separator character (for example `"` or `'`), to include a delimiter in a value, use two delimiters (`""` for example)
empty string <optional>
"" value to be used to represent an empty value (two separators in a row)
charset string <optional>
UTF-8 charset to be used to read the file content. More information about charset
parse_numbers array <optional>
array of names or indices (zero based) of columns containing numerical values that should be stored as numbers (double). Examples : `["age",3]` is asking the loader to parse column with header `"age"` and the fourth column.
parse_longs array <optional>
array of names or indices (zero based) of columns containing long values that should be stored as longs. Examples : `["age",3]` is asking the loader to parse column with header `"age"` and the fourth column.
trim boolean <optional>
`true` to trim values before inserting them in the collection. The trimmed value will be the parsed value, with any leading and trailing whitespace removed. Trimming also occurs before decoding numerical values. `false` to keep values unchanged.
drop boolean <optional>
false `true` to drop the collection if it already exists before the import. `false` otherwise (objects will be added to the existing collection)
See:
Throws:
Uploaded file X doesn't exist
Returns:
The number of imported objects.
Type
integer
Example
${import_objects( "95933380-75ec-11e2-8875-123139322be6","import_point_virgule",{"separator":";","delimiter":"\""},"true")}
      ${import_objects( "95933380-75ec-11e2-8875-123139322be6","import_point_virgule",{"separator":";","delimiter":"\"","empty":null},"true")}
  

import_objects(file, name, separator, drop) → {integer}

Import objects in a collection from a file

Parameters:
Name Type Argument Default Description
file string Reference of an uploaded file
name string Name of a collection
separator string <optional>
, Separator to be used during [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) parsing or an object to pass other configuration items
drop boolean <optional>
false `true` to drop the collection if it already exists before the import. `false` otherwise (objects will be added to the existing collection)
Deprecated:
  • Yes
See:
Throws:
Uploaded file X doesn't exist
Returns:
The number of imported objects.
Type
integer
Example
${import_objects( "95933380-75ec-11e2-8875-123139322be6","test_import_valeur_vide",",","true")}
      ${import_objects( "95933380-75ec-11e2-8875-123139322be6","import_virgule_sanscote",",","true")}
  

inject_objects(variable, filter) → {array}

Inject retrieved objects in the execution context of a request

Retrieved objects (using list_objects() or save_object()) are never retained in the process data document. So they will not be accessible in the next task. To be able to access objects in a future task, you have to inject them into the data document using this function.
Parameters:
Name Type Argument Default Description
variable string Name of the variable containing objects retrieved from a collection
filter string <optional>
no filter List (comma separated names) of the fields of `variable` objects that should be kept in the injected objects
See:
  • collections#save_object
  • collections#list_objects
Returns:
An array of injected objects. These objects will be kept in the process data document. Please be aware that a data document has a maximum size, if it grows bigger than that maximum size, the process will be stopped.
Type
array
Example
objects -> ${list_objects({},"my_collection")}
          injected_objects -> ${inject_objects(objects, "firstname", "lastname")}
  

list_objects(query, name, first, limit) → {array}

Retrieve objects from a collection

Parameters:
Name Type Argument Default Description
query object Query to filter objects to be retrieved. Please refer to [MongoDB documentation](http://docs.mongodb.org/manual/core/read-operations/)
name string Name of a collection
first integer <optional>
0 Index of the first object to be retrieved, used when results are paginated
limit integer <optional>
1000 Maximum number of objects to be retrieved, used when results are paginated. The maximum value is 1,000
See:
  • collections#load_object
Throws:
  • Unable to parse skip index or limit value
  • Cannot list objects with an empty condition
Returns:
An array of retrieved objects. Returned objects are not automatically inserted into the data document of the process. Please @see collections#inject_objects for further information.
Type
array
Example
${list_objects( {"a":{$gt:1}},"my_collection")}
           ${list_objects( {"$query":{"a":2},"$orderby":{"b":-1}},"my_collection", 30, 10)}  
  

load_object(where, name) → {object}

Load a document from a collection

Parameters:
Name Type Description
where object Query to retrieve the object. Please refer to [MongoDB documentation](http://docs.mongodb.org/manual/core/read-operations/)
name string Name of a collection
See:
  • collections#list_objects
Throws:
Cannot load an object with an empty condition
Returns:
One document matching the `where` clause; if several documents match the condition, then the first one resulting from the query is returned.
Type
object

R_create_index(id, name, keys, unique, ascending) → {boolean}

Creates indexes on collection

Parameters:
Name Type Argument Default Description
id integer id of the collection
name string Name of the index
keys array JSON Array of keys
unique boolean <optional>
false Creates a unique index so that the collection will not accept insertion of documents where the index key or keys match an existing value in the index. Specify true to create a unique index.
ascending boolean <optional>
true Create an index with ascending order
Returns:
The result of the create action (true or an error)
Type
boolean
Example
${R_create_index(108760, "myidx", ["attr1","attr2"], false, true)}
      Output: true
  

R_delete_index(id, name) → {boolean}

Remove index on a collection

Parameters:
Name Type Description
id integer id of the collection
name string Name of the index
Returns:
The result of the delete operation (true or false)
Type
boolean
Example
${R_delete_index(108760, "myidx")}
      Output: true
  

R_list_indexes(id) → {array}

List of all indexes on a collection

Parameters:
Name Type Description
id integer id of the collection
Returns:
JSON Array of indexes
Type
array
Example
${R_list_indexes(108760)}
      Output: [
        {
          "keys": [
            "_id"
          ],
          "unique": false,
          "name": "_id_",
          "ascending": true
        },
        {
          "keys": [
            "attr1",
            "attr2"
          ],
          "unique": true,
          "name": "myidx",
          "ascending": false
        }
      ]
  

remove_collection(name) → {boolean}

Remove a collection

Remove a collection: the collection, its configuration and all of its documents are deleted. Use with care!
Parameters:
Name Type Description
name string Name of a collection
See:
  • collections#drop_collection
Returns:
Collection successfully removed or not
Type
boolean

remove_field(where, fieldname, name, multi) → {integer}

Remove a field from documents matching a where clause

Parameters:
Name Type Argument Default Description
where object Query to retrieve the object. Please refer to [MongoDB documentation](http://docs.mongodb.org/manual/core/read-operations/)
fieldname string Name of a field in the documents of the target collection
name string Name of the target collection
multi boolean <optional>
false Advanced option. Modify only the first object retrieved (`false`) or all objects (`true`)
Returns:
Number of updated objects
Type
integer

remove_objects(where, name) → {integer}

Remove a subset of objects from a collection

Parameters:
Name Type Description
where object Query to retrieve the objects. Please refer to [MongoDB documentation](http://docs.mongodb.org/manual/core/read-operations/)
name string Name of the target collection
Throws:
Cannot remove objects with an empty condition
Returns:
Number of removed objects
Type
integer

rename_collection(old_name, new_name) → {boolean}

Rename a collection.

Parameters:
Name Type Description
old_name string Current name of the collection
new_name string New name of the collection
Returns:
Renaming successul or not. `false` if `old_name` doesn't designate an existing collection.
Type
boolean

save_object(object, name) → {object|array}

Save object(s) in a collection

Parameters:
Name Type Description
object object | array Object to be saved or an array of objects
name string Name of the target collection
See:
  • collections#inject_objects
Returns:
The object or array saved. The object or array may be different, since it's the representation of the objects returned by MongoDB, after insertion into the collection. Specifically, the `_id` field of the objects will be returned.
Type
object | array
Example
${save_object( {"a":1,"b":"a is one"},"my_collection")}
      ${save_object( [{"a":1,"b":"a is one"},{"a":2,"b":"a is two"}],"my_collection")} 
  

update_field(where, fieldname, name, multi) → {integer}

Update a field on a subset of the documents in a collection

Parameters:
Name Type Argument Default Description
where string Query to retrieve the objects. Please refer to [MongoDB documentation](http://docs.mongodb.org/manual/core/read-operations/)
fieldname string Name of a field in the documents of the target collection
name string Name of the target collection
multi boolean <optional>
false Advanced option. Modify only the first object retrieved (`false`) or all objects (`true`)
Throws:
Cannot update objects fields with an empty condition
Returns:
Number of objects updated
Type
integer

update_objects(where, variable, name, multi) → {integer}

Update a field on a subset of the documents in a collection

Parameters:
Name Type Argument Default Description
where string Query to retrieve the objects. Please refer to [MongoDB documentation](http://docs.mongodb.org/manual/core/read-operations/)
variable string -
name string Name of the target collection
multi boolean <optional>
false Advanced option. Modify only the first object retrieved (`false`) or all objects (`true`)
Throws:
  • Cannot update objects with an empty condition
  • Cannot update objects with a null object
Returns:
Number of objects updated
Type
integer