User-Defined Buttons

Modified on Tue, 8 Aug, 2023 at 2:06 PM

Introduction

User-defined buttons are used to provide custom functionality to the main grid view of the Applications, Users, Devices, Deployment Unit, and Bespoke modules through the use of Powershell Scripting and the ManagementStudio  API. The User-defined buttons are accessed using the right-click context menu when hovering over these main grid views. These buttons can be used to send emails, run scripts, and run actions. The buttons support sub-buttons to create granular and easy-to-use menus.



TABLE OF CONTENTS



Example - Custom Buttons added to Grid Context Menu



Button Types

  • Script Buttons - Pass the selected Grid Items (Apps, Users, etc) to a PowerShell script for processing
  • ESM Plan Buttons - Pass the selected Grid Items (Apps, Users, etc) to n ESM Plan for processing 
  • Send Email Buttons - Send an Email to the selected Grid Items (Apps, Users, etc)  
  • Action Buttons - Run a build in action on the selected Grid Items (Apps, Users, etc)


Note the top-level button that appears directly on the context menu can not perform any actions, it must have a sub-button under it to do the work


Note it is not possible to have button that perform multiple types of actions, e.g. a Button that Runs PowerShell, Calls and ESM Plan and Sends an Email. only one action type is allowed per button. 

Script Buttons

Script Buttons target PowerShell scripts registered in the PowerShell area of the Admin section. 


User Input


When creating buttons that call Scripts, it is possible to ask the user for some input that can then be passed to the script. For example, asking the User for a Date or selecting an option from a list. Many of the input types have associated control args that allow configuration of the input, such as setting a maximum date or number, or the items in a list.  


Input TypeDescriptionControl Args
Text - Single LineUsers can provide a single line of textNone
Multi-LineUsers can provide a block of textMaxLines:5;
Date and TimeUsers can Date and Time from the selectorMaxDate  / MinDate
e..g MaxDate:2024-01-01;MinDate:[Today -1]
Date OnlyUsers can pick only a Date from the selectorMaxDate  / MinDate
e..g MaxDate:2024-01-01;MinDate:[Today -1]
Time OnlyUsers can pick only a Time from the selectorMinHour: / MaxHour / Interval

e.g MinHour:09;MaxHour:18;Interval:HalfHour;
CheckboxPass a TRUE/FALSE into the script, the default is FALSE
IntegerUsers  can select a whole numberMaxValue / MinValue
e.g. MaxValue:50;MinValue:0;
DecimalUsers can select a decimal numberMaxValue / MinValue
e.g. MaxValue:50;MinValue:0;
DropdownUsers can select 1 item from a dropdownItems
e.g Items:AD Group1|AD Group 2|AD Group3
ListboxUsers can select many items from a listItems
e.g Items:AD Group1|AD Group 2|AD Group3
Module ItemsUsers can select Apps, Users, Devices, etc from a pop up.Module / Multiple 
e.g. Module: UserMigrations; Multiple;

if 'Multiple' is present the user will be able to select multiple items from the list

Valid Modules are: Applications, UserMigrations, Devices, Mailboxes, BespokeModule, DeploymentUnits, Dashboard, Defects, Tasks



ESM Plan Buttons


Pass the selected Grid Items (Apps, Users, etc) to n ESM Plan for processing. To use select the name of the ESM Plan to run from the dropdown in the "Run ESM Plan" column of the Button UI Grid. 

Only ESM Plans for the UI Buttons module will be shown in the dropdown. i.e. When looking at Application Buttons only ESM Plans that target Applications will be shown in the drop-down. 



UI Buttons Grid Columns


The setup grid is broken split into the following sections BUTTON, OPTIONS, and ACTION  with the fields described in detail below:


ColumnDescription
Button LabelThis is the label that will be seen in the right-click context menu. If there are any sub-buttons defined, they will be shown to the side.
Sub-ButtonClick on the + icon next to the Button Label to create a Sub Button. These sub-buttons will be nested to the right in the context menu.
Note: It is possible to have multiple levels of sub buttons
Is Enabledif unticked then the Button will not be available in the context menu
IconIcon text representing the icon that will be displayed next to the button label in the context menu.
The Icons come from Font Awesome Pro selection
for example "bullseye-pointer" will show 
Grant Access 1
Grant Access 2
Grant Access 3
Select the Role Group that will have access to use this button.
A Button must have a role group associated with it to show in the UI. Only users in this role group can see the button. It is possible to have different permissions for different buttons in the same tree. The UI will still only show the User the buttons in the tree that they are allowed to see. 
OrderSort order of the Button or Sub-button
Context MenuTicking this will allow access through the context menu.
Note: Buttons on the ribbon don't require any rows to be selected on the grid to run, but if there are items selected then these will be passed to the Button's script
Are You SureWhen ticked, a popup will appear asking whether the users wishes to continue running either the script, action or Email send. 
UI Wait Complete (Hidden)Puts the grid into a 'busy' state that waits for the script to finish before the user is allowed to do another action. For scripts that are short is good to wait, the grid will be automatically refreshed when the script is finished. For longer-running scripts like a report that takes fifteen minutes to complete then it's best not to wait. The use will still get a notification popup when the script completes.
 Note: Buttons that wait for the UI are assumed to be short and get a new thread to run in. Buttons that don't wait are assumed to be long-running and are added to a queue of scripts to process. As such these no-wait scripts can take an extra-long time to run if there are other scripts in the queue. This is to protect the server from being overloaded. 
Limit (Hidden)The maximum items that can be selected on the grid to pass to the script. 0 = No maximum. For scripts that are long-running or particularly dangerous, it can be useful to limit the number of items it can affect at one time.
Script User InputPopups up a Textbox, Number Picker, and Date Picker to the User. The result will be sent to the script in the 'UserInput' variable.
User Input LabelThe text that appears on the input control that is defined in 'Script User Input'
User Input Control ArgsModifier args are used to set limits and other options on the User Input Control
Running Msg to User (Hidden)The text that shows in the alert bar at the bottom of the screen when the button is clicked.
Run ESM PlanPass the selected Grid Items (Apps, Users, etc) to n ESM Plan for processing
Run ScriptChoose which script will be run by clicking this button. These scripts are defined in Administration\PowerShell Scripts

Note: Only scripts that target this module will show in the list.
Send EmailChose which email template will be sent upon clicking this button. These email templates are defined within each of the modules under Administration\[module]\Email Templates
Args 1 (Hidden)
Args 2 (Hidden)
Args 3 (Hidden)

When ManagementStudio calls a script it passes three arguments to the script. This allows the same script to be used for multiple tasks and control the behavior via the arguments. e.g. A report generator script might be called with different reports at different times of the day.

DeleteTick this checkbox to delete the User-defined button upon the next save
IdInternal Id of the User-defined button
Parent Id (Hidden)If this button is a Sub Button, then the Id of its Parent is identified here. Used in scripting and
custom actions to check the hierarchy of buttons. 


All options marked Hidden can be found using the column chooser button at the top right of the grid 



Further Support

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