Path: Administration\PowerShell Scripts

The PowerShell Scripts Panel is a repository for scripts that can then be called by other sections such as...  Scheduled Tasks, System Events, UI Buttons or by ESM during Plan Evaluation or Plan Actions

Scripts can be stored as text and will use the default API template or if the script is too big the path of the script file can be stored instead. If the script is held as text ManagementStudio will automatically keep a history of any changes made to the script.

Additional Columns

The grid of PowerShell Scripts has many of its columns hidden by default to make using it easier. These columns can be turned on by clicking the icon on the toolbar and selecting the additional columns to display. 

Grid Columns

Script

Id

The Script Id that can be used when creating Script Buttons on Surveys or DMR reports.

Script Name

The name of the script will be shown in the UI such as in the UI Buttons Panel. This will also be used to name the log file for the script.

Category

An optional category to help group similar scripts together in the UI.  The Category name automatically creates a folder in the PowerShell Tree view for easier organisation of scripts.

Is Enabled

Control if the script can be executed without having to unlink it from UI Buttons or Scheduled Tasks

Description

An optional description of what the script does. This is only for UI info and is not used anywhere else. 

Edit Button

The Edit button pops open a new window allowing editing of the full PowerShell Script. Changes to the script are automatically tracked by ManagementStudio. This will be run unless a Script Path is specified in the next column - see below.

Script Path

For longer and more complicated scripts it can be easier to provide a path to the script file. Changes to this file are not tracked by MigrationStudio. A script path (e.g. c:\scripts\myScript.ps1) supersedes the 'Script Text' option and will run in its place if both are present. 

Scripts from Paths are not wrapped in the same template wrapper that Scripts from text are and must setup their own connection to the API. They do however receive all the same arguments. 

If a script path has been entered ManagementStudio looks for the script in three locations.

1. The explicit path.
   e.g. If the path is 'c:\scripts\myScript.ps1' MS will look for the script in that location. 
2. Project Scripts folder. 
   e.g. If the path is 'path\myScript.ps1' then the '[StorageFolder]\path\Scripts' folder will be checked
3. Automation Scripts folder. 
   e.g. If the path is 'myScript.ps1' then the 'wwwroot\Automation\Scripts' folder will be checked

Options

Module

Scripts should target a specific module in ManagementStudio, e.g. A script that updates Applications if an App is superseded. When a module is picked it will filter the available event triggers to only events available to that module. It will also filter the scripts a UI Button can target only scripts in that module that contains the UI Button. The script module is passed to the PowerShell script in the 'Module' variable. 

Run As

When a script is called it is passed an account to 'Run As'. This allows scripts to have their permissions restricted to that of the running account and to record any changes the script makes to data to be recorded against that account. This makes scripts safer and changes tracking more transparent. For an account to be listed in the 'Run As' dropdown it must be in the 'Project Permissions \ Run Script As' role. By default the 'Api Account' that ships with ManagementStudio are in this role. 

Priority (hidden)

If multiple scripts are run at the same time, e.g. multiple jobs in the same Scheduled Task then the scripts are executed in order of priority with the lower number going first.

Grant Access  1,2, 3 (2, 3 hidden) 

Defines the role that the User must be a member of to be allowed to run this script. 

Schedule 1, 2, 3 ( 2, 3 hidden)

Scripts can be subscribed to a Scheduled Task (S-Task) and be called when that Scheduled Task fires. Individual S-Tasks can call a script multiple times, e.g. an S-Task that runs every two hours. A script can be assigned to run on up to three separate S-Tasks. e.g. '9am S-Task' , '1-pm S-Task', '7pm-S-Task'. 

Trigger & Sub Trigger

Scripts can be called automatically when specific events trigger in ManagementStudio. e.g. A script can be run when an Application is archived or when a  User moves Process. Scripts can be assigned to run on up to three different triggers.

Note: If a script needs to run for more than three different triggers; then copy the PS Script to a new line on the grid with all the same settings for an additional three trigger slots.  

Args 1, 2, 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.

Log Args (hidden)

By default, all the arguments that are passed to a script are logged into a text file. For frequently called scripts this can be disabled to make the log files more concise. 

Url Activation

Exec via Url & Url Exec Key

The Exec via Url flag allows scripts to be run from specifically crafted URLs. This allows buttons to be added to Emails or buttons to be constructed in DMR reports and published as web endpoints. For example, a button could be added to a DMR that would allow a BA to unlock a User Self-Schedule booking page with that BA needing an account in MS. 

Args

Optionally args1, args2, and args3 can be added to the Url and will be passed into the script as EventArg1, EventArg2 EventArg3.

e.g. http://......./?args1=red&args2=blue&args3=green

Structure

'<a href="https://{ServerUrl}/{ProjectId}/p/a/script/{InstanceId}/{ScriptId}?ikey={Instance_RandomKey}&skey={Script_UrlExecKey}" target="_blank">Unlock Slot</a>'

E.G. Email Template Link

• Keyword: 
  • [{Module}-UrlButton-Script-{ScriptId}-{Button Text}-{arg1}-{arg2}-{arg3}]
  • [{Module}-Url-Script-{ScriptId}-{Button Text}-{arg1}-{arg2}-{arg3}]
  • e.g. [UM-Url-Script-99-Unlock Slot] will create a url that can be wrapped in a link
  • e.g. [UM-UrlButton-Script-99-Unlock Slot] will create a block of HTML as a button
     
• Raw Url: <a href="https://managementstudio.com/1/p/a/script/[UM-MigrationId]/99?ikey=[UM-RandomKey]&skey=ATKU0VBRKH" target="_blank">Unlock Slot</a>

E.G. DMR Expression Column

<a href="https://managementstudio.com/1/p/a/script/' + UserMigrations_MigrationId + '/999?ikey=' + UserMigrations_RandomKey + '&skey=ATKU0VBRKH" target="_blank">Unlock Slot</a>

Output

<a href="https://managementstudio.com/1/p/a/script/1000/999?ikey=ASDFASD&skey=ATKU0VBRKH" target="_blank">Unlock Slot</a>

Running Scripts

Surveys & Self-Schedule

Surveys & Self-Schedule can run some PowerShell when the User submits the form to perform any additional follow up actions on those users. The admin page for Surveys & Self-Schedules has a PowerShell editor to make using them easier. The PowerShell that is saved there is here in the PowerShell Scripts panel and can be edited also be edited here. 

The initial name of the script will show the name and id of the Surveys / Self-Schedule that created the script.

Calling Scripts in ManagementStudio

Scripts cannot be run from this Panel, registered here and called by something else. The 3 main ways a script can be called are. 

1. Scheduled Task

2. Custom UI Button

3. System Event

Calling Scripts outside ManagementStudio

Script Arguments

Scripts have an object '$ScriptArgs' available to them.  The individual parts of the arguments can be accessed using that object.

e.g. 

• $ScriptArgs.Items
• $ScriptArgs.ScriptArg1
• $ScriptArgs.LogFile

Further Support

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