Portal Edition R4 is a milestone in our Portal development and sets the tone for future developments. Furthermore, this release is an important step towards the complete replacement of the previous web apps with a role-based Portal.
The release of Portal Edition R4 introduces a modern design and a new user interface, the structuring in Portal Apps is rendered obsolete.
The New Features in More Detail:
- New information architecture, UX and UI design
- New Portal including the portal dashboard
- Revised "Run" area
- New in the Portal: credential configuration incl. SSH (Secure Shell)
- New in the Portal: target configuration
- Automatic module detection with advanced target testing functionality
- Microsoft Graph as new service for M365 targets
- Token-based authentication for M365 services (Teams and Graph)
- Upload of files by users for bulk processing
- Enforcement of signed scripts
New Information Architecture, UI and UX
The Portal is now based on a new information architecture. The goal was to combine a simple and quick-to-understand application with a modern, intuitive user experience. Many things were re-thought and re-designed, and proven structural elements from the previous web apps were integrated. Clarity was significantly improved, controls were designed so that their function and effect are recognizable, and old limitations were eliminated. This is most noticeable in the new main menu, the overviews and the individual configuration elements.
Portal dashboard with the different widgets
The new design is groundbreaking for further developments in the Portal in the coming years. This architecture eliminates the previous Portal Apps. The functions now merge into the new configuration and application modules of the Portal.
An important point in the redesign was also accessibility through revision of the color palette and recognizability for users with different color vision difficulties.
New Portal
In the first step, the Apps overview on the Portal's entry page was replaced by a clear dashboard (see figure above). In later versions, this will be individually configurable. Essential elements in the dashboard are the displays for the latest reports, the top actions as well as pinned actions, i.e. the actions that an administrator wants to have in immediate access.
The portal can be accessed in the familiar way using http(s)://<servername>/scriptrunner/portal .
The previous top bar has been retained. The top bar includes brief information, language selection, login account, support widget and online help.
NEW! The languages SPANISH and FRENCH are now available in the Portal for all users.
New language selection – nouveau choix de langue: français – nueva selección de idiomas: español
The thematically oriented main menu with Run/Automation, Delegation, Monitoring, Configuration and Settings provides clarity and easy access. It can be used fixed as well as sliding.
When a main menu item is selected, the display changes to an overview page for the corresponding elements, here in the example below, it switched to the list of all scripts. At the top, three navigation elements are placed:
- Back button and a clickable breadcrumb for quick navigation between levels.
- Global tag filter for filtering on specific elements. This filter is preserved even when switching between main menu items. Clickable tags in the table simplify usage.
- Owner selection. This selection appears in multi-team mode only.
The overview always shows the number of filtered or displayed, and total available elements next to the name of the selected menu item.
Complete overview of the scripts, direct editing possible
Below are context-oriented function buttons, with the primary one highlighted (+New script in the screenshot). On the right, at the same height, is the search field (icon of a magnifying glass).
Selected columns of the table are sortable and certain displayed properties are clickable and editable.
Opened script in the code editor
Clicking on the name of an element opens the detail view. In the example above, the script Add-ADUsersToGroups was clicked. The top section contains the Back button again, the clickable breadcrumb as well as the name of the element and important function buttons.
The Configuration section contains the individual groupings for editing properties and details of the element. The General section is the same for all elements, the other sections depend on the type and context of the element.
The Information section contains individual groupings for further information in the context of the element, e.g. where it is used.
Depending on the element as well as the context of an element, additional information is provided on the right side.
- Online help
- Input help
- Input requirements ("i")
- Tip
- Caution
- Warning
The context-oriented online help opens by simply clicking the help button in the top bar. For this purpose, a display area for the help is superimposed, but the configuration settings remain usable.
An input help can be recognized by the "?" directly at the input field. When you click on it, the short help appears.
An explanatory input requirement is always located below an input field and can be recognized by the "i".
Display of Tip and Caution
A Tip (gray) on the right side next to the details gives additional information and useful contextual hints for complex issues and contexts.
A Caution (yellow-orange) on the right side next to the details indicates that something has to be paid attention to, e.g. that certain requirements have to be met or something is outdated.
A Warning (red) on the right side next to the details indicates a problem, e.g., that something is incomplete or cannot work.
Set the hex color code for tags
Tags can now be colored with color values from a recommended palette or with custom color values for faster differentiation. A description on the tag is displayed in the list views upon mouseover.
Revised "Run" Area
The main menu item Run has been revised and adjusted both in design and user guidance. There is now a back button as well as a clickable breadcrumb, just like in all other overviews.
The design of the input form of an action has also been revised to improve clarity and to separate the inputs more clearly from other role-dependent additional options. In a future version, a simple form designer will create additional possibilities.
Default view Run: extended tiles
In the extended view, further information is displayed in addition to a multilingual name and description. Administrators and helpdesk can display the reports of an action depending on the role. Users in the role Administrator can additionally set the delegations for the action as well as edit the descriptions of an action.
The familiar tiles now come in a modern design and with a new, reduced, simplified option next to extended (by default) and list view. The reduced tile view is designed especially for helpdesk and end users. The information on the tiles is simplified and optimized for quick selection of an action. The names of the actions can be multilingual, depending on the selected language already stored and displayed in the script or on the action itself.
Reduced, simplified tiles
The selection and deselection of the display tabs and the views have been completely redesigned. In addition to the typical elements, the list view shows the color, icon and pin status of the respective action. If an action has been pinned, it also appears in the widget on the dashboard for administrators.
List view in Run displaying color, icon and pin status of an Action
New in the Portal: Credential Configuration
The configuration of credentials in the old Admin App was very complex and confusing. In the Portal, the entries have been categorized and the user interface has been completely redesigned so that users can work with it more intuitively. In the overview, all created entries are displayed with the corresponding type. Depending on the use case, the following types are supported: user credential, client secret, password server reference, SSH keys as well as entries for PowerShell secrets management and the use of WinRM client certificates.
When clicking the selection box at a list item, the additional buttons Edit and Delete appear in the display area above, next to the primary button +Create.
Clicking on the name opens the detailed configuration, clicking on a tag puts it into the global tag filter.
The extended line menu contains further functions.
Creating a new credential
When creating a credential, the first thing to specify is the type. This can be followed by other options such as ownership and subvariants.
For the use of PowerShell 7, remoting over SSH becomes more and more important. For this reason, it will be presented here in more detail. When creating an entry for an SSH key, the options "via file path" or "via file content" can be selected as a subvariant.
Background to the Use of SSH Key Files in ScriptRunner
SSH (Secure Shell) originally relies on key files in user directories with special permissions. For these user directories to exist, a user profile must exist on the ScriptRunner server.
The subvariant "via file path" allows the use of SSH in this variant. However, it has to be considered in which user context the script is executed. It must be ensured that the ScriptRunner server can access the user profile and thus the SSH directory at runtime.
Less complicated and therefore the preferred variant is "via file content". In this case, the ScriptRunner server manages the SSH key files, the administrator does not have to worry about permissions and accesses.
Configuring an SSH key with file path
After selecting "via file path", the path where the key file is stored can be specified in the configuration. It should be ensured that the permissions on the path are set correctly.
Configuring an SSH key as file content
The selection "via file content" allows two possibilities. On the one hand, the content of the key file can be copied into the text box. Alternatively, the file picker can be used, the content is extracted and can be seen in the text box.
With saving, a key file with the content is created and managed by the ScriptRunner server.
New in the Portal: Target Configuration
The portal of Release 4 now contains all configuration settings for targets. The wizard included in the Admin App has been replaced by the new user guide. The overview displays the types as well as additional information about the targets.
When clicking the selection box at a list item, the additional buttons Edit, Run test and Delete appear in the display area above, next to the primary +Create button.
Clicking on the name opens the detailed configuration. Clicking on a tag places it in the global tag filter.
The extended line menu contains additional functions.
Creating a new Target
The details of the configuration are shown here using the target for M365 as an example. Several targets can be created, e.g., for different administrator teams or for managing different clients.
Note: Services that Microsoft has already discontinued are marked as deprecated. They are available, but users should refrain from using them.
The name, tags and description are stored in the General section. The following section depends on the type of the target and the context of its use. In the target for M365, the services to be used are now assigned by activating them. It must be ensured that no competing variants of a service are selected.
Dialogue adding one or more Microsoft Service
Then the details of the individual service must be set. You can get there by expanding the respective service configuration.
In the advanced settings, you can limit the parallel use of each target type by several actions running at the same time and set the behavior when the limit is exceeded.
Limitation of parallel actions executed on the target
When using jumphosts in complex infrastructures, it is possible to build bridgehead structures with ScriptRunner. This makes it possible to set defined paths for remoting through the infrastructure. It is also possible to use multiple jumphosts in series with ScriptRunner.
In the configuration below, the M365 target is controlled via the jumphost. The script runs in the configured rights context on the jumphost, and the ScriptRunner server collects the results and feedback. The necessary PowerShell modules must be installed on the jumphost in this case. This can be checked with the new advanced target test, which is available via button after saving. See the next section for details.
The typical double-hop problem of PowerShell when using jumphosts is solved by ScriptRunner on its own.
Automatic Module Detection and Advanced Target Testing
The ScriptRunner server functions have been extended by the automatic detection of PowerShell modules. For this purpose, the #Requires statement of PowerShell is evaluated. Typically, the statement is used in scripts to check whether the module is available in the PowerShell session at all before the actual function code is started.
Example
#Requires -Modules ActiveDirectory,ExchangeOnline,TeamsIt will check if these PowerShell modules are installed and available in the session. If not, the processing of the script is already aborted at this point. So the usage is very useful to avoid problems and errors in the later execution of the function code.
Automatically added system-tag
ScriptRunner automatically creates a tag for each recognized module. This tag can be recognized by the PowerShell icon for some settings. This has no influence on the use of the tag for filtering and display as before.
What is new is the use of these tags for advanced testing of a target. In addition to the connection establishment, it is also checked whether the modules would be available on the target, e.g., a remote system with its settings. For testing, the list of PowerShell modules to be tested can be added manually.
Target-test checking availability of a module, here AD PowerShell Module
Microsoft Graph as a New Service for M365 Targets
The target type for M365 has been extended with the service for the Microsoft Graph module. The use of Microsoft Graph with PowerShell enables the automation of complex relationships in the context of infrastructure, users, their content and various services and properties. It is strategic for Microsoft in that it should allow access to very diverse data as well as remove the limitations of PowerShell connections to a tenant because it works stateless with REST.
A first overview of Microsoft Graph with PowerShell can be found here:
https://docs.microsoft.com/en-us/powershell/microsoftgraph/overview
Creating an MS Graph target – options for certificate & client secret
The implementation in ScriptRunner follows the new user guidance for creating and configuring targets. The Microsoft Graph service can be added to an existing M365 target or one that is to be created. The current version of Microsoft Graph supports the two authentication methods with certificate or with client secret. If a certificate is used, the certificate must be stored in the local certificate store. If, on the other hand, a client secret is used, the name and secret must have been configured under Credentials. In both cases, a service principal must be set up in the tenant or the permissions must have been assigned to the registered ScriptRunner service.
Token-based Authentication for M365 Services
Microsoft has made modifications for logging in and using services. The new token-based authentication removes old references to AADGraph in the background and now uses modern methods with improved security.
Affected are the Teams PowerShell module from V4 as well as Microsoft Graph PowerShell modules. It is expected that other PowerShell modules will also be affected in the future.
In ScriptRunner, an automatic detection has now been implemented for the M365 target, which first determines the method and then uses the appropriate one.
This means that no changes to the configuration are necessary when a newer PowerShell module is used.
Upload of Files by Users for Bulk Operations
In the daily business of helpdesk and administrators it often happens that data sets have to be processed in bulk. Often the records are in CSV, TXT, XML or JSON format. A PowerShell script should be used to process the data sets, e.g., to create or lock user accounts, to change properties on systems or data objects.
ScriptRunner now offers the possibility to read the record file in the portal and pass the data stream as a parameter to the script.
Adding a fileupload option in your script
The example below shows the parameter declaration to pass a dataset file as a data stream to the script. The formats mentioned are supported. The recommendation is to limit to max. 1 MB.
<#
.SYNOPSIS
This is an example of using the fileupload for bulk operations.
The file type must be TXT, CSV, XML or JSON. The file size is limited to 1 MB.
.DESCRIPTION
With bulk operations, the same tasks, such as creating users or changing properties
on many objects, can be processed as a batch. You can use more than one batch file params.
.PARAMETER batchfile
Pls. drop your batch file into the field
#>
Param
(
[Parameter(HelpMessage="ASRDisplay(FromFile)")]
[string]$batchfile
)To allow maximum freedom and flexibility regarding the record structures used, a data stream is used instead of the file itself. The data stream corresponds to the encoding and the byte stream of the file. For parsing and assigning the single data to local processing parameters a PowerShell Function from a _LIB_ can be used. This has the advantage that this function can be used multiple times.
File upload File upload via drag & drop for bulk processing
The display in the Portal is done as a no-code parameter with a drop zone to read in the record file. Multiple data set files can also be read in. A separate data stream parameter is required for each one. If the action is then started, the read-in data can be processed in the PowerShell process.
Requiring Signed Scripts
ScriptRunner can now be forced to use signed scripts, regardless of the PowerShell Execution Policy settings on the ScriptRunner server.
This affects not only local execution of scripts on the ScriptRunner server itself, but also remoting, as ScriptRunner controls remote connections and refuses to process scripts without or with incorrect signatures. The functionality always includes _LIB_ and _QUERY_ scripts.
This function can be activated with the command:
Set-ASRSettings -SignedScriptsOnly yes/no
Conclusion
A lot has changed! Besides the technical enhancements, the focus of this release was on usability and accessibility. The center of the more modern, more intuitive navigation concept is the new main menu, for which the frontend development team first scrutinized the information architecture and then redesigned it.
For the first time, ScriptRunner is available in Spanish and French, in addition to English and German.
In addition to features such as drag & drop of files for automated bulk processing in ScriptRunner Actions, the Portal Edition R4 also includes the future-oriented topic of token-based authentication. This makes connecting to M365 services (Teams, Exchange Online, Graph) easier and more secure. ScriptRunner now supports the Microsoft Graph PowerShell module as a target for automating IT management tasks in Microsoft 365 and Microsoft Azure.
Our Video about the New Features in Portal Edition R4
#KeepOnScripting
This Way to Portal Edition R4!
Related Links
Related posts
About the author:
Frank Kresse is Head of Product and CEO of ScriptRunner. As the inventor of the automation and delegation solution for PowerShell, he advises clients on use case scenarios and develops solutions for the automation and the digitalization of their processes. He is also involved in technology start-ups.