NSOA.form.setValue(field, value)

Use this command to set form values on the submit scripting event and to update values as part of the main form save, without needing to write WSAPI (SOAP) calls. The effect is the same as a user making manual changes to a field.

Full validation from your other scripts or rules is applied after the changes are made, ensuring your changes are safe. Form default values are applied before the script is run, and any permission rules or "After save" scripts are applied after the "On submit" script runs.

Error messages can be raised on the submit event. If errors are raised, the script will still run to completion, and the errors will be logged.

The function takes two parameters:

• The field you want to change

• The value to set in the field (either literal or variable)

The NSOA.form.setValue function supports the following field types: text, text area, date, numeric, currency, days, hours, ratio, checkbox, dropdown, dropdown and text, pick list and radio group. The following field types are not supported: password, sequence and multiple selection.

See Examples for individual use cases.

Parameters

• field {string} [required] — The name of the field on the form to set the value for

• value {permitted value type for field} [required] — The value to set in the field. May be text, numbers, date values or ISO-8601-formatted strings, the NSOA.form.getValue command, true or false, or null values, depending on the field affected.

Returns

True if the function was successful and false otherwise. If the function fails, it writes a descriptive message to the script log.

Units Limit

1 unit

Since

April 15, 2017

Examples

• Text field

  • This example enters a text string into a "Notes" field.

                      NSOA.form.setValue('notes', 'Note text here'); 
    
                    

  • To clear a text field, use an empty string in the second parameter.

                      NSOA.form.setValue('notes', ''); 
    
                    

    Note:

    The example above only uses single quotes, not double quotes.

    Setting the value to null clears the text field.

                      NSOA.form.setValue('notes', null); 
    
                    

    This example sets a “Notes” field using the getValue command.

    Note:

    NSOA.form.setValue supports both the new (prj_custpo_num__c) and old (custom_24) methods of referencing custom fields. When creating portable scripts, always use the new format for referencing custom fields.

                      NSOA.form.setValue('notes', NSOA.form.getValue('name')); 
    
                    

• Numeric field

  • Numeric values must be written using the base U.S. number format, for example, "23.67". Number values are displayed according to the user's settings in Regional Settings > Number format.

                      NSOA.form.setValue("prj_sales_rep_ratio_1__c", 23.67); 
    
                    

  • Use a null value to clear a numeric field using setValue.

                      NSOA.form.setValue("prj_sales_rep_ratio_1__c", null); 
    
                    

• Date field

  • SetValue can set the value of <date> fields using date values or ISO-8601-formatted strings, for example, YYYY-MM-DD. Date values are displayed according to the user's settings in Regional Settings > Date format.

                      NSOA.form.setValue('start_date', '2017-01-23'); 
    
                    

    Note:

    An error is logged when you attempt to set a date field with an invalid date string.

  • Use a null value to clear a date field:

                      NSOA.form.setValue('start_date', null); 
    
                    

• Checkbox field

  • Use true or false values to set checkboxes.

                      NSOA.form.setValue("active", true); 
    
                    

  • Use false to clear a checkbox:

                      NSOA.form.setValue("active", false); 
    
                    

    Note:

    If you use setValue to set a null value for a checkbox, an error will be logged.

• Dropdown / Dropdown and text field

  • To set a dropdown (or dropdown and text field) field value, use one of the values from the dropdown list, as it is displayed.

                      NSOA.form.setValue("currency", "EUR"); 
    
                    

    

  • Set the value to "Select ..." to clear any selected value.

                      NSOA.form.setValue("tax_location_id", "Select..."); 
    
                    

    

  • When using NSOA.form.setValue to set a value for a dropdown field, an error is logged if the value parameter is not one of the available dropdown options.

• Pick list field

  • Set the pick list field value by its internal identifier. Meta values are also supported — in the example below, the internal identifier for [Project owner] is —3.

    Tip:

    To find the internal identifier for meta values, you can use developer tools on your browser. Point to the pick list, right-click and select Inspect element to display the HTML for the pick list element. You can retrieve the name of the field from the name attribute of the <select> element and the internal identifier from the value attribute of the <option> element.

                      NSOA.form.setValue("ta_approver_choice", "-3"); 
    
                    

    

  • When using NSOA.form.setValue to set a value for a dropdown field, an error is logged if the value parameter is not one of the dropdown options.

  • Set the value to "BLANK" to clear any selected value.

                      NSOA.form.setValue("ta_approver_choice", "BLANK"); 
    
                    

  • An error is logged if the value parameter is not the internal identifier for one of the available pick list options.

• Radio group field

  • Set a radio group field value by the radio button name.

    Note:

    You can reference custom fields using the user-defined name — for example prj_radio_group_c — or the internal reference — for example custom_42. Always reference custom fields by their the user-defined names to create portable scripts.

                      NSOA.form.setValue("prj_radio_group_c", "three"); 
    
                    

    or

                      NSOA.form.setValue("custom_42", "three"); 
    
                    

    

  • Set the value to an empty string "" or to null to clear any selected value.

                      NSOA.form.setValue("prj_radio_group_c", ""); 
    
                    

    or

                      NSOA.form.setValue("prj_radio_group_c", null); 
    
                    

  • An error is logged if the value parameter is invalid. Radio button values, as displayed on the form, null and an empty string "" are the only valid values.