Freemarker Functions for Collections

Table of Contents

Freemarker Functions for Collections

You can use Freemarker functions to access collections in any Freemarker script in your processes. In this section, the available functions are described including examples.

Adding an Object

${save_object(object, collection_name)}

Freemarker uses the collection name to identify the collection, JavaScript uses the collection ID instead (see JavaScript Methods for Collections).

Example:

<#assign first_name = "Mike">
<#assign last_name = "Tyson">
<#assign phone_number = "">

<#assign my_object>
{"first_name":"${first_name}","last_name":"${last_name}","phone_number":"${phone_number}"}
<!--#assign-->

${save_object(my_object,"client")}

Result:

{"phone_number":"","_id":{"$oid":"4f516cc91eff614bfc239289"},"last_name":"Tyson","first_name":"Mike"}

You will notice a field _id. Never perform requests based on this ID.

Mass Import of Objects From a CSV File

${import_objects(file_id, collection_name, {options} [, drop])}

Imports objects directly from an uploaded file with the identifier file_id into a collection named collection_name.

The first line of the files is used for the field names of the objects to be inserted:

first_name,last_name
John,Smith
Mike,Tyson

Additional options can be specified, for example, the separator parameter. The default separator is a comma (,).

All objects will be inserted into the collection as new objects.

If an error occurs during the import, the operation is stopped. Objects which have already been imported are kept in the collection.

If you want to drop the collection before the import, set the drop parameter to true.

The function returns the number of imported objects.

Example:

${import_objects("6852c8c0-a694-11de-b93f-123138017842", "clients",{"separator":","}, "true")}

Listing Objects

${list_objects( query, collection_name [, first_index [,limit]])}

Loads all objects matching the query (see Query Interface) from the collection collection_name.

To paginate the result, use the first_index and limit parameters. The number of returned objects is limited to 100.

The function returns a list of objects that match the query or an empty list.

Example 1:

${list_objects({},"clients",10,25)}

Lists 25 objects starting at the index 10.

Example 2:

<#assign first_name = "John">
<#assign my_pattern>
{"first_name":"${first_name}"}
<!--#assign-->

${list_objects(my_pattern,"clients")}

Retrieves all objects whose first_name is John.

The result of the list_objects function is only available within your script. It cannot be assigned directly to a process variable (see the inject_objects function). You need to manipulate the result to extract what you would like to persist in your process.

Example 3:

<#assign tmp=[]>
<#list list_objects({},"clients") as x>
<#assign tmp=tmp+[x.last_name]>
<!--#list-->
${tmp}

Loading a Single Object

${load_object( query, collection_name)}

The function is identical to list_objects, except that it returns only one result even if several objects match the query. The result is a JSON structure and not an array of JSON structures.

Counting Objects

${count_objects( query, collection_name)}

Counts the objects matching the query (see Query Interface) in the collection collection_name.

The function returns the number of objects matching the query.

Creating a Collection

${create_collection(collection_name [, is_public [, is_readonly]])}

Creates a collection named collection_name in the current project.

If is_public is specified and true, the collection is publicly accessible.

If is_readonly is specified and true, only read access is granted to users. Users with Supervisor or Designer access rights for the project will nevertheless be able to read and write objects in this collection.

You cannot use the same name for two collections, even if they are not in the same project.

The function returns true if the collection has been created, false otherwise.

Example:

${create_collection("clients","true","true")}

Dropping a Collection

${drop_collection(collection_name)}

Deletes the objects of the collection collection_name. All objects are deleted, but the collection is still known at the project level.

The function returns true if the collection has been dropped.

Deleting a Collection

${remove_collection(collection_name)}

Deletes the collection collection_name. All objects are deleted, and the collection is removed from the project.

The function returns true if the collection has been deleted.

Renaming a Collection

${rename_collection(collection_old_name, collection_new_name)}

Renames the collection collection-old-name to collection-new-name. You cannot use the same name for two collections, even if they are not in the same project. The function returns true if the collection has been renamed, false otherwise.

Be very careful in using this function. If you change the name of a collection, you need to update all processes and web interfaces that use it.

Updating Objects

${update_objects( query, object, collection_name [, multi])}

Updates the objects matching the query in the collection collection_name.

If multi is specified and true, all objects matching the query are updated. Otherwise, only the first one is updated.

Matching objects are completely replaced by the specified object document. To modify only a field value, use the update_field function.

The function returns the number of updated objects.

Example:

${update_objects({"last_name":"Smith"},  {"last_name":"Smith","first_name":"John"},"clients","false")}

Updating Specific Fields in Objects

${update_field( query, field_object, collection_name [, multi])}

Updates fields of objects matching the query in the collection collection_name. If multi is specified and true, all objects matching the query are updated. Otherwise, only the first one is updated. field_object is a partial object, containing only the fields to be modified.

The function returns the number of updated objects.

Example:

${update_field( {"first_name":"John"}, {"last_name":"Smith"}, "clients", "true"     )}

Deleting Objects

${remove_objects( query, collection_name)}

Removes objects from the collection collection_name. The objects to be removed are specified using a query. For details, refer to the MongoDB documentation.

The function returns the number of removed objects.

Example:

${remove_objects({},"clients")}

Removing Specific Fields in Objects

${remove_field( query, field_name, collection_name [, multi])}

Removes fields of objects matching the query in the collection collection_name. If multi is specified and true, all objects matching the query are updated. Otherwise, only the first one is updated. The field named field_name is removed from the objects.

The function returns the number of updated objects.

Example:

${remove_field( {"first_name":"John"}, "phone_number", "clients", "true" )}

Injecting Objects in Freemarker Variables

${inject_objects(objects [, field_name [,field_name] ...])}

Injects object values in the current computed parameters of the process. If no field-name parameters are specified, all fields are injected, otherwise only the specified fields are injected. objects may be a simple object, or an array of objects (the result of list_objects or load_object).

The function returns objects detached from the collection, visible in the computed parameters of the Datadocument in AWS S3 where you can find all internal, computed, and initial parameters of a process request.

Example:

<#assign tmp = list_objects({},"client")>
${inject_objects(tmp)}

Performing an Aggregation

aggregate_collection( collection_name,my_pipeline1[,my_pipeline2[,my_pipeline3[,my_pipeline4...]]])

Example: In the following example, the collection has the following fields and contents:

Fields: [first_name,last_name,state,nb_of_cars,nb_of_motors]

Contents:

If you want to display the number of cars per state for the people having 2 as number of motors, you have to build an aggregate expression and use a $match pipeline, then a $group pipeline. The grouping key should be the state. It is passed through the _id object. You use the $sum function to calculate the total number of cars per state.

<#assign my_pipeline1>
 {"$match":{"nb_of_motors":2}}
<!--#assign-->
<#assign my_pipeline2>
 {"$group":{"_id":{"State":"$state"},"Total":{"$sum":"$nb_of_cars"}}}
<!--#assign-->

$group,_id, and $sum are reserved words. $state and $nb_of_cars are the names of the fields in the collection.

To define which fields you want to project and show in the final result, you use the $project pipeline:

<#assign my_pipeline3>
 {"$project":{"STATE":"$_id.State","TOTAL_CARS":"$Total"}}
<!--#assign-->

As shown above, State must be prefixed by $_id as it is part of the grouping key.

You can also sort the result using a $sort pipeline:

<#assign my_pipeline4>
 {"$sort":{"STATE":1}}
<!--#assign-->

The final code is:

<#assign my_pipeline1>
 {"$match":{"nb_of_motors":2}}
<!--#assign-->
<#assign my_pipeline2>
 {"$group":{"_id":{"State":"$state"},"Total":{"$sum":"$nb_of_cars"}}}
<!--#assign-->
<#assign my_pipeline3>
 {"$project":{"STATE":"$_id.State","TOTAL_CARS":"$Total"}}
<!--#assign-->
<#assign my_pipeline4>
 {"$sort":{"STATE":1}}
<!--#assign-->

<#assign my_pipeline1 = my_pipeline1?eval>
<#assign my_pipeline2 = my_pipeline2?eval>
<#assign my_pipeline3 = my_pipeline3?eval>
<#assign my_pipeline4 = my_pipeline4?eval>

<#assign res=aggregate_collection("my_col",my_pipeline1,my_pipeline2,my_pipeline3,my_pipeline4)>
${res}