Report functions

This documentation is intended for IUCLID report builders only

General

This document outlines two types of out-of-the-box functions and macros which you can use when creating IUCLID Freemarker Report Templates (FTLs).

The first type of function is the in-built .iuclid function that can be passed to the FTL template. This in-built function is typically used to access the IUCLID data model.

The second type of function are Freemarker functions/macros which support the building of templates, for example to quickly call datatypes, or to get other repeatable elements.

List of in-built IUCLID functions

Level Function name “iuclid.” (with (<parameters>) to parse) Description
Entity iuclid.webUrl.entityView(<document variable>.documentKey)

Get the URL of the main Entity, such as a Substance or a Mixture.

Example get the parent entity URL for a study.
Note that in this case, the study is a variable capturing a list of studies under a certain parent node:

<#assign docUrl=iuclid.webUrl.entityView(study.documentKey)/>
${ docUrl }

 

Document iuclid.webUrl.documentView(<document variable>.documentKey)

Get the URL of a section document.

Example get the document URL for a study.
Note that in this case, the study is a variable capturing a list of studies under a certain parent node:

<#assign docUrl=iuclid.webUrl.documentView(study.documentKey) />
${ docUrl }

 

Entity and Document iuclid.getDocumentForKey(<IUCLID field path to reference>)

This function gets the Document key for either an Entity reference or Document reference.
The resulting key can be used to continue to extract IUCLID data from the linked Entity or Document.

Example get the reference substance name linked to a ‘SUBSTANCE’ document:
<#assign substance = _subject />

 

<#assign referenceSubstance = iuclid.getDocumentForKey(substance.ReferenceSubstance.ReferenceSubstance)/>

 

${referenceSubstance.ReferenceSubstanceName}

Entity and Document iuclid.getSectionDocumentsForParentKey(<root entity>.documentKey, "<document type>", "<document sub type") /

This function returns a section document key.

The function should be iterated using #list to fetch all section documents
under the relevant section node.

Example get a list of keys for all ‘FLEXIBLE_RECORD.IntermediateEffects’ documents.
(Note, the example uses '_subject' as the parent entity)
<#local resultStudyList = iuclid.getSectionDocumentsForParentKey

(_subject.documentKey, "FLEXIBLE_RECORD", "IntermediateEffects")/>

Sorting (Entity, Document, Repeatable block) iuclid.sortByField(<sequence that needs sorting>, “<IUCLID field path to picklist>”, <list of phrases in order of preference> />

This function sorts an order of returned values based on the order of picklist phrases
(also known as picklist items)
*Note that this does not work for multipicklists, only single picklists.

This function could condition a returned set of IUCLID Documents, e.g.:

  • Return based on an order of picklist phrases;
  • Return a set of repeatable block items sorted by an order of picklist phrases.

Example return a list of studies by the order of phrases assigned in:

  • AdministrativeData.PurposeFlag

*Note that ‘study’ represents a sequence of IUCLID endpoint documents, e.g. for ‘Explosiveness’:

<#assign returnList = iuclid.sortByField

(study, "AdministrativeData.PurposeFlag",["key study","supporting study","weight of evidence"])/>

Document iuclid.getHistoryForDocumentKey(<document variable>.documentKey)

This function gets the history of user modifications.

To get the list, you need to list through the Directive used to get the document key.

Example (get the history of a document):
<#assign historyList = iuclid.getHistoryForDocumentKey(document.documentKey) />

<#list historyList as history>

${ history.date }

</#list>

Field iuclid.localizedPhraseDefinitionFor(<field path>.code, locale)

This function gets the phrase definition of a picklist.

The returned value can then be used to get either (if content is available):

  1. The phrase name
  2. The ‘other:’ text value
  3. The phrase description
  4. The remarks value of the picklist

Example

  1. Get phrase text

<#assign localizedPhrase = iuclid.localizedPhraseDefinitionFor(picklistValue.code, locale) />

${localizedPhrase.text}

  1. Get other than-default language text

To get languages other than the default ‘locale’ (i.e. English), you do not use the above function.

Instead, you list through the:

  • localised texts (whether for a text or picklist field) to fetch the:
    • language (e.g. EN)
    • field value

Here is an example for "FLEXIBLE_RECORD.SDSInfoMixtures":
<#assign toxInfo = toxSDS.InformationOnMixtures.TradeNamesAndSafetyDataSheetsOfTheMixture.SDSsection11/>

<#if toxInfo.localizedTexts?has_content>

<#list toxInfo.localizedTexts as toxicologicalInformation>

<para>[<@com.text toxicologicalInformation.language/>]</para>

<para><@com.richText toxicologicalInformation.value/></para>

</#list>

</#if>

Field iuclid.getMetadataForAttachment(<path to attachment>)

This function gets the metadata object for an attachment in IUCLID.

The objects available are listed below, including the variable to use to extract that object:

  • File name (.filename)
  • Size of file (.size)
  • Media type [file extension] (.mediaType)
  • MD5 file that verifies the integrity of downloaded files (.md5)
  • Remarks given to attachment (.remarks)

Example 1 (get structural formula attachment data in reference substance):
<#assign attachmentData = iuclid.getMetadataForAttachment(chemicalStructure.StructureFile)/>

${attachmentData.filename}

Example 2a (get the image of a file, using:
iuclid.getContentForAttachment(< variable representing the attachment key>)
(to render the base64 string )

<mediaobject><imageobject>
<imagedata width="100%" scalefit="1"
fileref="data:${structuralFormula.mediaType};base64,${iuclid.getContentForAttachment(attachmentKey)}"
/>
</imageobject></mediaobject>

Example 2b (Get the multilingual text of an 'other' text field in a phrase)
<#local organsMultiLingual = item.Toxicity.AffectedOrgans/>

<#if item.Toxicity.AffectedOrgans.localizedTexts?has_content>

<#list organsMultiLingual.localizedTexts as organsAffected>

<para>

[<@com.text organsAffected.language/>]

</para>

<para>

Affected organs: <@com.text organsAffected.value/>;

</para>

</#list>

</#if>

Field .hasElement

The function .hasElement works with variables that point to IUCLID data structure elements such as IUCLID Blocks of Fields.

The function is useful in checking what should be included or excluded as part of a Freemarker #if condition.

For example, if you want to return the following field path element

  • SubstancePhysicalState

in the block:

  • ENDPOINT_STUDY_RECORD.GeneralInformation.ResultsAndDiscussion

<#list appearanceStudies as appearance>
<#list appearance.ResultsAndDiscussion
?children as child>
<#if child.hasElement("SubstancePhysicalState")>
<#return child>
</#if>
</#list>
</#list>

The .hasElement function is distinguished from the Freemarker ?has_content function as this checks if a variable is true or not and applies to any freemarker variable pointing to IUCLID documents, strings etc

Field iuclid.label for=<field path variable> var="<user-define variable name>"

This function is called to retrieve the IUCLID field label name (as shown in the user interface)

Example

<#list block?children as child>
<#if child.hasElement("AdditionalInformation")>
<@iuclid.label for=child var="addInfo"/>
${addInfo}
</#if>
</#list>

List of reusable datatypes (available when using macros_common_general.ftl, a common module available from GitHub)

Macro name to call Field (Data)Type in IUCLID
Text <@com.text
Picklist <@com.picklist
Multi-Picklist <@com.picklistMultiple
Numeric <@com.number
Rich Text <@com.richText
Range <@com.range
Quantity <@com.quantity
use this macro to call any of the above datatypes <@com.value

 

List of reusable Reference Substance fields

Macro name to call IUCLID field path
REFERENCE_SUBSTANCE.ReferenceSubstanceName <@com.referenceSubstanceName com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.MolecularStructuralInfo.MolecularFormula <@com.molecularFormula com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.MolecularStructuralInfo.MolecularWeightRange <@com.molecularWeight com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.MolecularStructuralInfo.ChemicalStructureFiles <@com.chemicalStructureFiles com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.MolecularStructuralInfo.InChl <@com.inchi com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.MolecularStructuralInfo.SmilesNotation <@com.smilesNotation com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.MolecularStructuralInfo.Remarks <@com.molecularStructuralRemarks com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.IupacName <@com.iupacName com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.Description <@com.description com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.Inventory.CASNumber <@com.casNumber com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.Synonyms.Synonyms <@com.synonyms com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>
REFERENCE_SUBSTANCE.Inventory.CASName <@com.casName com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>

(Reference substance confidentiality flag, note this is a node not a field path)

<@com.referenceSubstanceFlags com.getReferenceSubstanceKey
(<path to reference substance entity in parent document>)/>

 

List of in-built paths to get certain elements of data that are not provisioned for in the common modules

Name of built-in Mapping in IUCLID
${<documentNode>.name} Used to retrieve the name value given by a user for a document, such as the name given to a study summary or the name given to a dossier header
${<documentNode>.documentKey.uuid} Used to retrieve the UUID for a document

 

List of reusable node_types that are available under a document's element node

Name of node_type Mapping in IUCLID
data_protection Refers to Flags field, e.g. the field containing CBI flags
address  
integer  
address  
boolean Refers to fields that are ither true or false, for example the Key Result field in many Effec Levels' repeatable blocks
decimal  
date  
quantity  
range  
picklist_single Refers to a picklist (phrasegroup) in which only one phrase can be selected
picklist_multi Refers to a picklist (phrasegroup) in which more than one phrase can be selected
document_reference Refers to a single cross-reference with another document, for example a reference to a single Test Material
document_references Refers to cross-references to with (potentially) two or more other document's, for example, a reference to Additional Test Materials
attachment Refers to a single attachment, for example the Attached Justification in study summaries
attachments Refers to (potentially) two or more attachments, for example the attachments that can be added to the meta data of a Document
section_types  
repeatable Refers to a path to a repeatable block of information, such as an Effect Levels' repeatable block

 

Other types of data that can be retrieved by the Report Generator using the common module macros_common_general.ftl

Type of data retrieval

Description

sub entity

This function can be called to retrieve the sub-entity of a parent entity.

The function permits the user to retrieve one or, a combination of the following:

  • only the sub-entity
  • the parent entity of the sub-entity
  • the entities contained in the sub-entity

The sub entity UUID can be retrieved directly with:

${subEntityUuid}

To retrieve the sub-entity key in order to retrieve data from the sub-entity, you call from macros_common_general.ftl the following Directive:

<#assign subEntityKey = com.getSubEntityKey(subEntityUuid) />

From here, you can get the contents as needed, from the sub-entity, e.g.:

${subEntityKey.name}

inbound references

This function can be called from the common module 'macros_common_general' and retrieves the inbound reference(s) from a document or entity (i.e. the references being made to that document or entity)

Example

<#list com.inboundReferences(<sectionDocumentVariable>.documentKey) as inboundReferenceKey>
<#assign inboundReference = iuclid.getDocumentForKey(inboundReferenceKey) />
${inboundReferenceKey.name}

</#list>