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
<@com.text Text
<@com.picklist Picklist
<@com.picklistMultiple Multi-Picklist
<@com.number Numeric
<@com.richText Rich Text
<@com.range Range
<@com.quantity Quantity

 

List of reusable Reference Substance fields

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