Custom Forms

Modified on Tue, 06 Feb 2024 at 05:24 PM

TABLE OF CONTENTS

Introduction

Custom Forms are a flexible way to extend the type of information stored in ManagementStudio's Modules.  For example, a new custom form that contains PPE & Safety details could be added to the Deployment Units module to store information regarding the PPE requirements for each Deployment Unit. For example:



All modules within ManagementStudio have access to Custom Forms.





Accessing Custom Forms

All modules within ManagementStudio -  Applications, User Migrations, Devices, Deployment Units, Defects, and Bespoke - have access to four Custom Forms:

  • Discovery: Description
  • Custom Tab 1: Description
  • Custom Tab 2: Description
  • Hidden Tab: Similar to Custom Tabs 1 and 2, Hidden Tab is only presented to users with the View Hidden Tab permission defined in Administration > Role Groups. For further reading about defining permissions, please refer to https://support.managementstudio.com/a/solutions/articles/14000108610.


Custom Forms are found in the Custom Forms panel of Administration (1)> Module (2). The screenshot below shows the options for the Deployment Units module:




Custom Form Common Elements

Each module's Custom Form share the same common elements:


  1. Breadcrumb Bar: Used to ease navigation in the Administration section by providing clickable links to parent sections.
  2. Control Bar: Provides
    • Save Changes: Commits changes to the Custom Form
    • Cancel Changes: Dismiss any changes made since the previous save
    • Preview Changes: Preview the current state of the form without needing to save
    • Current Custom Form: Displays the current Custom Form without saving it first. The preview will open in a separate window and will not contain data as they are not attached to an object at this point.   In the example below, Discovery is selected. Other options include Custom Tab 1, Custom Tab 2, and Custom Tab 3.
  3. Tab Control Bar:
    • New Field: Creates a new field (which will appear in the Field List (5))
    • New Tab: Creates a new tab (which will appear in the Tab List (4))
    • Tab Label: The name for the currently selected tab.
    • Move Tabs: This allows you to move the currently selected tab up and down the tab list (4)
    • Visible: This allows you to control whether a tab is visible or not.
    • Remove Tab: This allows you to remove the currently selected tab.
  4. Tab List: A list of tabs for the current Custom Form. Tab order can be changed by selecting the relevant tab and using the Move Tab arrows in the Tab Control Bar (3) to move the tab up and down the tab list.
  5. Fields Grid: This shows a list of fields in the currently selected tab in the Tab Control Bar (3). The New Field button adds a new field to the list, which is automatically populated with a default text line control. Further information is provided in Fields Grid, below.
  6. Field Details: This pane allows the administrator to configure the options for the selected field.  Further information is provided in Field Details, below.


Tab Control Bar

The Tab Control Bar provides the functionality required to manage the tabs and the columns that are available to the Fields Grid (see the following section).  The bar provides several features:

  1. New Field: Creates a new text field at the top of the Fields Grid.
  2. New Tab: Create a new Custom Form Tab, which appears in the Tab List (area 4 of the Custom Form Common Elements, above).
  3. Tab Label: The name of the Custom Form Tab.  To change the name, replace the text in Tab Label and click Save Changes at the top of the window.
  4. Move Tab: Clicking the up/down arrows will move the position of the current tab in the Tab List.
  5. Visible: By default, all tabs are visible in the UI.  To hide a tab, for example when testing a new tab, de-select Visible and click Save Changes. This does not remove the tab from the Custom Form, nor does it delete data.
  6. Column Picker: The use Column Picker to select additional columns to add to the Fields Grid.
  7. Remove Tab: This feature will permanently delete the currently selected tab from a Custom Form and all the associated data.  The change will only take effect when the Save Changes button is clicked.  To reverse the action, click Cancel Changes.
  8. Adv. Info: Display additional fields the could be useful for advanced users, such as Tooltips, Tags, Internal Name, Internal Id, and Flags. By default, this is disabled.



Fields Grid

The Fields Grid offers a convenient way to add and edit fields in a Custom Form.  The grid consists of several columns:

  1. Field Label: The name of the control.
  2. Display As: Specify the type of control (e.g. text, dropdown, or radio button).  Further information about the field types available is detailed in Control Types, below.
  3. Options: Several of the field controls support additional options, such as adding items to a dropdown list or radio button.  Further information is provided in Control Options, below.
  4. Display Order: The Display Order allows an administrator to specify the order in which each field is displayed.  Lower values will appear first.  
  5. Width: A Custom Form row is comprised of 12 columns (refer to the illustration below).  A control with a width of 12 will occupy the entire row, a control with a width of 6 will occupy half of a row, a control with a width of 3 will occupy a quarter of a row, and so on. This can be used in conjunction with the On New Line option in the Field Details panel, detailed below, to force the control to start on a new row.
  6. Visible: As the name suggests, this controls whether a control/field is visible on the Custom Form.
  7. History: ManagementStudio will record up to 5 changes (who and when) for any given field. By enabling the History option, changes will be recorded indefinitely. This should be used sparingly as it increases database load and size.
  8. Fld: This number refers to the Custom Forms fields and is a unique identifier in the system. This value is useful when programmatically referencing ManagementStudio objects in Javascript and PowerShell custom scripts.




Field Details



  1. Field Label: The text of the field as it appears in the user interface (UI).
  2. Options: Several of the controls support additional options, such as adding items to a dropdown list or radio buttons. Further information about the options available is detailed in Control Options, below.
  3. Client Style: All controls support border, margin and padding options.  Multiple properties are separated by a semi-colon and the values specified represent left, top, right, bottom values.  For example, Border: 2,2,2,2;would create a 2-pixel border around the control.
    • The margin property creates space outside of the control.  For example, margin:0,100,0,0 will move the control down by 100 pixels. I.e. the top of the control will start 100 pixels further down.
    • The padding property creates space around the control's content.  For example, if padding: 0,100,0,0 is specified, the top of the control will remain the same but 100 pixels of space will be added between the top of the control and the start of the content.
    • The border property creates a border around the control.
  4. Tooltip: This is the text that appears when a user hovers the mouse over a control.
  5. Default: The default text, date, time, selected option etc for a control.
    • For Checkbox, use TRUE to check the box by default.
    • For CheckboxList and List Box, the Default value for the control should match one of the values specified in the Options field for the control.  For example, the image below has a Checkbox List with Items: Off|7 days|28 days|3 months|6 months|1 year specified as Options.  The control has the Default value of 28 days, which matches the third value.
  6. Display As: Specifies the type of field to show in the UI.  For example, text box, radio buttons, or Checkbox List.
    • The type of control.
    • See below for a table of controls and their options.
  7. Display Order
    • This controls which order the controls are displayed in the Custom Form, lower values appear first.
  8. Width:
    • Determines the width of the control. A Custom Form row is comprised of 12 columns. A control with width 12 will occupy the entire row, a control with width 6 will occupy half of a row, a control with a width of 3 will occupy a quarter of a row and so on. 
    • One of the control parameters is "On New Line" when this is ticked a control will always start a new row even if there is space for it on the current row.
  9. Web Style: Coming soon
  10. Watermark:
    • The text that will appear in text-based control when it is empty. i.e. "Enter Your Name" will appear in a greyed out colour until a user starts entering data in the control.
  11. Tag:
    • To store "extra" data in the control. 
    • Typically used with API calls and scripts
  12. Visible:
    • If checked the control will display on the form otherwise it is hidden.
  13. Retain History: If enabled, this will retain all changes to this field in the history tracker. A Custom Form field can have history enabled which means every time it changes it is recorded who changed it to what value and when. This is off by default and should be used sparingly as it increases database load/size. If this is enabled, we recommend enabling the Trim Custom Form Field History and setting the number of changes to be retained within the Housekeeping task 
  14. Disable History: Don't record any history for this field in the history tracker
  15. On New Line: When this is ticked the control will always appear at the start of a new row even if there was space for it on the row above.
  16. Read Only:
    • If checked the control will not be editable in the UI.
  17. Add Filter:
    • Adds the field to the Custom Form filter on the ribbon menu of the main grid



Control Types


ControlDescription
HeaderA bold line of text
InfoA line of normal text
LineA horizontal line, like an <hr/> in HTML
SpacerAn empty line. Used to create space between sections
(UI) Toggel UI ElementsControl to Show Hide other custom fields
TextBoxA one-line high textbox for the user to enter data
TextBoxMultiLineA multiple line textbox for a user to enter a block of data


CheckboxA single checkbox
DropdownA dropdown box with multiple options, but only one option can be selected
RadioButtonA list of radio buttons that can have only one option selected at a time
ListBoxA list of options that supports multiple options being selected at the same time
CheckboxListA list of checkboxes that supports multiple options being selected at the same time
StarRatingA 1 to 5 Star review rating like control


DatePickerA button that popups up a calendar to pick a date from
TimePickerA button that popups up a list of times to pick from
DateTimePickerA button that popups up a calendar and list of times to pick from


NumberPickerIntA textbox that allows a whole number to be entered
NumberPickerDecA textbox that allows a decimal number to be entered


ButtonA button that will run a Button Action as defined in the Admin section. e.g. AD Sync
HtmlBlockAn area that will render HTML. e.g. A Html formatted report from ESM
ProgressBarA progress bar that connectors can update in real-time
SettingsTableA table of rows and columns to hold settings for connectors
PasswordA Password textbox where the data will show as ******
HyperLinkA clickable link that will open in a browser


Control Options

Most form controls support further customisation by use of the 'Options' field. These can be used to set the items in a dropdown, the min/max date on the date picker, the font in a text box etc. The options text can be a maximum character limit of 2000 characters.


Note: The option field treats the characters : | , ; as special. To use these in text e.g. A header that says 'Section 1: Validation' prefix the character with a \ e.g. 'Section 1\: Validation'. These will then be treated as text and not used to distinguish different options. 


Note: ManagementStudio will remove any extra spaces in a list during processing.  For example, 'Items: Yes | No ;' is exactly the same as 'Items:Yes|No;'



ControlOptionsExample
HeaderText - Text to show as headerText: This is a header!;
InfoText - Text to show as info textText: This is a paragraph of text;
LineNo options available
SpacerNo options available



TextBoxMonoSpaced - Switch to a better font for code
Bold - Make font bold
MonoSpaced; Bold;
TextBoxMultiLineMonoSpaced - Switch to a better font for code
Bold - Make font bold
MaxLines - Number of lines to show before scrolling
TextWrappingOff - Turn off text wrapping and use a horizontal scroll bar (good for reports)
MonoSpaced; Bold;
MaxLines:5;TextWrappingOff;



CheckboxText - Text shown next to the checkboxText: Check this option;
Use 'TRUE' to check the box as the default.
Dropdown

Items - A | delimited list of options to display

Items: Yes|No;
ListBox

Items - A | delimited list of options to display

Items: Frist | Second| Thrid
Use the options delimited by a | to check them by default. e.g. Opt1|Opt3|Opt5
CheckboxListItems - A | delimited list of options to displayItems: 1|2|3|4
Use the options delimited by a | to check them by default. e.g. Opt1|Opt3|Opt5
RadioButton

Items:

Colour: Auto - Auto colours items 

Colour: Explicit - Set the colour of individual options

Red:Opt1;Amber:Opt2; - Used with Colour Explicit 

Items:Yes|No; Colour:Auto;
Items:Opt1|Opt2;Colour: Explicit;
Green:Opt1;Amber:Opt2;



DatePickerMaxDate - Max allowed date in yyyy-mm-dd format
MinDate - Min allowed date in yyyy-mm-dd format
MinDate:2020-01-01;
MaxDate:2020-05-20;
TimePickerMaxHour - Max allowed hour in 24 hour format
MinHour - Min allowed hour in 24 hour format
Interval:(Hour, HalfHour, QuarterHour) - Minutes group
MinHour:09;
MaxHour:18;
Interval:HalfHour;
DateTimePickerMaxDate, MinDate , Interval.
NB: Interval does not work on web forms
MinDate:2020-01-01;
MaxDate:2020-05-20;
Interval: HalfHour;



NumberPickerIntMinValue- Min number value
MaxValue-Max number value
MinValue: 0; MaxValue: 99;
NumberPickerDecSame as NumberPickerInt
Star RatingMaxValue - Number of Stars (default is 5)MaxValue: 10;



ButtonScriptId -
ScriptName -
AreYouSure - UI will popup a confirmation box prompting the user to confirm the running of the script.
WaitForComplete - UI will wait for the script to complete and pause the UI with a spinning wheel.

ButtonId- Id of the button execute
ButtonName - Guid of the button execute

EventArg1, EventArg2, EventArg3- Values to pass to the script

GetUserInput, GetUserInputLabel - Ask the user to input a value before continuing. This value will be passed to the target of the button
Buttons can be used to execute a script or button registered in the system.

NB: When executing a script the 'AreYouSure' and 'WaitForComplete' options can be used

Button:10;
EventArg1:SYNC;

GetUserInput;
GetUserInputLabel: Server Name
(UI) Toggle UI Elements

OnLabel: Yes; - Value of the toggle when on

OffLabel: No;  - Value of the toggle when off

HeaderMode; - If present the field name is bold

OnFieldIds : {FieldId}|{FieldId}|{FieldId}|{FieldId}; - what fields should be visible when the toggle is selected.

OffFieldIds : {FieldId}|{FieldId}|{FieldId}|{FieldId}; - what fields should be visible when the toggle is NOT selected.

OnInternalFieldIds : {FieldId}|{FieldId}|{FieldId}|{FieldId};  - What internal field references should be visible when the toggle is selected.
OffInternalFieldIds : {FieldId}|{FieldId}|{FieldId}|{FieldId};  - What internal field references should be visible when the toggle is NOT selected.
Toggle can be used to show hide custom fields in the UI. Useful to guide a ManagementStudio user through a custom form by hiding what they do not need to see.

example:-

OnLabel: Yes; OffLabel: No;

OnFieldIds : 8112;

OffFieldIds : 8113;


Schedule TaskScriptId -
ScriptName -

EventArg1, EventArg2, EventArg3 - Values to pass to the script

HtmlBlockNo options available
ProgressBarNo options available
SettingsTableColumns - List of column names to create
Combo-[ColumnName] - Create a dropdown column of options.
Columns:Setting|Value|Enabled;


Combo-Setting: Opt1|Opt2|Opt3;

Combo-Enabled: Yes|No;

PasswordNo options available
HyperLinkTarget -default target of link type. File, Web, SSL.
This will pre-fix the link/path with 'file://' , 'http://', 'https://'

Target:File


All controls support Border,Margin and Padding options. Format: {left},{top},{right},{bottom}.
e.g. Border:2,2,2,2; Margin:1,1,1,1;


Displaying Custom Fields within the Details Tab

Step 1 - Decide on the Custom Fields to be displayed within the details tab

The example that follows will use the User Migrations module to illustrate the concept although this approach applies to all modules within ManagementStudio. 

  • Switch to Administration -> User Migrations (1) -> Select the option required (2)


  • The custom fields required in the example is located within the Discovery custom form
  • Click on the desired tab (1)
  • Make a note of the fields you want displayed within the details panel (2)



Step 2 - Configure the Details Config

  • Switch to Administration -> User Migrations ->Details Config (1)
  • Scroll down to the section “List of Custom Fields to show in the ‘Custom Fields Panel’"
  • Enter the fields ids noted from step 1 (2)
  • Enable the Custom Fields Panel (3)
  • Click Save Changes (4)


  • Restart the Client
  • Upon restarting the client
  • You should see the Custom Field Panel with the listed fields within the details tab


Further Support

If you require further support, please visit ManagementStudio's Service Desk to search the knowledge base or create a new support ticket.