PowerShell Scripts

Modified on Mon, 11 Mar at 11:54 AM

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



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


ArgumentDataNote
ScriptNameScriptName.PS1Name defined in PowerShell Script Panel
SourceTypeEventTriggerHow the script was called, UI Button, Scheduled Task, Event, etc.
SourceNameUpdatedMore info on the source. e.g. Updated, Created, etc.
SourceId55More info on the source e.g. ButtonId
RanByUserAdmin Account [Admin]The account that called the script. This will be the User that clicked a UI button, caused an event to fire, etc.
RanAsUserAPI Account [ApiAccount]Any changes will be attributed to this account and the script is subject to this account's permissions. 
ProjectId1Id of Project that called the script
ModuleApplicationsThe module of the script set in the PowerShell Panel
Items1000, 1001,1002The list of Id's or objects to run the script on. e.g. Selected Ids on the Grid. Id's of affected items for an event. 
AltItems2000, 3000, 54542
"Related object ID,  i.e DU BP or Task"

So an event that triggers when a user is added to a DU and runs a PS Script. Items would hold UsersIds and AltItems would contain the DU ID.

ScriptId1Script If from PowerShell Panel
ScriptArg1, 2, 3Option1Optional args specified in the PowerShell Panel. Allows the same script to perform multiple roles 
EventArg1, 2
Additional arguments system events can supply. e.g. Added to Blueprint provides the Blueprint Id in EventArg1
UserInput
For a UI Button that asks a User a question, the answer will be held here 
CallerInput2ESM Plan Number that called the script. Required to call back to ESM to recover script variables.
ScriptFolder\\ManagementStudio\1\ScriptsIf this PowerShell script is running from a file rather than script text then the path to the file will be here
ReportsFolder\\ManagementStudio\1\ReportsThe path to the Reports folder for this Project
AutomationFolder
The path to the Api Module Folder
LogsFolder\\MigrationStudio\1\LogsThe path to the log files folder for this Project
LogFile\\MigrationStudio\1\Logs\ScriptName.logThe full path to the logfile for this script
UtcOffset-3DU timezone offset
StartTime09/06/2021 12:12:28The time the script was launched
ServerIsWaitingNot Yet ImplementedNot Yet Implemented
ApiUrlhttp://MigrationStudio.domain.localThe Url of the Api endpoint for this Project
ApiModulec\wwwroot\Automation\MigrationStudioApiThe full path to the MS PowerShell Api Module
ApiTokeneyJhbGciOiJIUzI1NiIsIn....A token that can be used to access the Api 



Further Support

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