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 MigrationStudio will automatically keep a history of any changes made to the script.
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.
The name of the script will that 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.
Control if the script can be executed without having to unlink it from UI Buttons or Scheduled Tasks
An optional description of what the script does. This is only for UI info and is not used anywhere else.
An optional category to help group similar scripts together in the UI. It is not used anywhere else.
Edit Button & Script Text
The script text field is a shot preview snippet of the full PowerShell script. The Edit button pops open a new window allow editing of the full PowerShell Script. Changes to the script are automatically tracked by MigrationStudio. This will be run unless a Script Path is specified in the next column - see below.
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 MigrationStudio looks for the script in three locations.
- The explicit path.
e.g. If the path is 'c:\scripts\myScript.ps1' MS will look for the script in that location.
- Project Scripts folder.
e.g. If the path is 'path\myScript.ps1' then the '[StorageFolder]\path\Scripts' folder will be checked
- Automation Scripts folder.
e.g. If the path is 'myScript.ps1' then the 'wwwroot\Automation\Scripts' folder will be checked
Scripts should target a specific module in MigrationStudio, 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.
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 more change 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 MigrationStudio is in this role.
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.
Schedule 1, 2, 3 ( 2, 3 hidden)
Scripts can be called subscribe 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'.
Note: If a script needs to run at more times than 3 different S-Tasks can describe; then copy the PS Script to a new line on the grid with all the same settings for an additional three schedule slots.
Trigger 1, 2, 3 ( 2, 3 hidden)
Scripts can be called automatically when specific events trigger in MigrationStudio. 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 MigrationStudio 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.
Surveys & Self-Schedule
Calling Scripts in MigrationStudio
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 MigrationStudio
Scripts have an object '$ScriptArgs' available to them. The individual parts of the arguments can be accessed using that object.
|ScriptName||ScriptName.PS1||Name defined in PowerShell Script Panel|
|SourceType||EventTrigger||How the script was called, UI Button, Scheduled Task, Event, etc.|
|SourceName||Updated||More info on the source. e.g. Updated, Created, etc.|
|SourceId||55||More info on the source e.g. ButtonId|
|RanByUser||Admin Account [Admin]||The account that called the script. This will be the User that clicked a UI button, caused an event to fire, etc.|
|RanAsUser||API Account [ApiAccount]||Any changes will be attributed to this account and the script is subject to this account's permissions.|
|ProjectId||1||Id of Project that called the script|
|Module||Applications||The module of the script set in the PowerShell Panel|
|Items||1000, 1001,1002||The 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.|
|AltItems||2000, 3000, 54542|
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.
|ScriptId||1||Script If from PowerShell Panel|
|ScriptArg1, 2, 3||Option1||Optional 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|
|CallerInput||2||ESM Plan Number that called the script. Required to call back to ESM to recover script variables.|
|ScriptFolder||\\MigrationStudio\1\Scripts||If this PowerShell script is running from a file rather than script text then the path to the file will be here|
|ReportsFolder||\\MigrationStudio\1\Reports||The path to the Reports folder for this Project|
|AutomationFolder||The path to the Api Module Folder|
|LogsFolder||\\MigrationStudio\1\Logs||The path to the log files folder for this Project|
|LogFile||\\MigrationStudio\1\Logs\ScriptName.log||The full path to the logfile for this script|
|UtcOffset||-3||DU timezone offset|
|StartTime||09/06/2021 12:12:28||The time the script was launched|
|ServerIsWaiting||Not Yet Implemented||Not Yet Implemented|
|ApiUrl||http://MigrationStudio.domain.local||The Url of the Api endpoint for this Project|
|ApiModule||c\wwwroot\Automation\MigrationStudioApi||The full path to the MS PowerShell Api Module|
|ApiToken||eyJhbGciOiJIUzI1NiIsIn....||A token that can be used to access the Api|