Test environment

The use of PowerShell in administration and as an automation language is now widespread. Nevertheless, there are great uncertainties regarding a central administration of scripts, guidelines for the execution of scripts, rights and security, central logging and auditing, delegation options and much more. All reasons to test ScriptRunner in your own environment. This guide will help you.

For an initial product test, only a few systems in your infrastructure are required. In detail are needed:

  • Active Directory for creating a few security groups
  • Virtual machine for the ScriptRunner Server in a Windows domain with administrative access
  • Virtual machine as a target system in a Windows domain for remotely running PowerShell test scripts.
  • Client with a web browser (IE11, Edge, Chrome, Firefox or Opera)

To run the advanced test cases with Exchange, Office 356, file and print servers, Hyper-V or VMware, you need access to the appropriate systems.

This chapter has been translated by DeepL.

Yes No Suggest edit

Prepare for testing

Groups and Users in Active Directory

At least two security groups in Active Directory, an administrative user account and a standard user account are required for the minimum roles to function properly in ScriptRunner.

  • Administrative user account should also have administrator rights on the required test VM. We recommend to use your personal admin account if it has sufficient rights.
  • Standard user account does not require any administrative rights. We recommend to use your personal standard user account.
  • Security Group for ScriptRunner Main Administrators: Create a security group. This can be based on your naming conventions, e.g. “SR-Main-Admins”. Include your and other administrative user accounts in this group.
  • Security Group for ScriptRunner Service Desk Users: Create a security group. This can be based on your naming conventions, e.g. “SR-ServiceDesk”. Include your and other standard user accounts in this group. Existing security groups can also be used.

For end user self services:

  • Optional: Security group for ScriptRunner self-service end users. Create a security group. This can be based on your naming conventions, e.g. “SR-SelfService-User”. Include your and other standard user accounts in this group. Existing security groups can also be used.

For multi-team and multi-tenant operations:

  • Optional: Security group for ScriptRunner Administrators (team or tenant). Create a security group. This can be based on your naming conventions, e.g. “SR-AD-Team” or “SR-Customername”. Include the corresponding admin accounts in this group. Existing security groups can also be used.

Credentials with administrative privileges are required for the proper functioning of the PowerShell policies in ScriptRunner. You may create separate technical service accounts, use existing technical service accounts or use your personal administrative account for testing purposes only.

Virtual machine for ScriptRunner Server

It is recommended to install ScriptRunner Server on a virtual machine. The virtual machine requires the following basic settings:

  • Windows Server 2019, Windows Server 2016, or Windows Server 2012R2 as member server in a domain
  • CPU: min. 2 cores, productive environment min. 4
  • Memory: min. 8 GB RAM and 64 GB disk (SSD or similar preferred)
  • .NET Framework 4.6 or higher
  • Management Framework 5 with PowerShell 5.1
  • WinRM Service is active
  • PowerShell Execution Policy and PowerShell Remoting is enabled, including the firewall rules.
  • Internet Explorer 11 with valid local intranet zone and enhanced security disabled (in Server Manager)

In addition, you should use Server Manager to install the Active Directory PowerShell Module feature from the Remote Server Administration Tools -> Role Management Tools -> AD and DS Tools feature group.

Setting Up the Web Server Role on the Server

The ScriptRunner Web Apps are JavaScript applications and run in Edge, Chrome, Firefox, Opera and Internet Explorer 11. A web server is used to distribute the Web Apps to the clients. Use the IIS on the ScriptRunner Server for testing and to install the role “WebServer (IIS)” with the administration programs without any additional features. For the test you use the IIS and the ScriptRunner Web Apps over HTTP. Before a later productive use you can reconfigure the IIS and the Web Service on the ScriptRunner Server to HTTPS.

Note

Internet Explorer 11 uses an outdated rendering engine to render Web pages. This can lead to display and performance problems in the ScriptRunner apps.

Second server for testing with PowerShell Remoting

A second test machine is required to run PowerShell scripts using PowerShell Remoting. You can also use an existing test machine. In an initial functional test, only PowerShell scripts that do not make any changes to the system are executed. The virtual machine and ScriptRunner access require the following basic settings:

  • Windows Server 2019, Windows Server 2016, or Windows Server 2012R2 as member server in a domain
  • WinRM service on the second machine is active
  • PowerShell Execution Policy and PowerShell Remoting is enabled, including the firewall rules.
  • Technical service account or administrative account that is authorized to run PowerShell scripts on this machine.

Open PowerShell as an administrator and use the following commands:

> Get-ExecutionPolicy -List 
> 
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine -Force -Verbose 
> 
> Enable-PSRemoting -Force

Check to see if the PowerShell settings on both virtual machines are controlled by GPO! You can also use PowerShellConfigWizard.EXE from our setup package to configure the PowerShell settings.

If you work with firewalls or proxies

Make sure that the two test VMs are accessible from your client browser via HTTP. In addition to port 80, port 8091 is also required for REST communication with the ScriptRunner Web Service Interface. The default port 5985 for WinRM/PowerShell is used for communication between the ScriptRunner Server and the second server via PowerShell Remoting. This should be enabled on the local firewall as well as in an intermediate firewall if necessary. When PowerShell Execution Policy and Remote Powershell are enabled, all necessary settings are automatically made to the local Windows Server firewall. Here you can learn more about the protocols and ports used in detail.

This chapter was translated by DeepL.

Yes No Suggest edit

Quick install

Only use the current ScriptRunner setup files to perform the installation. You can request these on our support site. A link to the download of the setup files has already been sent to you in the same email with the link to this guide.

  1. Take a snapshot of the ScriptRunner Server VM before installation.
  2. Unpack the ZIP file containing the setup files on the ScriptRunner Server VM.
  3. Run SetupScriptRunnerService_version.EXE first

The central ScriptRunner service and all functions of the ScriptRunner Server as well as a set of Windows performance counters are installed on the virtual machine.

Important note

Change the group for the ScriptRunner Main Administrators on the appropriate setup page. To do this, enter the group name of the security group you created for it and press Verify. The security claim for this group is displayed. If an error occurs, the connection of the ScriptRunner Server to the Active Directory is disturbed.

Check the newly installed “ScriptRunner Service”. The service must have started. If any errors occur during installation, check the setup log in
Drive:\Program Files\ScriptRunner\ScriptRunnerService

Second execute SetupScriptRunnerWebApps_version.EXE with the option Deploy to IIS. Enter the complete FQDN of the ScriptRunner Server on the corresponding setup page and use the default port 8091. Leave the SSL inactive!

Tip

During installation, the setup checks whether the ScriptRunner Web Service is accessible via HTTP (or HTTPS) under the specified URI.

If you want to use the ScriptRunner ISE App on your Admin and DevOps clients, run SetupScriptRunnerTeamApps_version.EXE and select the option “ISE Plugin” and deselect the other two apps. If you want to use the ISE PlugIn, your client logon account must be a member of the security group for ScriptRunner Main Administrators or ScriptRunner Administrators.

This chapter was translated by DeepL.

Yes No Suggest edit

Easy initial configuration

The PowerShell module ScriptRunnerSettings is used for the unique settings on the ScriptRunner Server. Open the PowerShell as an administrator. Enter the following commands:

> get-asrlicense # output the license information
>
> get-asrservice # output the status of ScriptRunner service
>
> test-asruri    # output the status of web service endpoint

Use the following commands to configure the e-mail notification functions to send notifications via SMTP:

> # Displaying the default settings at the connector  
> Get-ASREmailNotificationConnector -Verbose 
> 
> # Configure the connector 
> Set-ASREmailNotificationConnector -ON -Host 'MyHostName' -Port pnr -UseTLS yes/no -Sender scriptrunner@mydomain -Restart -Verbose 
> 
> # Send a test e-mail 
> Test-ASREmailNotificationConnector -Receipient Empfaenger@MyDomain

Note

To use authentication for e-mail, use the other options in the Set- cmdlet. SMTP error codes are displayed if errors occur when sending the test e-mail. Check the logs of your mail server for errors.

This chapter was translated by DeepL.

Yes No Suggest edit

My first use

Log on to a client with your administrative account and start a web browser. Enter the following URL:

  • http://FQDN_of_ScriptRunner_Server/scriptrunner/admin -> the Admin Web App is loaded
  • Select the green “Test” button on start screen.
  • You can optionally switch the language in the app. To do this, select the language in the top right-hand corner of the Top Bar of the application.

Note

If you are using Internet Explorer, the domain ID from the ScriptRunner Server’s FQDN must be entered in the Security Settings of the Local Intranet Zone. Under certain circumstances these settings are set by GPO for the browser and the domain of the ScriptRunner Server is not listed!

Optionally you can start the Admin App directly in Internet Explorer on the ScriptRunner Server. To do this, switch off the enhanced security options for IE with the Server Manager. Also use the complete FQDN in the URL on the server.

ScriptRunner Admin App with Dashboard, top menu, main menu on the left and Action bar on bottom line

ScriptRunner Admin App with Dashboard, top menu, main menu on the left and Action bar on bottom line

To test the functionality of the script execution, to do following:

  1. Click in the main menu of the Admin Web App on the left side the item Actions.
  2. In the list view, select the action with the name “Local: Add two values”.
  3. Start the action with the button Run in the context-oriented Action Bar at the bottom of the application. The Action Wizard appears in RUN mode with an input mask for the PowerShell parameters with two prefilled fields.
  4. Now click the OK button at the bottom of the wizard. Now the PowerShell script is executed, which adds two numbers.
  5. After the execution of the script a green bar appears in the line of the action. Click on the bar and display the report.
  6. Repeat the action and choose other options. Note that numbers and strings cannot be mixed together.
  7. Now switch to the main menu and select the Dashboard. There you can click on individual reports as well as use different display options.
  8. In the dashboard, click the button Reports at the Action Bar downstairs. In the report display, you can now scroll through the individual reports and use the various display options in the top right corner of the report window.

 

Contextual Action bar with help button

Contextual Action bar with help button

 

This chapter was translated by DeepL.

Yes No Suggest edit

Setting up & testing a delegation

Now first configure a group in the role Service Desk User. Users with this role can use the ScriptRunner Delegate Web App and start pre-configured PowerShell actions without needing administrative permissions on the target systems. To do this, do the following:

  1. Switch to the main menu Delegation.
  2. Click on the button Create. The wizard for creating operator groups and operator accounts opens. Select the Role Service Desk User and click Next.
  3. Enter a display name for the group and go to the next wizard page.
  4. Enter the name of the security group in the Active Directory for the Service Desk and press the Verify button. In the Claim type field, a string appears with group-sid at the end.
  5. Go to the assignment page and click on the action “Local: Add two values” from the list. Multiple selection can be made with the CTRL+left mouse button.
  6. Complete the settings and assignment with OK.
  7. Switch to the main menu Actions and select the action.
  8. In the Action Bar, click the button below Delegate. The Action Wizard opens in EDIT mode and displays the configuration page for the delegation for this action.
  9. Enter a tag identifier “MyRegister” without spaces. Select a color for the action tile in the Delegate app. Optionally, you can oblige the user to fill out the cause field before starting the actions.
  10. Finish with OK.
Delegate App, ScriptRunner, Listview and Tileview

ScriptRunner Delegate App – List view (left) and Tiles view (right)

Now log on to a client with your default user account and start a web browser. Enter the following URL:

  1. http://FQDN_ScriptRunner_Server/scriptrunner/delegate -> the Delegate Web App is loaded.
  2. Now select the tab All and then the register MyRegister.
  3. Click on the tile “Local: Add two values”. An input mask appears for the PowerShell parameters with the two prefilled fields.
  4. In the Reason field, type a comment about the action, such as a reference to a ticket number.
  5. Start the action by pressing the RUN button in the Action Bar at the bottom.
  6. Wait for finalising the execution.
  7. Click in the modal display window the link Report or in the Action Bar the button Reports.
  8. Repeat the action and choose other options. Note that numbers and strings cannot be mixed together.

Now switch to the Admin App on the main menu Actions and select the action “Local: Add two values”. Now click on the Button Reports in the Action Bar below. You can then scroll through all the reports, and so on. Pleas note the different information in the metadata block above.

This chapter was translated by DeepL.

Yes No Suggest edit

My first PowerShell Remoting

After a successful initial functional test, the system for testing remote management with PowerShell is now included in ScriptRunner and an action is configured to run a script on a remote machine. The built-in wizards support you during setup. In addition to the ?-Help in the Action Bar, each Assistant Page has a ?-Helpbox that contains additional information.

ScriptRunner Infobox on each wizard page

ScriptRunner Infobox on each wizard page

To do this, to set up an action for PowerShell Remoting to the second server, do the following:

  1. Open the Admin Web App and switch to the main menu Credentials and click the button Create.
  2. Capture an administrative service account that is authorized to run PowerShell scripts on the second server (remote system). Tip: Create domain service accounts in the domain\account notation. Finish the process with OK.
  3. Now switch to the main menu item  Targets and mark the target with the name “Sample Target”.
  4. Click the button Edit at the Action Bar downstairs. The configuration wizard opens in EDIT mode.
  5. Change the display name – recommended Windows computer name – and the registered FQDN to the actual FQDN of the second server (remote system).
  6. Select the PS Remoting Credential you have created under 2). Finish with OK.

After the second server (remote system) is known in ScriptRunner and linked to the Credential, a PowerShell Script Policy is created. To simplify the process, proceed as follows:

  1. Switch to the main menu Actions and mark “Local: Add two values”.
  2. Now click the button Copy at the Action Bar downstairs. A copy of the action is created and displayed in the list with the extension “– Copy“.
  3. Select the copy in the list and click Edit at the Action Bar. The wizard opens in EDIT mode.
  4. Change by clicking on the first Wizard Page Action Properties and change the name of the action, e.g. to “My First Remote Test”.
  5. Change by clicking on the second Wizard Page Select Targets and select the second server you configured (Remote System).
  6. Skip the third wizard page.
  7. Change by clicking on the fourth Wizard Page Assign Parameter Values and select the value “Select a value” in both dropdown menus.
  8. Click on the fifth wizard page to switch to the next wizard page Set Result Options & Notifications. Mark e-mail notifications, select the “Always” option and enter your e-mail address. Tip: For proper operation, the E-Mail Notification Connector must be set up as described above.
  9. Finish with OK.

Now the first PowerShell Script Policy is set up for a test with PowerShell Remoting. To test it with the Admin Web App and the Delegate Web App, use the My First Remote Test action to complete the steps described above in My first use and Setting up and testing a delegation chapter.

Note

If errors occur during execution, carefully read the PowerShell error messages in the report and check the following settings:

  • On the second server (remote system):
    • WinRM Service must be active.
    • PowerShell Execution Policy must be turned on and configured to Remote Signed.
    • PowerShell Remoting must be enabled.
    • The account entered under Credentials and used for remoting must have permission to run PowerShell scripts.
    • Tip: A domain-wide PowerShell GPO can make other settings effective!
  • On the ScriptRunner Server in the Admin Web App:
    • Check at the target system settings whether the FQDN is correct and the correct credential has been assigned.
    • Check the action settings to see whether the correct target system has been selected.
    • If an error has occurred in the authentication method, you can change it on the wizard page “PS Remoting Session Settings” with the option “use a non-default PS Remoting authentication method“, e.g. on Kerberos.
    • Check the Credential, enter the name of the account and password correctly.

This chapter was translated by DeepL.

Yes No Suggest edit

Advanced testing

In order to quickly achieve results with the extended test cases, corresponding scripts and configurations are already included in the setup, which are available immediately after installation.

The extended test cases demonstrate selected capabilities and functions of ScriptRunner in cooperation with the following systems:

  • Multi-Team and Multi-Tenant operations
  • Active Directory
  • Exchange Server
  • Office365
  • Azure

In this context the following features of ScriptRunner are the focus of the tests:

  • Mapping of the same use case using local and remote PowerShell settings
  • Increased interactivity by querying Active Directory and lists
  • Increased interactivity through scripted queries to different systems
  • Use of PowerShell modules locally and remotely
  • Use of library scripts

In addition, team scenarios for different responsibilities can be tested.

This chapter was translated by DeepL.

Yes No Suggest edit

Multi-Team & Multi-Tenant

Additional groups in the Active Directory

For proper functioning in the multi-team and multi-tenant operation in ScriptRunner, two additional security groups in the Active Directory with corresponding user accounts are required.

  • Security groups forScriptRunner administrators (team or client). Create two more security groups. These can be based on your naming conventions, e.g. “SR-AD-Team” or “SR customer name”. Include the corresponding admin accounts in this group. Existing security groups can also be used.

Start the ScriptRunner Admin App in the browser as the main administrator. Then select the main menu Delegation. Click on Create in the Action Bar. Select the role Administrators (Team) and follow the wizard. Proceed in the same way for the second group in ScriptRunner.

Add a group in ScriptRunner

Working as an administrator in a team or tenant

Log on to a client with an administrative account in the Administrators (Team) role and start the Web browser.

Enter the following URL:

  • http://FQDN_of_ScriptRunner_Server/scriptrunner/admin -> the admin web app is started in the context of an administrator or client
  • Select the green “Test” button on the start screen.
  • You can optionally switch the language in the app. To do this, select the language in the top right corner of the top bar of the application.

 

ScriptRunner Multi-Team Multi-Tenant

Admin groups for multi-team and multi-tenant operations

Switch to one of the other main menus and create a new credential with Create and then a new PowerShell Remoting target system. Assign the created credential to the target system in the wizard.

Ownership of Policy Elements

ScriptRunner actions consist of various policy elements: scripts, administrative accounts, target systems, and queries. Both actions and other elements can now be from the PRIVATE USE or PUBLIC USE setting.

PRIVATE USE symbolizes the assignment to a specific admin team or client. All elements and actions that have been assigned can only be used by this admin team or client.

PUBLIC USE implements the common use of individual elements and actions.

PRIVATE USE beats PUBLIC USE. This means that elements that have been assigned to an admin team or client cannot be used in higher-level elements and actions that are PUBLIC USE. Conversely, PUBLIC USE elements can always be used as subordinate elements in PRIVATE USE elements.

DELETE GROUP leads to PUBLIC USE. If the group of an admin team or client is deleted in ScriptRunner, all elements associated with this group are reset to PUBLIC USE.

The deletion of such a group is only possible by a main administrator.

This chapter was translated by DeepL.

Yes No Suggest edit

Self Service for end users

Now first configure a group in the Rolle Self-Service end users. Users with this role can use the ScriptRunner Self-Service Web App and start pre-configured PowerShell actions without requiring administrative privileges on the target systems. To do this, do the following:

  1. Start the Admin App in the role of the Main Administrator.
  2. Switch to the main menu Delegation.
  3. Click on the button Create. The wizard for creating groups and accounts opens.
  4. First select the role Self-service end user and clickNext.
  5. Then enter a display name for the group and go to the next wizard page.
  6. Enter the name of the security group in the Active Directory for the self-service end users and press the Verify button. In the Claim Type field, a string appears with group-sid at the end.
  7. Go to the assignment page and click on the action Local: Add two values from the list. Multiple selection can be made with the CTRL mouse button.
  8. Complete the installation and assignment with OK.
  9. Switch to the main menu Actions and select the action.
  10. In the Action Bar, click the button below Details. The Delegations for this action are listed below in the details view.
  11. Change by clicking again on Details to the main overview.
Self-Service App, ScriptRunner

Self-Service App to delegate task to the end users

Now log on to a client with your standard end user account start a web browser. Enter the following URL:

  1. http://FQDN_ScriptRunner_Server/scriptrunner/selfservice-> the Self-Service Web App is loaded.
  2. Click on the tile “Local: Add two values”. An input mask appears for the PowerShell parameters with the two prefilled fields.
  3. Start the action by pressing the RUN button in the Action Bar at the bottom.
  4. Wait until the execution is complete.

This chapter was translated by DeepL.

Yes No Suggest edit

Active Directory Test Case

Preparations

For this test case you need access to the Active Directory using:

  • installed Active Directory PowerShell Module on the ScriptRunner Server. You can install the module using the Server Manager. To communicate with the Active Directory, the module uses the LDAP and ADWS protocols.
  • PowerShell Remoting to a selected Active Directory Controller. WinRM and PowerShell Remoting must be enabled on the controller. The WinRM/PowerShell-Remoting protocol is used for communication with the Active Directory Controller.

Note

Only scripts with Get cmdlets are used for this test case.

Learn how it work ScriptRunner locally and remotely with PowerShell

When you use the Active Directory module on the ScriptRunner Server, you use the local execution mode of PowerShell scripts. Starting an action in ScriptRunner leads to the following simplified steps:

  1. A local PowerShell process is created. You can recognize this in the Windows Taskmanager as SRXPSHost.exe.
  2. All necessary information, scripts, credential references, etc. are transferred to this process.
  3. The script starts and calls the cmdlets in the local Active Directory module.
  4. The local Active Directory module establishes a connection to the primary Active Directory controller. You can also check this with the command Get-ADRootDSE on the PowerShell console of the ScriptRunner Server.
  5. The commands of the PowerShell script are transformed by the Active Directory module into LDAP calls and ADWS communication.
  6. The results of the calls are re-transformed by the Active Directory module to PowerShell return values and passed to the local PowerShell process on the ScriptRunner Server.
  7. After finishing the script, the local PowerShell process is terminated.
  8. The PowerShell report in ScriptRunner completes.

The local mode of operation results in some consequences, which you should consider when planning use cases with ScriptRunner:

  • PowerShell modules that are required by locally executed scripts must be installed on ScriptRunner Server.
  • Communication protocols other than WinRM/PowerShell remoting are used. This concerns the local firewall of ScriptRunner Server and target systems as well as intermediate firewalls and proxies.
  • The control and processing load for executing the scripts is concentrated on the ScriptRunner Server. The remote system, here the Active Directory, is relieved of PowerShell processing.
  • a high concentration of control and processing load on the ScriptRunner Server requires an appropriate sizing.
  • Loading the script and modules and running them in the local PowerShell process is faster than using PowerShell Remoting.

Note

Scripts should not always be executed locally on the ScriptRunner Server. The functionality of the script, its runtime and the programmed output behavior are decisive for this. The mode of operation and protocol transformation in the PowerShell modules used are also important. Many manufacturers use cmdlets to transform the command sequences of a script into web service REST calls to their interface. Details should be taken from the relevant manufacturer documentation.

 

A completely different way of working is to use PowerShell Remoting. The Active Directory module is used on an AD controller. In ScriptRunner, a target system, here an AD controller, must be configured with settings for PowerShell Remoting. Starting an action in ScriptRunner leads to the following simplified steps:

  1. A local PowerShell process is created. You can recognize this in the Windows Taskmanager as SRXPSHost.exe.
  2. All necessary information, scripts, credential references, etc. are transferred to this process.
  3. WinRM/PowerShell remoting attempts to connect to the Active Directory Controller.
  4. If the connection was successfully established, a standard PowerShell process is also created on the remote Active Directory Controller.
  5. The script and all necessary information is transferred to this remote process.
  6. The script is started in the remote process and the command sequence is processed with the Active Directory module on the Active Directory Controller.
  7. The connection between the local PowerShell process on ScriptRunner Server and the remote PowerShell process remains in place to transfer output to the ScriptRunner Server.
  8. After finalising the script processing on the Active Directory Controller, the remote PowerShell process stops.
  9. After stoping the remote PowerShell process and the results are fully transferred, the local PowerShell process is ended on ScriptRunner Server.
  10. The PowerShell report in ScriptRunner completes.

This way of working results in some consequences, which you should consider when planning PowerShell Remoting use cases with ScriptRunner:

  • Remote systems to be addressed with PowerShell Remoting must be enabled.
  • WinRM/PowerShell remoting is used as the communication protocol. This concerns the local firewall of ScriptRunner Server and target system as well as intermediate firewalls and proxies.
  • PowerShell modules that are required by the scripts to run must be installed on the remote system.
  • The processing load for executing the scripts is on the remote target system.
  • The ScriptRunner Server retains the control load for communicating with the remote PowerShell process.
  • Establishing and closing the connection via PowerShell Remoting, creating the remote PowerShell process, loading the modules, and processing the script affect the overall performance of an action.

Note

Remote execution of scripts is only possible with systems that can generate PowerShell processes and process scripts. There are different default endpoints for communicating with the target system, such as Exchange PowerShell. The functionality of the target system is decisive for this. For all target systems, which do not offer such a possibility, the scripts must be processed in the local execution mode.

Testing with Action Get-ADUserProperties

Start the Admin Web App and change main menu Actions and select the Action Get-ADUserProperties. Click on the icon Details in the Action Bar. The view changes to the detailed view and displays all policy items associated with the action.

scriptrunner_action_getaduserproperties

Details view auf the action Get-ADUserProperties.

 

The target system displays ADC Remote with a connected credential, indicating remote execution of the PowerShell script. Below this is the script with two PowerShell parameters connected by ScriptRunner Queries.

Tip

You can edit the individual policy elements directly in the detail view by selecting the element and clicking Edit below in the Action Bar.

To pass the test successfully, the PowerShell module for Active Directory must be installed on the ScriptRunner Server. They must also have stored a credential valid for in your environment for the target system. You can edit the Credential AD Admin directly or create a new credential in the main menu Credentials. If you have created a new credential, assign it to the target system AD local. To do this, edit the target system AD local and select the created credential.

ScriptRunner Target Credential

Select the credential for the script execution on this target.

 

The next step is to select the List of OUs from AD policy element. This and the next element is a preconfigured ScriptRunner AD Query. The first of both queries all OUs of the next level from a starting point in the Active Directory tree and displays them in the input forms as a selection dropdown. Click Edit and check the query settings for your Active Directory. If you want to search in another, untrusted domain, you have to set the search domain at the top. Set the SearchBase to the starting point of the search in your Active Directory in a string like OU=myou,DC=mydomain,DC=mydomain.

scriptrunner_query_serachbase

Edit the search base for the query.

 

Now select the List of Users from AD policy element. This preconfigured queries all active users from a starting point in the Active Directory and displays them in the form as a selection dropdown. Click Edit and check the query settings for your Active Directory. If you want to search in another, untrusted domain, you have to set the search domain at the top. Set the SearchBase to the starting point of the search in your Active Directory tree in a string like OU=myou,DC=mydomain,DC=mydomain.

scriptrunner_query_user

Configure the user query, esp. search base

 

Note

The SearchBase in the configuration contains the default setting for this query and is overwritten by cascading. It is recommended to use default settings if certain, e.g. administrative branches in the Active Directory, are not to be taken.

You can test the ScriptRunner Queries by switching to the main menu Queries, selecting the relevant query, and clicking the Test icon in the Action Bar. The query can be started by clicking on the blue triangle. The first 100 results of the query are displayed.

 

scriptrunner_query_test

Testing the query by clicking the blue triangle.

 

The execution and display options of a query can also be changed during editing by scrolling one page forward in the configuration wizard. If the expected result set of the query is greater than 500 entries, deactivate the Automatic Query Execution option.

Then select the action and click Edit. The PowerShell parameters page appears in the Configuration Wizard. The parameter $Username allows you to view linking the AD queries. The SearchBase of the Query List of Users from AD is controlled by the parameter $OUPath with the result of the Query List of OUs from AD.

scriptrunner_action_queries

Linking parameters and queries in the action.

 

In the wizard, go to the page for target system selection and select the target system AD local.

If you only want to provide a preconfigured selection of OU paths, you can also use a static list query instead of the AD Query List of OUs from AD. To do this, select the Query Static List of OUs for the $OUPath parameter. Confirm the change with OK. Then click Reload in the Action Bar, and then select this query for editing. Then enter the corresponding OU paths and the display names in the list and end with OK.

scriptrunner_list_query

Configure List Query with display and parameter values.

 

When you have made all the adjustments, stop editing and click the Run icon in the Action Bar. Then click on the blue Osiris in the lower right corner and select the action started in the popup. The view changes to the live report and you can follow the execution of the action. When you have finished the action, you see the complete report. Then switch back to the list view in the main menu Actions and start the action again. You can then filter the dashboard for reports of this action.

scriptrunner_osiris

Open popup list by clicking the Osiris and click the entry.

Error Notes

If errors occur while executing the action, read the error messages and notes carefully. They refer to the causes. Check above all:

  • PowerShell module for Active Directory must work on the ScriptRunner Server. Start the PowerShell console in the context of the deposited administrative account and call the CmdletGet-ADRootDSE.
  • The administrative account (credential), which is used by the target system must be valid and correctly stored (password !!)
  • AD local and ADC Remote can be used as target system. Check the target system configuration and the requirements for remoting.
  • The two queries must work by testing both separately. Check the stored default SearchBase.
  • The referenced script must not have been moved or deleted.

This chapter was translated by DeepL.

Yes No Suggest edit

Exchange Server Test Case

Preparations

For this test case you need access to the Active Directory and to an Exchange Server using :

  • installed Active Directory PowerShell Module on the ScriptRunner Server. You can install the module using the Server Manager. To communicate with the Active Directory, the module uses the LDAP and ADWS protocols.
  • PowerShell Implicit Remoting to a selected Exchange Server. The Exchange PowerShell must be active on this. Communication with the Exchange Server uses the default settings for the Exchange PowerShell (port 80) with the URI of the Exchange Server.

Note

Only scripts with Get cmdlet are used for this test case.

About how Exchange PowerShell works

When you use Exchange PowerShell with ScriptRunner, PowerShell Implicit Remoting is used. It imports the interface and cmdlets of the PowerShell Module for Exchange into the PowerShell process on the ScriptRunner Server. This method of working largely corresponds to a New-PSSession followed by an Import-PSSession on the interactive console.

Note

The installation of Exchange PowerShell on the ScriptRunner Server is NOT necessary and should be omitted.

Starting an action in ScriptRunner leads to the following simplified steps:

  1. A local PowerShell process is created. You can recognize this in the Windows Task Manager as SRXPSHost.exe.
  2. All necessary information, scripts, credential references, etc. are transferred into this process.
  3. It connects to the Exchange Server and imports the Exchange PowerShell module into the local PowerShell process. The import generates a local interface module with the cmdlets. These can now be used directly in the local process.
  4. The script starts and calls the cmdlets in the temporary Exchange PowerShell module.
  5. The temporary module communicates with the Exchange Server through the PowerShell Web Service URI.
  6. The commands of the PowerShell script are transformed by the local, temporary module into PowerShell Web Service calls.
  7. The results of the calls are transformed back by the temporary module and further processed by the PowerShell process.
  8. After the script is completed, the imported session is terminated and the temporary, local module is terminated with the PowerShell process.
  9. The PowerShell report in ScriptRunner completes.

This way of working in Exchange PowerShell results in some consequences that you should consider when planning use cases with ScriptRunner:

  • PowerShell Implicit Remoting is always used to communicate with the Exchange Server.
  • The Exchange PowerShell Web Service URI is always used. By default, port 80 with integrated encryption is used. This concerns the local firewall of ScriptRunner Server and Exchange Server as well as intermediate firewalls and proxies.
  • The DNS-FQDN of the Exchange Server must always be specified as the target system. DNS records for OWA and other Exchange services cannot be used.
  • The control and most processing load for executing the scripts is concentrated on the ScriptRunner Server. The remote Exchange Server is relieved of PowerShell processing.
  • High concentration of control and processing load on the ScriptRunner Server requires an appropriate sizing.
  • Setting up and importing the session to the Exchange Server and creating the temporary, local module requires an initialization time that is influenced by many factors.

Tip

However, by setting up the Exchange role for the service account, which ScriptRunner uses as the administrative credential, you can control which and how many cmdlets are imported at runtime. This allows you to shorten the required initialization time.

Testing with Action Get-MailboxProperties

Start the Admin App and change to main menu Actions and select the Action Get-MailboxProperties. Click on the icon Details in the Action Bar. The view changes to the detailed view and displays all policy items associated with the action.

scriptrunner_action_getmailboxproperties

Details view of the Action Get-ExMailboxProperties.

 

The Exchange Server element with a connected credential is displayed as the target system. Below this is the script with a PowerShell parameter connected by a ScriptRunner Query.

Tip

You can edit the individual policy elements directly in the detail view by selecting the element and clicking Edit below in the Action Bar.

To pass the test successfully, you must customize the configurations for the following policy items:

  • Credential – You need a valid administrative account in your environment to access Exchange Server. Select Exchange Admin and Edit directly or create a new credential in the main menu Credentials.
  • Target System – Select the target system and Edit the name and FQDN to a valid Exchange Server. If you have created a new credential, assign it to it.
    Click the next page to check the settings for Exchange PowerShell. Scroll down to the bottom and click Advanced Connection Options. Enter SkipCNCheck=1 there. This option suppresses possible Exchange certificate errors to avoid installing Exchange certificates on the ScriptRunner Server. Then click OK.
scriptrunner_exch_target_remoting

Configure the remoting options to access an exchange server.

 

In the next step, select the List of Mailboxes from AD policy element. This element is a preconfigured query to the Actice Directory. This queries all mailboxes of active users and displays them in the input form as a selection dropdown. Click Edit and check the settings for your Active Directory.

  • If you want to search in another, untrusted domain, you have to set the search domain at the top.
  • The selected option Attribute Filter Pattern contains the AD attribute [HomeMDB] without value. This means that the search for the user objects is filtered for an existing user attribute [HomeMDB]. Only user objects with an Exchange mailbox have this attribute. The free field Attribute value ensures that the search finds all hits, no matter in which MDB the mailbox is located.
  • Set the SearchBase to the starting point of the search for mailboxes in the Active Directory in the formOU=myou,DC=mydomain,DC=mydomain. Select a useful starting point below root to exclude the display of Exchange system mailboxes.

Then confirm everything with OK.

scriptrunner_query_mailbox

Configure the mailbox query esp. attribute pattern and the search base.

Note

The SearchBase in the configuration contains the default setting for this query and is overwritten by cascaded queries. In this way, a higher-level query can determine OU paths and make them available for selection. The search for the mailboxes then refers to all user objects below the selected OU path. You can find an example of this in the Active Directory Test Case.

You can test the query List of Mailboxes from AD by switching to the main menu, selecting the relevant query, and clicking the Test icon in the Action Bar. The query can be started by clicking on the blue triangle. The first 100 results of the query are displayed.

The execution and display options of a query can also be changed during editing by moving one page forward in the configuration wizard. If the expected result set of the query is greater than 500 entries, deactivate the Automatic Query Execution option.

Tip

If you do not use cascaded queries, you can also set the query mode from real-time to one of the cache options. The cache is kept in the main memory of ScriptRunner Server.

Then select the Get-MailboxProperties action and click Edit. The PowerShell parameters page appears in the Configuration Wizard. The parameter $MailboxID allows you to check the link to the selected query.

scriptrunner_action_queries_mailbox

Linking parameters and queries in the action.

 

When you have made all the adjustments, stop editing and click the Run icon in the Action Bar. Then click on the blue Osiris in the lower right corner and select the action started in the popup. The view changes to the live report and you can follow the execution of the action. When you have finished the action, you see the complete report. Then switch back to the list view in the main menu Actions and start the action again. You can then filter the dashboard for reports of this action.

Error Notes

If errors occur while executing the action, read the error messages and notes carefully. They refer to the causes. Check above all:

  • The administrative account (credential) used by the target system Exchange Server must be valid and correctly stored (password !!) The account must have a valid Exchange role.
  • Implicit remoting of the Exchange PowerShell to the Exchange Server must work on the ScriptRunner Server. Start the PowerShell console in the context of the deposited administrative account. Create and import a new PowerShell session to the Exchange Server manually. You can also check which cmdlets are loaded for the administrative account you are using. If necessary, the assigned Exchange role is not sufficient.
  • The AD query to finding mailboxes must work. Test this separately. Check the stored default SearchBase before.
  • The referenced script must not have been moved or deleted.

This chapter was translated by DeepL.

Yes No Suggest edit

Would you like to open a support ticket?

  • Click on the picture.
  • Describe the problem.
  • Submit your e-mail.
  • Receive Ticket-ID from us.

Alternatively, you can register in our ticket system and open a ticket.

Yes No Suggest edit

Would you like a personal online meeting?

  • Select date
  • Fill in the form and submit


Yes No Suggest edit
Suggest Edit