Create your own formulas: play with entity references in JavaScript

With AODocs, you can set up conditional logic in document classes in any type of AODocs library. When users edit their documents, conditional logic is applied as follows:

  • property values can be calculated automatically
  • properties can be conditionally mandatory or hidden
  • document titles can be calculated automatically (in Document Management libraries only)

Conditional logic is calculated using formulas that can include references to other entities such as custom or system properties, custom property states (mandatory or hidden) and the document title. 

Before you use this article, you should:

Use this article alongside the article Create your own formulas: use the correct JavaScript syntax for conditional logic to learn how to be creative with your conditional logic according to your specific business needs.

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: propertyType`Name of your property` where Type is one of 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 : “' + systemPropertyString`Title` + '” of the project: “' + propertyString`Project name` + '“, version: ' + propertyInteger`Version number` + ' has been validated.'

to obtain the following calculated value in your "Status" 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

propertyPerson`Approver`.value

Displays the email address of the approver

type

JavaScript object: String

propertyPerson`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

propertyPerson`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 

propertyCategory`Location`.id

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

name

JavaScript object: String 

propertyCategory`Location`.name

Displays the category value, for example: Michigan

shortName

JavaScript object: String 

propertyCategory`Location`.shorName

The category value short name, for example: MI

outdated

JavaScript object: Boolean 

propertyCategory`Location`.outdated

true if the category value is outdated

false if the category value is not outdated

level

JavaScript object: Integer 

propertyCategory`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 

propertyCategory`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

 

propertyCategory`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 as the calculated value of your String property:
propertyCategory`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 as the calculated value of your String property: propertyCategory`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 

propertyURL`Company website`.uri

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

displayText

JavaScript object: String 

propertyURL`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

propertyGeoPoint`Eiffel tower`.latitude

Displays the latitude value, for example: h48.858093

longitude

JavaScript object: Decimal

propertyGeoPoint`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. Also, Multi is added to the entity reference.

Example 1:

Use the formula:

propertyMultiString`Suggestions`.length

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

multivalue.png number_of_suggestions.png

Example 2:

Use the formula:

propertyMultiCategory`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 String property whose value is calculated. Its formula references two properties. If either or both of these properties is empty, their values are null in the result.

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.

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

no_publisher_defined.png

 

Example 2: missing short names in category values

You created a property whose value is calculated. Its 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:

propertyCategory`Type of Contract`.shortName
    ? propertyCategory`Type of Contract`.shortName
    : propertyCategory`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 property whose value is calculated 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. 

propertyCategory`Type of Contract`
  ? (propertyCategory`Type of Contract`.shortName
    ? propertyCategory`Type of Contract`.shortName
    : propertyCategory`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".

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

 

Example 5: missing value in Category properties

You created a String property named “Please, specify”, which you want to be displayed only when a user selects the value “Other“ in the Category property “Location”. You also want to handle the case when no location value is selected, which means the “Location” property is empty.

You can make the “Please, specify” property conditionally hidden with the following formula:

!(
propertyCategory`Location`
? (propertyCategory`Location`.id
=== categoryValue`Location:Other(Sb04Uwg000000V5flG)`)
: false
)

You can also use the JavaScript optional chaining operator ?. – learn more: Optional chaining. This returns the ID of the value selected in “Location” (if any) and otherwise returns undefined without triggering an error:

!(
propertyCategory`Location`?.id
=== categoryValue`Location:Other(Sb04Uwg000000V5flG)`
)

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

Syntax to reference the system property

id

String

The ID of the document

systemPropertyString`id`

stateID

String

The ID of the workflow state

systemPropertyString`stateId`

creationDate

Integer (Epoch milliseconds)

The date-time at which the document was created

systemPropertyDateTime`creationDate`

title

String

The title of the document

systemPropertyString`title`

stateChangeDate

Integer (Epoch millisecond)

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

systemPropertyDateTime`stateChangeDate`

 

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(systemPropertyDateTime`stateChangeDate`).getFullYear()

Year.png

In this formula:

  • new Date(systemPropertyDateTime`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(systemPropertyDateTime`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(systemPropertyDateTime`stateChangeDate`).getMonth()+1).toString().padStart(2,'0')

 

Example 3: extract the day

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

Day.png

JavaScript format of other AODocs entities

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

Learn more: Sequence IDs.

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

Learn more: 

Was this article helpful? 3 out of 3 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.