Use scripting with operations

How to use scripting features in parameters values

Values you put in operations parameters are provided with scripting capability.

When filling in a parameter value (like "value" parameter of "update property" in the case we want to update the title of the a document), there are three options:

• Title: there is no interpretation (default behavior), the parameter is taken "as is", which means that the title will be "Title".

• expr:Title starts with a "expr:". The system will interpret the value "Title" as a scripting expression. In that case it means that the value of the title will be updated with the content of the variable Title

• expr:The real @{Title}}: When there is the use of @{my_variable_name}} in a script expression, the expression between bracket is considered as a variable name and resolved as a string, and the whole expression is evaluated as the concatenation of the various substrings (included the one interpreted). In our case, if the Title variable is equal to "Jack is on the place", the title value will be "The real jack is on the place".

When the script is evaluated, you can use some contextual objects and some embeded functions.

Scripting context

• Document: The Document object represents the input document, when the operation takes a document as input. You can use it to get a property value of it:
  expr:Document["dc:title"]
  You can also use methods provided by the Document Wrapper, see below.

• variable_name: if you set a context variable in a previous operation, you can access it in the parameter value by just referring to its name. In the following sample, if there was a "SetVariable" before in the operation flow that put the path of a document in the variable "path_of_the_workspace", the parameter's value will be this path.
  expr:path_of_the_workspace

  Do not use "-" character in the variable name. Prefer the use of "_".

• Relative paths: each time you need to use a path expression (wether it is as a direct parameter of an operation, such as move, or in a an NXQL query, for STARTSWITH operator, you can leverage relative path capability:
  • "." will be replaced by path of input document
  • ".." will be replaced by path of parent of input document

• CurrentDate: you can use the CurrentDate object, that will provide various utility methods to get the current date value, see below 

• Context.principal.model.getPropertyValue("schema:field"): get current user property. By default users implements user.xsd schema. So if you want for instance the company name, Context.principal.model.getPropertyValue("user:company"). But if your users implements other schema, you choose your "schema prefix (or name if don't set) : field name"

Document Wrapper

The Document wrapper, used by the system for any document put in scripting context (whether under a variable name, or as the input document ("Document") provides serveral utility methods:

• Document.parent: returns a document wrapper of the parent of the document

• Document.workspace: returns a document wrapper of the parent workspace of the document

• Document.domain: returns a document wrapper of the parent domain of the document

• Document.path: returns a string representing the value of the path of the document, like "/default-domain/workspaces/my-workspace"

• Document.title: returns the title of the document

• Document.description: returns the description of the document

• Document.type: returns the Nuxeo EP Document type of the document (like "File", "Folder", ...)

• Document.lifeCycle: returns the current lifecycle state of the document

• Document.name: returns the name of the document (last part of the path)

• Document.versionLabel: returns the version name of the document (like "1.1"...).

Date Wrapper

The Date wrapper is useful to update documents' date properties and to build time-relative NXQL queries.

• CurrentDate.date: returns the date. It is the method to use to update a document date field, like "dc:valid", or whatever custom date field

Some other methods are provided to display the current date as a string:

• CurrentDate.format("java formating expression"): returns the current date in the specified format

• CurrentDate.time: returns the date in milliseconds

• CurrentDate.day: returns the day of the current time

• CurrentDate.month: returns the month of the current time

• CurrentDate.year: returns the year of the current time

• CurrentDate.hour: returns the hour of the current time

• CurrentDate.minut: returns the minut of the current time

• CurrentDate.second: returns the seconds of the current time

• CurrentDate.week: returns the week of the current time

Some others can be used when building an NXQL query to express dates relatively to the current date:

• CurrentDate.days(-3): returns the current date minus three days

• CurrentDate.years(10): returns the current date plus ten years

• CurrentDate.months(-5).weeks(2).seconds(23): returns the current date minus 5 Months plus two weeks and 23 seconds...

• ...

  If you want to work on a date that is hold by a property of your document, you first need to get a DateWrapper object, by using: @{Fn.calendar(Document["dc:created"])}. Ex: @{Fn.calendar(Document["dc:created"]).format("yyyy-MM-dd")}

Functions

The Functions object is providing a set of useful functions. This object is named Fn and provide the following functions:

• Fn.getNextId(String key) : get an unique value for the given key. Each time this function is called using the same key a different string will be returned.

• Fn.getVocabularyLabel(String vocabularyName, String key) : get a value from the named vocabulary that is associated with the given key.

• Fn.getPrincipal(String userName) : get a Nuxeo principal object for the given username string.

• Fn.getEmail(String userName) : get the e-mail of the given username

• Fn.getEmails(List<String> userNames) : get a list of e-mails for the given user name list.

• Fn.getPrincipalEmails(List<NuxeoPrincipal> principals) : the same as above bu the input object is a list of nuxeo principals.

Nuxeo Environment Properties

Nuxeo environment properties are accessible in scripts using the Env map object. All the properties defined in Nuxeo property files located in Nuxeo conf directory are available through the Env map. This is very useful when you want to parametrize your operations using values that can be modified later on a running server.

For example let say you want to make an operation that is creating a document and initialize its description from a Nuxeo property named automation.document.description.

In order to do this you should fetch the property using the Env map in your operation parameter: Env["automation.document.description"].

And then on the target server to create a property file inside the Nuxeo conf directory that defines the variable you are using in the operation chain:

automation.document.description = My Description

MVEL

The scripting language used is MVEL. See the MVEL language guide. You can use all the features of the scripting language itself.

For instance, you can use the substring method, when dealing with paths:
expr: Document.path.substring(26).

Testing if a variable is null:

More advanced Scripts

We will gather in this sections useful scripts so as to share experience on using scripting in automation, especially in the Run Script operation.