Pre-Defined JavaScript Functions

CA Service Catalog provides several options for performing automated tasks for fields in forms, including report data objects, JavaScript expressions, and JavaScript functions. This topic lists the predefined JavaScript functions and provides an overview of how you can optionally use them to automate tasks in fields.

Use the following guidelines to specify values for the operands used in several of the predefined JavaScript functions. For most functions, the first two operands in the following list are required and the remaining are optional. Verify the syntax for an individual function to see which operands apply to that function.

• For formId, specify the value of the _id attribute of the form on which you want to run the function.
• For _id, specify the value of the _id attribute of the element within that form on which you want to run the function.
• For name, value, and index, specify the value of these attributes for the element on which the function is being run.
• Additional operands are mentioned, as applicable, for specific functions. For example, the index attribute is applicable for certain elements only, such as a select group.

_.serviceoption.status( )

Returns the status of the line item to which the current form belongs. Use this function to specify form attributes dynamically depending on the status of the line item. For example, to hide certain form fields when their line status is completed, set their hidden attribute to “_.serviceoption.status() == 200”.

Note: You can also use this function to hide or disable a service option element. To do so, use this function in the hidden or disabled text box.

This function is also especially useful for Hold and Resume status. You can give reasons in text messages for both.

Note: This function does not take any parameters.

ca_fdDoFieldLookup(fieldId, reportId),

Runs the report data object, associates it to the lookup field, and copies the data returned to the matching fields on the form. You can use these actions to help populate fields based on user input to a report data object.

For fieldId, specify the value of the _id attribute of the lookup field.

For reportId, specify the value of the data object that you created earlier.

ca_reportQuery(reportId, variables, onSuccess, onFailure)

Runs a report data object (data object) that queries the data source (such as the MDB) for the data you specify and returns the results.

• For reportId, specify the data object that you want to query.
• For variables, specify the JavaScript map with the variable names and values. Examples include {“var1”:”foo”,”var2”:”bar”,”var3”:_.user.id}. These variables match the ones that you query in the report data object.
• For onSuccess, specify the JavaScript function to run when the query returns successfully. The onSuccess function must take one operand. This operand is set with an array of maps, each representing a row, returned by the query.
• For onFailure, specify the JavaScript function to run if the call fails.

You can prepopulate fields based on a report data object and JavaScript functions.

ca_fdValidateCC(credit card number, credit card type)

Validates the format of a credit card number entered by the user in a form you create.

ca_fdShowField(formId, _id)

Applies to a single field.

Finds the form (formId) and field (_id) specified. Also makes that field visible if it is not already visible.

ca_fdShowFields(formId, _ids)

Applies to multiple fields.

Finds the form (formId) and field (_ids) specified. Also makes the fields visible if they are not already visible.

The second parameter is an array containing the _ids of multiple fields on the form, as shown in the example for ca_fdHideFields(formId, _ids).

ca_fdHideField(formId, _id)

Applies to a single field.

Finds the form (formId) and field (_id) specified. Also hides that field if it is not already hidden.

ca_fdHideFields(formId, _ids)

Applies to multiple fields.

Finds the form (formId) and fields (_ids) specified. Also hides the fields if they are not already hidden.

The second parameter is an array containing the _ids of multiple fields on the form. For example, you want to hide both the first and last name fields on a form. Also, the _id of the form is name_form, and the _id values of the fields are first_name and last_name. In this case, use the following code:

ca_fdHideFields("name_form", ["first_name","last_name"]

ca_fdDisableField(formId, _id)

Applies to a single field.

Finds the form (formId) and field (_id) specified. Also disables the field if it is not already disabled.

ca_fdDisableFields(formId, _ids)

Applies to multiple fields.

Finds the form (formId) and fields (_ids) specified. Also disables the fields if they are not already disabled.

The second parameter is an array containing the _ids of multiple fields on the form, as shown in the example for ca_fdHideFields(formId, _ids).

ca_fdEnableField(formId, _id)

Applies to a single field.

Finds the form (formId) and field (_id) specified. Also enables the field if it is not already enabled.

ca_fdEnableFields(formId, _ids)

Applies to multiple fields.

Finds the form (formId) and fields (_ids) specified. Also enables the fields if they are not already enabled.

The second parameter is an array containing the _ids of multiple fields on the form, as shown in the example for ca_fdHideFields(formId, _ids).

ca_fdSelectOption(formId, _id, name, value) and ca_fdSelectOptionByIndex(formId, _id, index)

You can use either of these functions to select a value in a select box programmatically. These functions have the same effect, and differ only in how they are called:

• ca_fdSelectOption selects the option with the specified _id attribute, name, and value in the select field.
• ca_fdSelectOptionByIndex selects the option with the specified _id attribute and index value in the select field.

Consider the following examples:

Example 1

This example selects the first option in the select box. This example uses the following values:

• _id attribute of the form: form_id
• _id attribute of the select box: memory_select

  ca_fdSelectOption(‘form_id’, ‘memory_select’, 1) :
  

Example 2

This example selects the first option in the select box of the current form. This example uses the following values:

• _id attribute of the form: ca_fd.formId
• _id attribute of the select box: memory_select

  ca_fdSelectOption(ca_fd.formId, ‘memory_select’, 1) :
  

If the specified select box cannot be found, the call is ignored and no errors are reported.

Example 3

You can rewrite the previous examples with explicit values for the options, as follows:

ca_fdSelectOption(‘form_id’, ‘memory_select’, ‘option1’, ‘option1_value’), ca_fdSelectOption(ca_fd.formId, ‘memory_select’, ‘option1’, ‘option1_value’):

option1

Specifies the name of an option as it appears on the Forms Designer tree. The value of this option is option1_value.

ca_fdUnselectOption(formId, _id, name, value)

Unselects the option with specified name and value in select field with the corresponding _id attribute.

ca_fdUnselectOptionByIndex(formId, _id, index)

Unselects the option at corresponding index in select field with the corresponding _id attribute.

ca_fdUnselectAllOptions(formId, _id)

Unselects all options in the select field with the corresponding _id attribute.

ca_fdGetSelectedOptions(formId, _id)

Return ans array of integers indicating the indexes of the selected options.

ca_fdGetSelectedOptionValues (formId, _id)

Returns an array of strings indicating the values of the selected options. Select the first option value as follows:

ca_fdGetSelectedOptionValues(formId, _id)[0]

Select the second option value by changing the 0 to 1; select the third option value by changing the 1 to 2, and so forth.

This function is especially useful to use user input to prepopulate a select box.

ca_fdSelectRadio(formId, name, _id)

Selects radio with corresponding _id in radio group with corresponding name attribute.

ca_fdIsSelectRadio (formId, name, _id)

Returns whether the indicated radio is selected.

ca_fdSelectCheckBox(formId,_id)

Selects check box with corresponding _id attribute.

ca_fdUnselectCheckBox(formId, _id)

Clears the check box with corresponding _id attribute.

ca_fdIsSelectedCheckBox(formId,_id)

Returns whether the selected checkbox is selected.

ca_fdSetDateFieldValue(formId, _id, date) and related functions

Sets the value of the specified date field with corresponding _id attribute. This function can take Null, String, or Long integer values for the parameter named date.

To clear the value of the field, use empty string and null.

Specify nonempty strings in the format specified for the Date Time field (an element of the form), as follows:

• If the time portion of the Date Time field is hidden, specify the strings in date format only. Use either the format attribute of the Date Time field or the Date format of the business unit.
• If the time portion of the Date Time field is visible, specify the strings in the date and time format specified by that field.

In both cases, separate multiple strings with a space.

Related JavaScript functions for setting the date are as follows. The previous text for the ca_fdSetDateFieldValue(formId, _id, date) function also applies to these functions.

• ca_fdSetDateFieldMinValue(formId, _id, date) – Sets the minimum value of the date.
• ca_fdSetDateFieldMaxValue(formId, _id, date) – Sets the maximum value of the date.

In addition, for all ca_fdSetDateField* JavaScript functions, you can set the date in the number of milliseconds since the "epoch." The epoch is the standard base time of midnight (00:00:00) GMT, January 1 1970. For details, about setting the date in this manner, see your standard Java programming reference, for example, the Oracle website, oracle.com.

ca_fdGetDateFieldValue(formId, _id, date) and related functions

Gets the value of the specified date field as a string formatted according to the specified formatting for the date field.

The information about the Date Time field for the previous function (ca_fdSetDateFieldValue(formId, _id, date)) also applies to this function.

Related JavaScript functions for getting the date are as follows. The previous text for the ca_fdGetDateFieldValue(formId, _id, date) function also applies to these functions.

• ca_fdGetDateFieldValueInMillis(formId, _id, date) – Gets the value of the date in milliseconds.
• ca_fdGetDateFieldMinValue(formId, _id, date) – Gets the minimum value of the date.
• ca_fdGetDateFieldMinValueInMillis(formId, _id, date) – Gets the minimum value of the date in milliseconds.
• ca_fdGetDateFieldMaxValue(formId, _id, date) – Gets the maximum value of the date.
• ca_fdGetDateFieldMaxValueInMillis(formId, _id, date) – Gets the maximum value of the date in milliseconds.

In addition, for all ca_fdGetDateField* JavaScript functions, you can get the date in the number of milliseconds since the "epoch." The epoch is the standard base time of midnight (00:00:00) GMT, January 1 1970. For details, about getting the date in this manner, see your standard Java programming reference, for example, the Oracle website, oracle.com.

ca_fdSetTextFieldValue(formId, _id, text)

Sets text of text field with corresponding _id attribute, which can be text field and text area.

ca_fdGetTextFieldValue(formId, _id)

Gets text of text field with corresponding _id attribute, which can be text field and text area.

ca_fdFetchSelectData(formId,_id)

Causes the select box with the _id specified to fetch the report data object again. This function is especially useful when the report data object takes user input into account. As a best practice, invoke this function when that input changes, to help ensure that the select box displays the correct data.

This function is also especially useful to use user input to prepopulate a select box.

The following functions are for system forms only:

• custom_onPriorityChange(newPriority)
• custom_onDateRequiredChange(newDateRequired)
• custom_onRequestedForChange(type, id, name, shippingAddress)