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.


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

Script Name

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.


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. 


Category (hidden)

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.


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 MigrationStudio 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 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. 


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 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. 



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.


Schedule

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.  


Triggers

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

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.



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 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



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\\MigrationStudio\1\ScriptsIf this PowerShell script is running from a file rather than script text then the path to the file will be here
ReportsFolder\\MigrationStudio\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.log
The full path to the logfile for this script
UtcOffset-3DU timezone offset
StartTime09/06/2021 12:12:28
The time the script was launched
ServerIsWaiting
Not 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