Form Schema
The Form schema allows you to explore the form you are creating the script for. This provides vital information as you need to know the names of the fields and the structure of the objects so you can reference them in your scripts.
![Form schema explorer in the Scripting Studio tools and settings pane.](img/UserScripting/FormSchema.png)
The Fields drop-down list at the top gives a complete list of the available fields on the form. You can select between View by param or View by label by clicking on the link.
-
If View by label is selected (default), each entry in the drop-down list has the following format:
Label [Field] <Data Type>
-
Budget (hours) is the label the user sees on the form.
-
Budget_time is the field name you need to use when calling NSOA Functions.
-
Number is the internal data type JavaScript will use for a variable created for this field. See Dynamic Data Types.
-
-
If View by param is selected, each entry in the drop-down list has the following format:
Field [Label] <Data Type>
-
Budget_time is the field name you need to use when calling NSOA Functions.
-
Budget (hours) is the label the user sees on the form.
-
Number is the internal data type JavaScript will use for a variable created for this field. See Dynamic Data Types.
-
If you have added a new custom field and this is not listed in the Form schema, open the form with the new custom field to refresh the custom field list, and then open the Scripting Studio again. See Custom Fields for more details.
When editing a form script associated with the Receipt form, the hidden fields Receipt subtype [subtype] <String> and Envelope [envelope_id] <Number> are available in addition to the fields visible on the form:
-
The subtype field indicates whether the receipt is a Mileage receipt , a regular Receipt or Foreign currency receipt. The receipt subtype is determined by the type of the associated expense item.
-
The function NSOA.form.getValue(‘subtype’) will return a string with the value ‘M’ if it is a Mileage receipt, and ‘R’ otherwise (regular Receipt or Foreign currency receipt.
-
The functions NSOA.form.getOldRecord() and NSOA.form.getNewRecord() will return an object of type oaTicket with the associated expense item referenced by ID oaTicket.item_id. You can also use the item type field oaItem.type to determine the subtype of a receipt.
-
-
The envelope_id field is the ID of the envelope the receipt is associated to.
-
The function NSOA.form.getValue(‘envelope_id’) will return the envelope ID.
-
The functions NSOA.form.getOldRecord() and NSOA.form.getNewRecord() will return an object of type oaTicket with the associated envelope referenced by ID oaTicket.envelopeid.
-
When you select a field from the drop down list the Data structure/types & Examples area is filled.
The Data structure/types & Examples area has two text fields.
![Field data type information in the Scripting Studio tools and settings pane.](img/UserScripting/FormSchemaDataType.png)
The text field on the left shows the data type or data structure (if the data type is an object) for the field. See Object Fields.
![Field-referencing code sample in the Scripting Studio tools and settings pane.](img/UserScripting/FormSchemaExamples.png)
The text field on the right shows correctly formatted code samples using the NSOA functions for the selected field. You can directly copy and paste these samples into your script. See Object Fields.
Object Fields
Fields with the Object type expose properties that allow you to access their internal data structure.
For example, consider the Loaded hourly cost form section.
![Loaded hourly cost selection on the Project properties form in OpenAir.](img/UserScripting/LoadedHourlyCost.png)
All these fields are exposed through one loaded_cost field <Object>.
Notice the way the Loaded hourly cost fields map to the data structure you need for your script.
![Field data structure and code samples for loaded hourly cost in the Scripting Studio tools and settings pane.](img/UserScripting/FormSchemaObject.png)
The data structure has three blocks that correspond to the three rows of fields in Loaded hourly cost form section.
Getting a value from an object field is a two step process:
-
First you need to get the object variable for the field:
var loaded_cost_obj = NSOA.form.getValue("loaded_cost");
-
Then you can use the object variable to get the value:
var value = loaded_cost_obj[0].cost_0;
You can combine these two steps into one line:
var value = NSOA.form.getValue("loaded_cost")[0].cost_0;
Take a closer look at the syntax: var value = loaded_cost_obj[0].cost_0.
Each row in the data structure is accessed in the same way as an array, that is, loaded_cost_obj[0] is this first row. Each column of the row is accessed by the field name that is loaded_cost_obj[0].cost_0 is the “Primary loaded cost” for the first row.
Remember Arrays are zero-based.
Take a closer look at the syntax: var value = NSOA.form.getValue("loaded_cost")[0].cost_0
Notice this is NSOA.form.getValue("loaded_cost") with [0].cost_0 appended.
This is referencing "loaded_cost" in the same way as a simple field and then using [0].cost_0 to view the required property of the returned object.