Stages Documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
711:scripting_advanced [2024/11/22 10:03] – created Weinlein, Thomas711:scripting_advanced [2025/04/04 11:58] (current) – [Advanced Scripting] Weinlein, Thomas
Line 1: Line 1:
-Necessary steps to enable usage of libraries and file access.+[[:711:scripting|Use Scripting]] 
 + 
 +====== Advanced Scripting ====== 
 + 
 +Some advanced reports and admin jobs might need to use additional Java library API to provide the requested functionality. As this might pose security risks, explicit whitelisting of such API is necessary. This can be done by providing a comma separated list of class names in the following configuration properties depending on the use case: 
 + 
 +Admin Jobs: ''adminjob.script.class.whitelist'' 
 + 
 +Reports: ''metrics.script.class.whitelist'' 
 + 
 +e.g. 
 + 
 +<code xml config.xml> 
 +<property name="metrics.script.class.whitelist" value="java.text.SimpleDateFormat,java.time" /> 
 +</code> 
 + 
 +Stages will prevent access to all other Java API and will log an error message indicating the unavailable class that needs whitelisting. 
 + 
 +File system access also needs explicit permission via configuration. 
 + 
 +Files to be accessible to Admin Jobs need to be stored in directories within ''$STAGES_ROOT/adminjob-data''. 
 +This base directory can be configured via an absolute path with configuration property ''adminjob.script.fileAccessBase''. 
 + 
 +Files to be accessible to Reports need to be stored in directories within ''$STAGES_ROOT/report-data''. This base directory can be configured via an absolute path with configuration property ''metrics.script.fileAccessBase''. 
 + 
 +e.g. 
 + 
 +<code xml config.xml> 
 +<property name="metrics.script.fileAccessBase" value="/home/stages/custom-report-data" /> 
 +</code> 
 + 
 +File read and/or write permissions are configured by the following configuration property. Please note that the file paths need to be specified **relative** to the **base directory** as shown above. 
 + 
 +Admin Jobs: 
 + 
 +''adminjob.script.fileAccess.readlist'' 
 + 
 +''adminjob.script.fileAccess.writelist'' 
 + 
 +Reports: 
 + 
 +''metrics.script.fileAccess.readlist'' 
 + 
 +''metrics.script.fileAccess.writelist'' 
 + 
 +For file access the script needs to use the following API: 
 + 
 +<code javascript> 
 +files.newInputStream(relativeFileName); 
 +files.newOutputStream(relativeFileName); 
 +</code> 
 + 
 +Please ensure the returned streams are **closed after usage**. 
 + 
 +e.g. 
 + 
 +<code javascript> 
 +var reader = new java.io.BufferedReader(new java.io.InputStreamReader(Files.newInputStream("report-data.csv"))); 
 +try { 
 +    while ((rline = reader.readLine()) != null) { 
 +        log.info(rline); 
 +    } 
 +} finally { 
 +    reader.close(); 
 +} 
 +</code>