# Creating a Custom Field

Custom fields can also be used in reporting, setting up rules for Conditional Branching tasks, and can be used to search for items in ASM Core.

{% hint style="info" %}
**Before you start**

You must have **Designer** selected in your General Access security role before you can use this option.

To maintain an audit trail of changes made to screens, forms and message templates, Designer must be selected in the Auditing window. 
{% endhint %}

{% hint style="success" %}
**Best Practice**

#### Keep a spreadsheet of all custom fields you create and the details for change control and planning purposes.  This is also useful as a checklist against requirements.

You should create a CI called "ASM" and attach the spreadsheet to it, maintaining a complete change record and log of all the custom fields in perpetuity.  You can also attach all other related documentation relevant to your software to the ASM CI in your CMDB.  An example of a **Custom Fields and Screens** Spreadsheet is below - tailor it to your needs:
{% endhint %}

<figure><img src="https://content.gitbook.com/content/hlW9jKl7dcDggHAPhNU9/blobs/13dRGxixlDIyhLTwZhPm/image.png" alt=""><figcaption><p>Example: Custom Fields and Screens Spreadsheet</p></figcaption></figure>

{% hint style="success" %}
**Best Practice**

#### Choose a standard **Naming Convention** for all of your custom fields that includes: \[<mark style="color:orange;">**Prefix**</mark>]-\[<mark style="color:green;">**Body**</mark>]-\[<mark style="color:purple;">**Suffix**</mark>]

This method will organize your fields logically and alphabetically in the field list table so that you can find them easily both when building your screen but also when writing queries and building rules in other screens and workflows. &#x20;

1. <mark style="color:orange;">**PREFIX**</mark>: a logical designator (Project, Acronym, etc...). You should include a Project designator/number, or an acronym for the process you are defining, or any other designator such as your own companies name (or abbreviation) in the field name.  The important thing is that it makes sense to both you and other administrators that will come after you.
2. <mark style="color:green;">**BODY**</mark>: the name of the field&#x20;
3. <mark style="color:purple;">**SUFFIX**</mark>:  the field type (Chk, Txt, Num, etc...) When developers are building integrations through the API, etc, including the field type in the DB name enables them to know exactly what field and field type they are calling.
   {% endhint %}

{% hint style="danger" %}
**IMPORTANT NOTE WHEN NAMING YOUR FIELDS**

**When creating fields in ASM Designer, it's crucial to avoid using certain special characters in the name such as:** &#x20;

<mark style="color:red;">**Period (.)**</mark>  Used to delineate object names (tables) and can lead to parsing errors

<mark style="color:red;">**Comma (,).**</mark> Used by SQL when parsing and can cause unexpected behavior

<mark style="color:red;">**Percent Sign/Symbol (%)**</mark> Used in LIKE clauses for pattern matching

<mark style="color:red;">**Dollar Sign/Symbol ($).**</mark> Used in SQL to denote an internal system catalog view

<mark style="color:red;">**At Sign/Symbol (@)**</mark> the `@` symbol is used to declare a variable

<mark style="color:red;">**Double quotes (")**</mark> Used for string literals&#x20;

<mark style="color:red;">**Single Quotes (')**</mark> Used for object identifiers

<mark style="color:red;">**Forward Slash and Back Slash (/**</mark>**&#x20; and&#x20;**<mark style="color:red;">**\ )**</mark> Arithmetic operators and escape characters.

<mark style="color:red;">**Semicolon (;)**</mark>: Used to separate statements.

<mark style="color:red;">**Square brackets (\[ ])**</mark>: Used in LIKE clauses for pattern matching.

<mark style="color:red;">**Asterisk (\*)**</mark>: Used in SELECT statements to select all columns.

<mark style="color:red;">**Double-Hyphen (--)**</mark>: Used for comments when doubled (--), and can be misinterpreted.

<mark style="color:red;">**Plus (+), minus (-)**</mark>: Arithmetic operators.

These characters are reserved and have special significance in SQL, the language used for managing and manipulating databases. If these characters are included in a field name, particularly at the start.  They are automatically added to the database name as is. <mark style="color:red;">**Their use can lead to potential issues or errors in SQL operations because these characters might be interpreted in a way that was not intended, affecting the execution of SQL commands.**</mark> A common observation, for example,  is that rules with a comma in the rule name are often "invisible" and inaccessible through thee UI. &#x20;

To ensure smooth operation and to avoid database errors, it's recommended to refrain from using these characters in names. **A better option is to use the Underscore (\_).**
{% endhint %}

**The examples below use an acronym that flags the process and illustrates the naming convention outlined above.**

> ***Example 1:*** You are doing an Employee Onboarding project.  All the custom fields created for this project *could* be named like this - **EOv1\_\[field name]\_\[field type]**
>
> EOv1\_New Employee Name\_TXT *(Text Box - 255 Char)*
>
> EOv1\_Returning Employee\_CHK *(Check Box)*
>
> EOv2\_Returning Employee\_Y/Ns *(Yes/No String)*
>
> EOv1\_Start Date\_DT *(Date Time)*
>
> EOv1\_Special Access Required\_Y/Ni *(Yes/No Integer)*
>
> * **Note the 2 versions of the same field, "Returning Employee".**  Since projects usually involve several build, test, and fix/redeploy cycles, you may need to differentiate between iterations, sprints, or versions, of the same development project.  This really depends on the scope of the project and your own organizations development practices.&#x20;
>
> * **Here,** i**t was changed from a check box to a Yes/No string field in the second iteration.** You could go back and delete the depricated field at some point, but during development cycles, simply versioning will suffice.  Later cycles may want to reinstate the original field.

> ***Example 2:*** You are creating a custom Screeen for Budget Requests.  All the custom fields created for this screen *could* be named like this - **BU\_\[field name]\_\[field type]**
>
> BU\_FY\_NUM *(Number Field)*
>
> BU\_Budget Amt\_NUM *(Number Field)*
>
> BU\_Approvers\_MS *(Multi-Search List)*

## To Add a New Custom Field

1. In the left pane, select the **Add a Field** tab.
2. Select **Create New** in the left pane beneath the browse table of field types.
3. The **Create a New Field** window is displayed. Select the type of field you wish to create from the list in the left pane:

<figure><img src="https://content.gitbook.com/content/hlW9jKl7dcDggHAPhNU9/blobs/YN14flEnOEGO1YdhD5um/Screen%20Shot%202022-12-09%20at%2012.13.03%20PM.png" alt=""><figcaption><p>Example: Budget project custom approvers multi-search field creation</p></figcaption></figure>

<table><thead><tr><th width="168">Text Field</th><th>Enables input of a single line of text in the field. Text can include all alphanumeric and special characters.</th></tr></thead><tbody><tr><td>Text Area</td><td><p>Enables input of multiple lines of text.</p><p>Text Area custom fields cannot be used in rules for Conditional Branching tasks or in Rules Builder, and cannot be added as search criteria on Search windows.</p></td></tr><tr><td>Numeric Field</td><td>Enables input of numeric values – both integers and decimal fraction numbers.</td></tr><tr><td>Drop Down</td><td><p>Drop-down list fields can be used to create a list of values from which one can be chosen.</p><p>Select the list of values for the drop-down. You can either use an existing list of values (such as the Call Priority list), or you can create your own.</p><p>To use an existing list, select <strong>Assign an existing list</strong> and select a list, scrolling down if necessary. You can edit, copy or delete lists created in-house. (Standard lists can be edited in the relevant area of System Administration.)</p><p>To use vCloud CMDB item types, ensure that you select the (vCloud) CMDB Item Type. Selecting another CI type would not trigger the filtering mechanism that is possible with the (vCloud) CMDB type.</p><p>To create a new list and define your own values, select <strong>Create List</strong> and specify the list details.</p></td></tr><tr><td>Single Search Field</td><td><p>Enables the search and selection of one value in this field. The entity type configured for the QD field determines the type of items returned in the search and available for selection for the screen or submission form.</p><p>At <strong>QD Type</strong>, select the entity type you want to use. If you select a sub entity type (such as User which is a type of Person), then the values which can be selected in the QD field are limited to the sub type (that is, only person records designated as Users can be selected in a User entity type QD).</p><p>You can create the following:</p><p>·      Analyst</p><p>·      Call - available as of GAIA (ASM Version 10.4) </p><p>·      CMDB Item</p><p>·      Configuration Item</p><p>·      Cost Center</p><p>·      External Supplier</p><p>·      IPK Group</p><p>·      Knowledge - available as of GAIA (ASM Version 10.4) </p><p>·      Location</p><p>·      OLA Agreement</p><p>·      Organization</p><p>·      Person </p><p>·      Request - available as of GAIA (ASM Version 10.4) </p><p>·      Service</p><p>·      Service Action</p><p>·      Service Bundle</p><p>·      SLA Agreement</p><p>·      UC Agreement</p><p>·      User</p><p>·      Workflow Group</p></td></tr><tr><td>Multiple Search Field</td><td><p>Enables the search and selection of multiple values in this field. The entity type configured for the QD field determines the type of items returned in the search and available for selection for the screen or submission form. Using a QD field on a submission form within ASM Self Service is similar to using QD fields within ASM Core.</p><p>You can create the following:</p><p>·      Analyst</p><p>·      Analyst</p><p>·      Call - available as of GAIA (ASM Version 10.4) </p><p>·      CMDB Item</p><p>·      Configuration Item</p><p>·      Cost Center</p><p>·      External Supplier</p><p>·      IPK Group</p><p>·      Knowledge - available as of GAIA (ASM Version 10.4) </p><p>·      Location</p><p>·      OLA Agreement</p><p>·      Organization</p><p>·      Person </p><p>·      Request - available as of GAIA (ASM Version 10.4) </p><p>·      Service</p><p>·      Service Action</p><p>·      Service Bundle</p><p>·      SLA Agreement</p><p>·      UC Agreement</p><p>·      User</p><p>·      Workflow Group</p></td></tr><tr><td>List box</td><td><p>List boxes can be used to create a list of values that are displayed on screen from which one can be chosen.</p><p>Select the list of values for the drop-down. You can either use an existing list of values (such as the Call Priority list), or you can create your own.</p><p>To use an existing list, select <strong>Assign an existing list</strong> and select a list, scrolling down if necessary. You can edit, copy or delete lists created in-house. (Standard lists can be edited in the relevant area of System Administration.)</p><p>To use vCloud CMDB item types, ensure that you select the (vCloud) CMDB Item Type. Selecting another CI type would not trigger the filtering mechanism that is possible with the (vCloud) CMDB type.</p><p>To create a new list and define your own values, select <strong>Create List</strong> and specify the list details.</p></td></tr><tr><td>Multi-Select</td><td><p>Like drop-downs, multi-select fields can be used to create a list of values. However, in this case one or more values can be selected from the list.</p><p>Select the list of values for the drop-down. You can either use an existing list of values (such as the Call Priority list), or you can create your own.</p><p>To use an existing list, select <strong>Assign an existing list</strong> and select a list, scrolling down if necessary. You can edit, copy or delete lists created in-house. (Standard lists can be edited in the relevant area of System Administration.)</p><p>To use vCloud CMDB item types, ensure that you select the (vCloud) CMDB Item Type. Selecting another CI type would not trigger the filtering mechanism that is possible with the (vCloud) CMDB type.</p><p>To create a new list and define your own values, select <strong>Create List</strong> and specify the list details.</p></td></tr><tr><td>Checkbox</td><td>Can be used to denote binary values. A checkbox can have only two states - it can either be selected or cleared.</td></tr><tr><td>Date</td><td>Enables input of a date in the field.</td></tr></tbody></table>

4\.  In the main part of the **Create a \[field type]** window, complete the details:

<table><thead><tr><th width="180">Display Name</th><th>This name will appear on screens. You can change the Display Name for the field later if you wish.</th></tr></thead><tbody><tr><td>Database Name</td><td>This is automatically completed using the <strong>Display Name</strong>. All alphabetical letters are converted to uppercase and spaces are converted to underscores to satisfy the naming convention requirement for fields in the database. The Database Name is the name by which the field will be referenced in database tables. This never changes, even if you change the Display Name later.</td></tr></tbody></table>

5\.  Select **Create**. The new field is added to the existing lists, in alphabetical order, and you will also see it in the list of fields in the left pane of the main window. The **Create a \[entity type]** window stays open allowing you to create more fields.&#x20;

6\.  Repeat for all the fields you wish to create, and then select **Close**.

## Specifying **List Details** <a href="#specifyi" id="specifyi"></a>

The **List Details** window which appears when you are creating a field enables you to define a list of values for a Drop Down or List Box field.  **You can select an existing list or**:

1. In the **List Name** field, specify a name for the list.  **Follow the same naming convention as you did for your field name.**
2. Select **Add** to insert a new row in the browse table, and type the name of the value.
3. If you will be using these values to calculate the value of another field, for weighting or risk calculation, for example, enter a numerical value for the list item.
4. Repeat until you have defined all the values for the list.
5. To remove a value, select it and then **Remove**. To change the order in which a value appears in the list, select it and then **Move Up** or **Move Down**.
6. Select **OK** to save the list and return to the **Create a Field** window with your new list pre-selected.