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, 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")}
  

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")}
  

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. If an array is used for the orderby section, the order is maintained as values are inserted. Please refer to [MongoDB documentation](http://docs.mongodb.org/manual/core/read-operations/) for further information regarding queries.
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)}  
           ${list_objects( {"$query":{"a":2},"$orderby": [{"status":-1}, {"last_name":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