Define a Scripted Algorithm

ClearTrial allows users licensed to Enterprise Edition and granted the Expert Algorithm Editor role to define algorithms using a scripting language.

This scripting language is based on a simplified subset of JavaScript and uses the JavaScript engine built into Java itself to evaluate the formulas you have composed. There are various websites on the internet available to learn more about JavaScript, but you only need to know how to use those features specific to writing algorithms.

• Although you do not need to be a software developer or expert in JavaScript, ClearTrial does recommend that you review some of the available tutorial websites.
• There are basic rules you should understand to use the scripting features; for example, JavaScript is case sensitive, so a variable name like "numEdits" is not the same variable as "numedits" for example.

• Arithmetic operations:
  • Addition (+)
  • Subtraction (-)
  • Multiplication (*)
  • Division (/)
• Conditional statements:
  • if / else if / else
  • Switch / case
• JavaScript comparison operators:

  >, >=, <, <=, ==, !=, ===

• JavaScript logical operators:
  • &&, ||
• JavaScript Math functions:
  • Use Math.round(x) to return the value of x rounded to its nearest integer; Math.round(1.6) returns 2
  • Use Math.floor(x) to return the value of x rounded downward to its nearest integer; Math.floor(1.6) returns 1
  • Use Math.ceil(x) to return the value of x rounded up to its nearest integer; Math.ceil(1.2) returns 2
  • Use Math.max() to find the highest value in a list of arguments; Math.max(5, 10, 15) returns 15
  • Use Math.min() to find the lowest value in a list of arguments; Math.min(5, 10, 15) returns 5
  • The following are less common Math functions that are valid to use in ClearTrial:
    • Use Math.sqrt(x) to return the square root of x; Math.sqrt(144) returns 12
    • Use Math.pow(x,y) to return the value of x to the power of y; Math.pow(8,2) returns 64
    • Use Math.exp to return e (Euler's number) raised to the power of the value provided as parameter; Math.exp(1) returns 2.718
    • Use Math.log to return the logarithm of the given parameter; Math.log(10) returns 2.303

Scripted algorithms can use any valid variable to help drive hours or costs.

A variable represents a ClearTrial work unit/cost driver or a custom assumption.

For example, the number of weeks between study start date and final report is represented by the variable name $numWeeks.

Over 200 ClearTrial variables are exposed to be used in a custom algorithms.

• The ClearTrial variables that can be used in a plan depend upon the plan's assigned Cost Model and Custom Field Model.

• All ClearTrial variables start with a dollar sign ($).

• Variables based on custom assumptions are defined by the Custom Field Designer.

• For a list of all the ClearTrial variables available as well as more information on working with expert algorithms, see the Script Variables Guide, available for download on the Oracle Help Center.

• For the list of user-defined variables, consult the Custom Field Model for the plan.

Example 1: You want to create a scripted algorithm to calculate the level of effort in hours for a user-defined resource based on the EDC maturity level selected for the plan. If the EDC maturity level selected is 1, then the level of effort should be 2 hours; if the level selected is 2, then the level of effort should be 1.5 hours; for any other selected level, the level of effort should be 0.5 hours.

1. On the Algorithm tab for the task/resource, click Switch to Script to switch into script mode.

2. Using the ClearTrial variable that exists for the EDC maturity level, $edcMaturityLevel, specify, in the script box, the conditional task/resource algorithm script to be:

   if (1 == $edcMaturityLevel) {2;}

   else if (2 == $edcMaturityLevel) {1.5;}

   else {.5;}

Example 2: You want to create a new user-defined cost for annual fees to be calculated as $1000 for each year of the plan after year 1.

1. On the Algorithm tab for the indirect cost, click Switch to Script to switch into script mode.

2. Using the ClearTrial variable that exists for the number of weeks between study start date and final report (e.g., study duration), $numWeeks, specify in the script box the cost algorithm script as:

   1000 * Math.ceil(($numWeeks / 52) - 1)

• Auto-formatting and Auto-completion
  ClearTrial automatically formats your algorithm script to make it easier to read and understand.
• Validation As You Type
  ClearTrial helps you write valid scripts by providing information about the script's validity and performance as you create it. This prevents you from saving scripts that will not execute properly.

Auto-formatting and Auto-completion

ClearTrial automatically formats your algorithm script to make it easier to read and understand.

• For each line of a scripted algorithm, a unique line number displays as the first character for the row. The first line number will always be "1," and each subsequent line number will follow sequential numbering logic.
• ClearTrial indents a new line automatically when the user inserts Enter after a leading brace.
• Variable name and keyword suggestions are provided with related descriptions, so that you can quickly find and select items from a pre-populated list to ensure you use valid variable names or keywords in the script.
  • You can click a selection from the pre-populated list and the selection will be inserted into the script.
  • When a pre-populated list is displayed, a description displays next to each list item.
• Because braces and brackets are often troublesome, when you place the cursor near a parenthesis, brace, or bracket ("(",")"," { ", "} "), the matching pair of braces, brackets, or parentheses is highlighted.

Validation As You Type

ClearTrial helps you write valid scripts by providing information about the script's validity and performance as you create it. This prevents you from saving scripts that will not execute properly.

Validation checks include:

• Scripts must be valid JavaScript whose last statement evaluates to the value desired.
• Scripts must only use the following JavaScript keywords: if, else, true, false, null, switch, case, break, and default.
• Scripts must not contain double or single quotes or any characters other than: upper or lowercase letters of the alphabet, numbers, dot, comma, mathematical operators (+,-,*,/,%), underscore, ?, :, ;, =, <, >, !, $, &, |, (, ), {, } , space, or newline.
• Scripts must not contain variables that are not defined/exposed with respect to the plan in which the scripts are created.

As you type your script, ClearTrial identifies any syntax that is invalid and highlights what has caused the error.

If the script is valid, ClearTrial provides an estimate of execution time, so you can adjust the run-time characteristics of your code.