Calculated properties: play with entity references in JavaScript

Calculated properties are custom properties whose values are calculated from a formula. The formula can include the values of other properties, thereby creating dependencies between your properties. Library administrators can create calculated properties for all property types and in all types of library.

This article explains how to write advanced formulas for calculated properties using JavaScript.

Before you use this article, you should:

Learn about JavaScript syntax: 

JavaScript format of custom property values
          Simple properties
          Properties with an object representation
          Multi-value properties
          Handle property values that are empty or that have missing elements
JavaScript format of system property values
Extract the year, month and day from JavaScript dates
JavaScript format of other AODocs entities

 


JavaScript format of custom property values

Simple properties

Use this reference: property`Name of your property` for these simple property types: 

  • String/Text
  • Boolean
  • Integer
  • Decimal
  • Date, DateTime, Time

The table below indicates the format of the JavaScript values for each simple property type.

Note: Simple properties don't have elements (fields) such as .name, .type.

AODocs
property type

JavaScript
type

Examples: AODocs property
and JavaScript value

String/Text

String

text.png

JavaScript value: Flooding in loading bay

Boolean

Boolean

boolean.png

JavaScript value:true (can be true or false)

Integer

Number (integer)

integer.png

JavaScript value: 7

Decimal

Number (float)

decimal.png

JavaScript value: 2.5

Date 

DateTime

Time

Number (integer)

date.png

JavaScript value: 1483211100000

(number of milliseconds since January 1, 1970, 00:00:00 UTC)

For example, use the formula:

'The document : “' + systemProperty`Title` + '” of the project: “' + property`Project name` + '“, version: ' + property`Version number` + ' has been validated.'

to obtain the following result in your "Status" calculated String property: 

image01.png

Note: Learn how to handle properties without values (empty properties).

 

Properties with an object representation

The following properties have richer information and are represented by objects in JavaScript:

  • Person
  • Category
  • URL
  • Geopoint

JavaScript objects have elements (fields).

Format of the Person object

The table below indicates the format of the JavaScript Person object with its elements.

Person element

JavaScript object: type and example

What does it do?

value

JavaScript object: String

property`Approver`.value

Displays the email address of the approver

type

JavaScript object: String

property`Approver`.type

Displays the type of email address:

USER: if the email is an individual user address

GROUP: if the email is a Google group address

displayName

JavaScript object: String

property`Approver`.displayName

 

Displays the name of the user account or the Google group, for example:
Alice Adam or Bob's group

 

Format of the Category object

The table below indicates the format of the JavaScript Category object with its elements.

Category element

JavaScript object: type and example

What does it do?

id

JavaScript object: String 

property`Location`.id

Displays the category value ID, for example: R|17JIn4ju4sOOqJtT

name

JavaScript object: String 

property`Location`.name

Displays the category value, for example: Michigan

shortName

JavaScript object: String 

property`Location`.shorName

The category value short name, for example: MI

outdated

JavaScript object: Boolean 

property`Location`.outdated

true if the category value is outdated

false if the category value is not outdated

level

JavaScript object: Integer 

property`Location`.level

Index of the last level of the category structure that is filled in; starts at 0. For example, if "US/Nevada" is filled in for the "Location" category with the structure "Country/State/Town", the value is 1

levelName

JavaScript object: String 

property`Location`.levelName

Name of the last level of the category structure that is filled in. For example, if "US/Nevada" is filled in for the "Location" category with the structure "Country/State/Town", the value is Nevada

leaf

JavaScript object: Boolean

 

property`Location`.leaf

 

true if the value is a leaf (last level) of the category tree.

false if the value is not a leaf (last level) of the category tree.

For example, for the "Location" category with the structure "Country/State/Town", the value Wisconsin is a leaf if there are no towns defined in the library for Wisconsin.

path

JavaScript object: Array of category objects

See example below.

The array represents all the values that are filled in, from level 0 (in the example below, EMEA) to the last level filled in (Paris).

category.png

All category objects must have a path element and in the path array, the path element of each category object is null.

 

Below is an example of the path of a multi-level category.

{
   "id":"RzziTk7000000jEqmx",
   "name":"Paris",
   "shortName":null,
   "level":2,
   "levelName":"City",
   "leaf":true,
   "outdated":false,
   "path":[
      {
         "id":"RzziG5l000000trdlK",
         "name":"EMEA",
         "shortName":null,
         "level":0,
         "levelName":"Region",
         "leaf":false,
         "outdated":false,
         "path":null
      },
      {
         "id":"RzziNzO1ehM4y0ZYed",
         "name":"France",
         "shortName":null,
         "level":1,
         "levelName":"Country",
         "leaf":false,
         "outdated":false,
         "path":null
      },
      {
         "id":"RzziTk7000000jEqmx",
         "name":"Paris",
         "shortName":null,
         "level":2,
         "levelName":"City",
         "leaf":true,
         "outdated":false,
         "path":null
      }
   ]
}

path_image.png

 

 

Examples of formulas that reference Category properties:

  • "Type of Contract" is a single-value Category property with one level. Each value has a short name, for example, the category value "Services" has the short name "SV".

Use this formula to display the short name in your calculated String property:
property`Document Type`.shortName

Services.png

  • "Location" is a single-value Category property with three levels: Country (path[0]), State (path[1]), City (path[2]). Use this formula to display the State in a calculated String property: property`Location`.path[1].name

State.png

Note: If your category value is empty at the level defined (in this example, if the State level of the Location property is not filled in), an error occurs. Learn how to handle properties without values (empty properties).

Format of the URL object

The table below indicates the format of the JavaScript URL object with its elements.

Category element

JavaScript object: type and example

What does it do?

uri

JavaScript object: String 

property`Company website`.uri

Displays the URL, for example: https://www.aodocs.com/

displayText

JavaScript object: String 

property`Company website`.displayText

Displays URL display text, for example:

AODocs website

 

Format of the GeoPoint object

The table below indicates the format of the JavaScript GeoPoint object with its elements.

Category element

JavaScript object: type and example

What does it do?

latitude

JavaScript object: Decimal

property`Eiffel tower`.latitude

Displays the latitude value, for example: h48.858093

longitude

JavaScript object: Decimal

property`Eiffel tower`.longitude

Displays the longitude value, for example: 2.294694O

Note: Learn how to handle properties without values (empty properties).

Multi-value properties

Multi-value properties are represented as arrays. Each item of the array is represented as a mono-value of the property type.

Example 1:

Use the formula:

property`Suggestions`.length

to count the suggestions in your audit CAPA report listed in the multi-value String property named "Suggestions". The calculated property "Number of suggestions" shows the value 3. 

multivalue.png number_of_suggestions.png

Example 2:

Use the formula:

property`Product type`.map(a=>a.shortName).join(' - ')

to concatenate the short names of all the values of the multi-value category property named "Product type".

product_type.png   product_type_reference.png

Handle property values that are empty or that have missing elements

If your formula references a property that isn't filled in (it's empty) in your document, the property with an empty value is handled as follows: 

  • mono-value properties: empty values are represented as null

Note: A Boolean property is empty if it hasn't yet been edited. When edited for the first time, it becomes either true or false.

  • multi-value properties: the empty values are represented as an empty array [] 

Note: We recommend referencing only mandatory properties in your formula. However, you may want to handle empty properties within your formula if, for some reason, you don’t want to make the property mandatory or if documents are created by importing from Gmail, for example, and an approver hasn't been defined. Learn more:
Create documents from emails in Team Folders and Secured Folders (in Gmail)
Create documents from emails in Document Management libraries (in Gmail)

Example 1: empty properties – replace default with specific text

You created a calculated String property which references two properties. If either or both of these properties is empty, their values are null in the formula of the calculated property.

internal_publication_code.png

Use this formula to replace null by specific text. In this example, if the property "Published by" has a value, its displayName is used in the property "Internal publication code"; if the property "Published by" is empty, the text "No publisher defined" is displayed.

property`Published by`
? property`Published by`.displayName
: 'No publisher defined'
+' - '+property`Document ID`

no_publisher_defined.png

 

Example 2: missing short names in category values

You created a calculated property whose formula references a Category property using the element .shortName. Learn more: Format of the Category object

Some of your category values may not have short names. To ensure errors don't occur when you calculate your property, write a formula that displays the short name if it exists and displays the category name if the short name doesn’t exist.

Use this formula:

property`Type of Contract`.shortName
    ? property`Type of Contract`.shortName
    : property`Type of Contract`.name

Services.png
Short name defined for "Services" category value

 

Sales.png
No short name defined for "Sales" category value

 

 

Example 3: missing short names and empty properties

You created a calculated property using the element .shortName. Use this formula to handle the case where the property is empty and where some of your categories don't have short names. In this example, if the Category property "Type of Contract" has a value, its short name is used; if it doesn't have a short name, the name is used; if the property is empty, the text "Default" is used. 

property`Type of Contract`
  ? (property`Type of Contract`.shortName
    ? property`Type of Contract`.shortName
    : property`Type of Contract`.name)
  : 'Default'

default.png

Example 4: missing value and empty category in multi-level category

For the "Location" Category example above, use this formula to replace any missing State values or empty values with "No location".

(property`Location` && property`Location`.path[1])
        ? property`Location`.path[1].name
        : 'No location'
State_no_location.png

 

JavaScript format of system property values

System property values have a simple JavaScript format.

The table below indicates the format of the value for each system property.

System property

Description

id

String

The ID of the document

stateID

String

The ID of the workflow state

creationDate

Integer (Epoch milliseconds)

The date-time at which the document was created

title

String

The title of the document

stateChangeDate

Integer (Epoch millisecond)

The date-time at which the document last changed workflow state

 

Extract the year, month and day from JavaScript dates

Date property values are given in Epoch milliseconds. Learn more: Simple properties.

To extract the year, month or day from a date, add to your formula a function that “transforms” the Epoch milliseconds into a JavaScript Date and then identifies the item you want to use. 

Example 1: extract the year

'Year' + ' ' + new Date(systemProperty`stateChangeDate`).getFullYear():

Year.png

In this formula:

  • new Date(systemProperty`stateChangeDate`) transforms the property into a JavaScrip date 
  • .getFullYear(): identifies that you want to extract the year

Example 2: extract the month

'Month' + ' ' + (new Date(systemProperty`stateChangeDate`).getMonth()+1)

Month.png

Important: Months in JavaScript start at zero: January is 0, February is 1, and so on. As indicated in the example, you need to add +1 to the result of the .getMonth() function to get the correct month number!

Note: By default, single-digit months in JavaScript don't have a leading zero. If you want August (for example) to be 08 and not 8, use:
(new Date(systemProperty`stateChangeDate`).getMonth()+1).toString().padStart(2,'0')

Example 3: extract the day

'Day' + ' ' + new Date(systemProperty`stateChangeDate`).getDate()

Day.png

JavaScript format of other AODocs entities

The three sequence IDs (library, document class and document) are given as integers.

Learn more: Sequence IDs.

Category values and workflow states are given as simple IDs (Strings). For example: RzziPGBu6KcCb8C3oT.

Learn more: 

Was this article helpful? 0 out of 0 found this helpful
If you didn’t find what you were looking for, don’t hesitate to leave a comment!
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.