Adding custom fields to a template

You can add custom fields to any of the default templates BMC Database Automation provides by editing the XML file in the Templates Repository. These custom fields appear in the relevant provisioning task in the Management Console.

Custom fields allow the following:

• Ability to define custom fields as having a list of possible values that appear in a list box. Input is validated.
• Ability to enable the selection of an ad-hoc value.
• NEW IN 8.9.02 (Applicable only for Oracle) Ability to define custom fields for the database options that appear on the Database Options page while adding a database.
• NEW IN 8.9.03 Ability to define custom fields for the scheduling options that can be set on the Scheduling page while running an action 

Custom field variables are assigned a  prefix, GAC_. For example, a parameter named responsible_dba would appear in the environment of the pre-provisioning and post-provisioning scripts as GAC_responsible_dba.

This topic provides information and instructions on adding custom fields to a template:

To add a general custom field to a template

1. Follow the steps in Editing templates.
2. Enter any of the custom fields found in the following example sections.
   The custom fields should be entered inside the root tag named defaults and outside of the editable and non-editable sections.
3. Type the custom field name.
4. Specify whether the field is required (true or false) and whether the field is editable or non-editable.
   Tags that are not specified appear as blank, optional and editable. You can require the user to enter information in any of these tags by marking it as required.

Custom field examples

The following sections demonstrate how to define various types of custom fields.

Example text input field

The following example shows a custom text input field.

<custom_fields>
<field>
        <name>field_1</name>
        <value>field_1 value</value>
        <required>true</required>
</field>
<field>
        <name>field_2</name>
        <value>field_2 value</value>
        <required>false</required>
        <editable>false</editable>
</field>
</custom_fields>

To define a text area, instead of just a standard input field, use the type tag as follows:

<field>
         <name>comments</name>
                   <value></value>
                   <type>textarea</type>
</field>

Example list box field

The following example shows a custom field with a drop-down list of choices for a user to select from.
Adding the value _other results in a text box appearing after _other is chosen from the list box. If the field is required, a value must be specified in the _other field text box when chosen.

<custom_fields>
  <field>
    <name>field_1</name>  
    <value>value_1</value>
    <required>true</required>
    <editable>false</editable>
  </field>
  <field>
    <name>field_2</name>    
    <value>value_1</value>
    <value>value_2</value>
    <value>value_3</value>
    <required>false</required>
  </field>
  <field>
    <name>field_3</name>
    <value>value_1</value>
    <value>value_2</value>
    <value>value_3</value>
    <value>_other</value>   
    <required>false</required>
  </field>
</custom_fields>

Example of a default value for a list box

You can specify a default value to be specified for a list box. It must be one of the choices in the value tags.

<custom_fields>
   <field>
    <name>field_2</name>    
    <value>value_1</value>
    <value>value_2</value>
    <value>value_3</value>
    <required>false</required>
    <default>value_2</default>
  </field>
  </custom_fields>

Example custom hidden field

You can specify whether or not a field should be visible to the end-user. The following example shows how to create a custom hidden field.

<custom_fields>
  <field>
    <name>field_1</name>  
    <value>value_1</value>
    <required>true</required>
    <editable>false</editable>
    <hidden>false</hidden>
  </field>
  <field>
    <name>field_2</name>    
    <value>value_1</value>
    <value>value_2</value>
    <value>value_3</value>
    <required>false</required>
    <hidden>true</hidden>
  </field>
  </custom_fields>

Example password field

The following example shows a password field.

<field>
     <name>field_1</name>
     <password>true</password>
     <required>true</required>
</field>

Example custom variable to replace values

BMC Database Automation allows the use of custom variables in your templates to replace certain values. For example, if you specify a custom field in your template, such as the following, you can refer to your custom field anywhere in the template by surrounding it in curly brackets {CUSTOM_FIELD_NAME}.

<custom_fields>
        <field>
                <name>ORA_BASE_DIR</name>
                <value> /app/oracle/foo</value>
                <required>true</required>
                <editable>true</editable>
                <hidden>false</hidden>
                <password>false</password>
        </field>
</custom_fields>

Example multiple custom fields pages in template

You can insert <page> and <title> tags into a template to have your custom fields provisioning distributed across multiple pages.

<page>
      <title>custom_fields_page_1</title>
      <field>
        <name>A</name>
        <value>dba</value>
      </field>
      <field>
        <name>B</name>
        <value>oper</value>
      </field>
</page>
<page>
      <title>custom_fields_page_2</title>
      <field>
        <name>C</name>
        <value>dba</value>
      </field>
      <field>
        <name>D</name>
        <value>oper</value>
      </field>
</page>

Example checkbox field

The following example shows a custom field that has been defined as a checkbox using the type tag.

<custom_fields>
 <field>
        <name>checkbox_1</name>
        <type>checkbox</type>
        <value>true</value> 
		<required>false</required>
		<editable>false</editable>
 </field>
</custom_fields>

To add a custom field for a database option to a template

1. Follow the steps in Editing templates.
2. Enter any of the custom fields demonstrated in the Custom field examples section.
   The custom fields should be entered inside the root tag named defaults and outside of the editable and non-editable sections.
3. Type the custom field name.
4. Specify whether the field is required (true or false) and whether the field is editable or non-editable.
   Tags that are not specified appear as blank, optional and editable. You can require the user to enter information in any of these tags by marking it as required.

5. Enter the content that defines the database option for which the value should be derived from this custom field. For example:

   <oracle_text>{custom_field1}</oracle_text>

   In this example, the value of the database option, oracle_text, on the Database Options page while adding a database, will be derived from the value of custom_field1 specified on the Custom Fields page.

To add custom fields for the scheduling options to a template

1. Follow the steps in Editing templates.
2. Enter any of the custom fields demonstrated in the Custom field examples section.
   The custom fields should be entered inside the root tag named defaults and outside of the editable and non-editable sections.
3. Type the custom field name.

4. Specify whether the field is required (true or false) and whether the field is editable or non-editable.
   Tags that are not specified appear as blank, optional and editable. You can require the user to enter information in any of these tags by marking it as required.

5. Define the custom fields for the scheduling options for which the value should be derived from the custom fields. Then, enter the content that implements the custom fields.
   For example, you can enter the following content to define and implement the custom fields.

   Note

   If you want to assign single digit values to custom fields (for example, hour and minute fields) in the example below, do not add 0 to make them 2-digit. For example, if you want to assign four to custom_maintenance_window_start_hour, assign 4, not 04.

   Example

   <?xml version="1.0" encoding="utf-8"?>
   <defaults>
       <custom_fields>
           <field>    
               <name>custom_maintenance_window_start_date</name>         
               <value>01/08/2018</value>
             </field>
           <field>         
               <name>custom_maintenance_window_start_hour</name>         
               <value>4</value>
            </field>  
           <field>
               <name>custom_maintenance_window_start_minute</name>  
               <value>5</value>           
           </field>    
           <field>       
               <name>custom_maintenance_window_end_date</name>
               <value>01/09/2018</value>
           </field>
           <field>
               <name>custom_maintenance_window_end_hour</name>
               <value>5</value>
           </field>
           <field>
               <name>custom_maintenance_window_end_minute</name>
               <value>59</value>
           </field>
       </custom_fields>
       <editable>
           <execute_option>schedule</execute_option>
       </editable>
       <non_editable>
           <set_maintenance_window>true</set_maintenance_window>
           <maintenance_window_start_date>{custom_maintenance_window_start_date}</maintenance_window_start_date>
           <maintenance_window_start_hour>{custom_maintenance_window_start_hour}</maintenance_window_start_hour>
           <maintenance_window_start_minute>{custom_maintenance_window_start_minute}</maintenance_window_start_minute>
           <maintenance_window_end_date>{custom_maintenance_window_end_date}</maintenance_window_end_date>
           <maintenance_window_end_hour>{custom_maintenance_window_end_hour}</maintenance_window_end_hour>
           <maintenance_window_end_minute>{custom_maintenance_window_end_minute}</maintenance_window_end_minute>
       </non_editable>
       <candidate_domains/>
   </defaults>

   In this example, values of the following options on the Scheduling page will be derived from their values specified on the Custom Fields page.

   • Job Execution
   • Schedule Date
   • Set Maintenance Window
   • Maintenance Window Start Time
   • Maintenance Window End Time