Custom Modules

Sometimes, an organization's needs may go beyond the scope of the modules present in the application. In other cases, the organization might need to collect and store additional data that cannot be categorized under our pre-defined modules. In such cases, administrators can create and customize a new module from scratch, based on the organization's requirements.

Benefits of creating custom modules: 

• Custom modules enable you to design an entire module according to your preferences.
• You can create forms and configure lookup fields to collect extra information.
• You can configure custom modules to appear as a tab on the navigation pane. Alternatively, you can also place them under Setup to avoid crowding the navigation pane.
• Technicians can also import data and generate reports based on the data collected in custom modules.

Role Required: SDAdmin

You can configure access permissions to technicians for each custom module. Go to Setup >> Users & Permissions >> Roles and click New Role. Under Access Permissions, all custom modules will be listed. You can configure the permission level for the role and assign it to a technician to limit or extend their scope. 

After a custom module is created, you can start adding the relevant data to it. The information entered in custom modules is collected and stored as Records.

To learn more, refer to Configuring Roles.

Content 

• Create New Custom Module
  • Details
  • Fields
• Customize the Form Layout
• Custom Module List View
• Edit Custom Module
• Delete Custom Module
• Web Tabs vs. Custom Configurations

Create New Custom Module

In the Custom Modules list view, click New. This will open the New Custom Module form. You can create up to 20 custom modules.

The New Custom module form has two sections: Details and Fields.

Details 

In this section, you can specify the details of the custom module such as the name, description, API name, and more. You cannot proceed to the Fields section without filling out the mandatory fields in Details.

Use the pointers below for reference:

• Display Name: Enter the name of your custom module that will be displayed in each record.
• Display Name Plural: The plural form of your display name will be displayed on the navigation pane and other places referring to the custom module as a whole.
• Description: Enter a relevant description for your custom module.
• API Name: Enter an API name to enable API access to the custom module. An API name is written in snake case. It is pre-fixed by cm_ automatically.
• Icon: Select from the list of built-in icons to represent your custom module. You can also import an image as your icon. Ensure that the image size is not more than than 2 MB.
• Display Type: You can select the display type as Web Tab or Custom Configuration. Learn more about each display type.
• Data Import Enabled: Select this checkbox to enable data import to the custom module. You can import data from .csv files into custom modules under Setup >> Data Administration >> Import Data. Learn more.
• Reports Enabled: Select this checkbox to generate reports for the data in the custom module. Learn more.

Click Save to proceed to the Fields section.

Fields 

In this section, you can create a form by defining fields to capture the relevant information in each custom module record. You can add new fields, delete fields, add sections, and customize the form layout.

To add new fields, drag and drop the required field from the right panel to the canvas. The right panel has two kinds of fields: New fields and Available fields.

• Available fields are pre-defined fields. The application comes with four default fields, namely Created By, Created Time, Last Update By, and Last Updated Time. When these default fields are used in a custom module form, they are auto-filled by the application. In addition to the default fields, the new fields you define and remove from the form are listed under Available Fields. These fields are editable and not auto-filled by the application.
• New fields are customizable, undefined fields. Each new field is used to collect different types of data such as text, numeric, currency, or decimals. Use the table below to find out the different field types available:

On adding a new field to the canvas, the New Field window pops up where you can define the field. The configurations displayed will vary based on the field type. Learn more about field types and their uses.

After you have entered all the relevant data, click Save.

To edit or delete a field, mouse over the field and click the respective icon on top of the field.

Enable Fields to hold Unique Values 

You can prevent users from entering duplicate data in a custom module field by checking Is Unique Field while adding/editing a field.

For instance, assume you have marked Serial Number as a unique field in a custom module. When adding data to the custom module, the application will prevent users from entering the same serial number for two records. 

Configure Custom Module as Lookup Fields

Lookup fields allow you to refer data from one module to other modules.

You can configure the records in custom modules as lookup fields (reference entities) in other custom modules, Assets additional fields, and CMDB CI types. For instance, you can create a custom module called Client Portal and use the records from this custom module as a look-up field in Assets called Client Name. While adding assets, the records from the Client Portal custom module will be displayed as a drop-down in the Client Name field.

Refer to this screen grab for an illustration.

Configure lookup fields within custom modules

While configuring the Fields section, select Lookup fields from the available fields in the right panel. Enter the relevant information and select the custom module whose record you wish to add as reference to forms from Reference Entity drop-down. 
 

To create a lookup field for custom modules,

1. Go to Setup > Developer Space > Custom Modules (for custom modules).

2. Create new or edit existing CI Type or Custom module.

3. Go to the Fields section.

4. Drag Lookup Field from the right-side pane to the canvas.

5. Provide a field name and field key.

6. Reference Entities: Choose your preferred reference entity from the drop-down.  

7. Is Unique Field: Select this option if you want the field to hold only a unique value.

8. Is Mandatory Field: Select this option if you want to make this a mandatory field. Supported only for custom modules.

9. Criteria: Configure criteria to filter out the values from the reference entity to retrieve only a subset of values for the lookup field. To do this, choose the field, condition, and value. You can either choose a static value or a dynamic value using the supported variables. You can configure up to 10 criteria. When multiple criteria are configured, choose whether all criteria, some of them, or one of them should be taken into account using the logical AND or OR operators for each of the criteria. You can also sort the order of the criteria using the Drag Handle beside them.

10. Do not allow deletion of Field Values: Enable this option if you want the values of reference fields to be marked as not for further use when deleted instead of removing them.

11. Description: Add a relevant description.

12. Finally, click Save.

Configure lookup fields from a custom module to Asset module

1. Go to Setup >> Customization >> Additional Fields.
2. Select Asset Additional Fields from the module drop-down.
3. Click New Field.
4. Enter the Field Name and select the Field Type as Lookup Field.
5. In the Reference Entity drop-down, select the custom module whose data will be shown in Asset form.
6. Enter a Description if needed and click Save.

To learn more about configuring asset additional fields, refer to Additional Fields.

Configure fields from a custom module to CMDB module

1. Go to Setup >> Customization >> CMDB.
2. In the CI Types tab, click New CI Type.
3. Enter the necessary details in the Details section.
4. In the Fields section, select Lookup fields from the available fields in the right panel.
5. Enter the relevant information and select the custom module whose field you wish to add as reference to Asset forms from Reference Entity drop-down.

To learn more about Adding New CI Types, refer to Configuration Item (CI) Types.

Prevent Deletion of Records configured as Lookup Fields  

When lookup fields are configured with custom modules as reference entity, you can prevent technicians from deleting the lookup fields (reference entities) configured in custom modules. This will prevent accidental loss of data.

For instance, assume you have a configured a custom module called Client Portal as the reference entity for a lookup field in Assets. In the Add/Edit Assets form, the records present in Client Portal module will be reflected as a drop-down from where you can select the relevant record. If a user deletes this selected record from Client Portal module, it would result in loss of data in Assets as well. To avoid such cases, you can prevent all users (including yourself) from deleting a record if it is configured as a lookup field.

To enable this option, check On Delete Restrict while configuring the lookup field. This option appears only when a custom module is selected as reference entity.

Customize the Form Layout

You can customize the form layout to look aesthetically pleasing and help users navigate the form in a progressive manner.

You can use the Section Properties to customize sections as a whole:

1. Click the settings iconon the top right corner of the section to open Section Properties.

2. Choose the number of columns to be displayed in the section.

3. Choose the label orientation. You can customize the label names to appear on the left, right, or top of the field box.

4. You can configure the collapsed state of the section. This is applicable only to named sections. There are three options:

• Expanded - The section is expanded by default when the form is loaded. The user can collapse if needed.
• Collapsed - The section is collapsed by default when the form is loaded. The user can expand if needed.
• None - The form is loaded static with no option to expand/collapse.

Apart from the section properties. you can also perform the following customization actions on the form directly on the canvas:

Re-order sections: To reorder the sections, click the icon on the top left of the section and drag them to the new location.

Re-order fields: Reorder fields using the drag and drop tool.

Align multiple options: For multi-select, checkbox and radio fields, you can align the options in list, grid, or sequence by clicking the icon on top of the field.

Expand/Collapse fields: When the number of columns is selected as 2, you can collapse the fields or expand them by clicking the arrows on either side of the field.

Here is a screenshot with various configurations for reference:

Once you have customized the form, click Save to apply the customization.

Custom Module List View 

You can view the custom module list view under Setup >> Developer Space >> Custom Modules. You can search, create, edit, and delete custom modules from the custom modules list view.

To modify the list view layout, click the icon. You can sort the modules, choose the number of records to view on a single page, and choose the columns to view.

You can also search for custom modules by clicking icon. Enter the display name, created by date, or last updated by in the relevant text fields and click Go.

Editing Custom Module 

1. In the Custom Module list view, click the icon beside the display name of the required custom module.
2. Select Edit.
3. The Edit Custom Module form opens up. Make the necessary edits.
4. Click Save.

Deleting Custom Module 

1. In the Custom Module list view, click the icon beside the display name of the custom module you wish to delete.
2. Select Delete.
3. Click Confirm.

Web Tabs vs. Custom Configurations 

Depending on the display type, you can create two types of custom modules: web tabs and custom configurations. The major differences in both types of custom modules are mapped in the table below:

To learn more about web tabs and custom configurations, refer to the links below:

• Web Tabs
• Custom Configurations