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).

  1. The first table is a list of known IUCLID (“iuclid.”) in-built Reporting Functions which can be used at any time. Examples are provided per function.

  2. The second table outlines a set of IUCLID Field (data)types and the corresponding macro to use (coming from macros_common_general.ft, a common module available from GitHub ).

  3. The third table outlines a set of Reference Substance macros that can be called to fetch individual fields from the Reference Substance entity.

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(<path to repeatable block or a variable representing a repeatable list>, “<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 list 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>

 

List of reusable datatypes

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