Managing Scripts: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
(306186)
 
(61 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Script Manager ==
In QPR ProcessAnalyzer, scripts can be used for ETL tasks and to automate routines. Scripts are managed in the [[QPR_ProcessAnalyzer_Project_Workspace|Project Workspace]].
Scripts are tied to specific contexts, and the Script Manager dialog lists all the [[Data Extraction, Transformation, and Loading|scripts]] accessible to the user according to the context selections defined by the '''Context''', '''Selected User''', '''Selected Project''', and '''Selected Model''' drop-down menus. The Script Gallery accessible via the Run button on the ribbon will show the scripts for the context that was last selected in the Script Manager.


By default, the following information is displayed for each script:
=== Running vs. Calling Scripts ===
*'''Context Type''': the context to which the script is tied.
''Running'' a script means starting executing a stored script, which can be done in the UI or using the ScriptLauncher. A script can also ''call'' other scripts during the run. The differences between the running and calling are:
*'''Name''': the name of the script.
* Script can run only once at a time, whereas there are no limitations on how many times a script can be called at the same time
*'''Group''': the name of the script group.
* Script log is written to the running script. No script log is written to the called script.
*'''Tags''': the tags added to the script.
* Script status shows whether the script is being run or not. The status does not change, when a script is called from other script.
*'''Created On''': the date and time when the script was created.
*'''Created By''': the user who created the script.
*'''Last Modified On''': the date and time when the script was last modified.
*'''Last Modified By''': the user who last modified the script.
*'''Help''': the URL of the defined help page for the script.


In addition, the following columns are hidden by default:
When a script is running, it's not possible to start another run of the same script, so the first run needs to end to start new. Scripts can call other scripts and a called scripts can run multiple times simultaneously. In the stack of called scripts, the script log is generated to the top level script. Also the top level script shows that it's running and the called scripts do not.
*'''Id''': the id of the script in the database.
*'''Model Id''': the id of the model to which the script is linked.
*'''Model Name''': the name of the model to which the script is linked.
*'''Project Id''': the id of the project to which the script is linked.
*'''Project Name''': the name of the project to which the script is linked.
*'''Script GUID''': the globally unique id of the script.
*'''User Id''': the id of the user to which the script is linked.
To unhide a column:
#Right click a column title and select '''Column Chooser''' from the popup.
#Drag the column to be shown to the desired position.


The same information related to scripts as listed above is shown if you run a script with the --#GetAnalysis command in the [[Script Management|Script Manager]] dialog using Scripts (24) as the analysis type. For more information, see [[Data Extraction, Transformation, and Loading]].
=== Scripts List ===
When selecting a project and opening the '''Scripts''' tab, all scripts in the project can be seen. Scripts list shows following information:
* '''Name''': Name of the script.
* '''Status''': Status of the script, which is one of following: ''Ready'', ''Running'' or ''Stopping''. For more information about script statuses, see below.
* '''Last run duration''': Duration of the last ended run of the script (the last run result can be any).
* '''Last run date''': Date and time when the last run ended. If you need to know the last run start time, subtract the ''Last run duration'' from this time.
* '''Last run result''': Result of the last run of the script. Either of following: ''Completed'', ''Failed'' or ''Aborted''. For more information about last run results, see below.
* '''Id''': Script id that uniquely identifies the script in the system.


=== Viewing or Editing Script Properties ===
Scrips are in either of following statuses:
To view or edit the script properties of a script, select the script from the list and click '''Properties'''
* '''Ready''': Script is currently not running, and can be started.
* '''Running''': Script is currently running, and the script can be stopped. When a script is running, another run of the same script cannot be started.
* '''Stopping''': Script is currently being stopped. When a script is in this status, the script cannot be started nor stopped, so you need to wait for the script to stop. There may be a delay in stopping a script, depending on the operation currently performed by the script.


=== Running a Script ===
The last script run result can be either of the following:
To run a script, select it from the list and click '''Run'''. Alternatively, you can run a script by clicking '''Run''' on the ribbon and selecting the script to be run from the menu that opens.
* '''Completed''': The last run ended successfully, i.e. without any errors or exceptions. Note that despite of the technically successful run, the script might still not work as intended.
* '''Failed''': The last run ended to an error or exception. To see more information about the reason of the failure, see the [[#Viewing_Script_Log|last run log]].
* '''Aborted''': The last run was stopped by a user, so the script did not run till the end.


=== Creating a New Script ===
=== Editing Script ===
To create a new script, click '''New''' and define the [[#Script Properties|Script Properties]].
Open the scripts editor as follows:
# On the left side projects hierarchy, select the project where the script is located.
# Open the '''Scripts''' tab.
# Select the script and in the right-click context menu select '''Edit'''. Alternatively, you can hover the script and click the ''Edit'' button in the end of the row.


=== Copying Scripts to Another Context ===
The script editor can show multiple scripts in the tabs, allowing to easily switch between the scrips. The editor remembers all scripts that have been opened during the session.
#Select the script(s) you want to copy from the list by left-clicking a script. To select multiple scripts hold down either the Shift key or the Ctrl key.
#Click '''Copy to Clipboard'''.
#From the Context and the Selected User/Selected Project/Selected Model drop-down menus, select the context to which you want to copy the script(s).
#Click '''Create from Clipboard'''.
Note that there cannot be duplicated global ID's (= the identifier in the '''Script GUID''' field) in the same context. If there are multiple scripts with the same global ID, you will receive an error message and the script is not copied.


=== Deleting Scripts ===
In the script editor, you can:
To delete script(s), select them from the list and click '''Delete'''.
* Run the script by clicking the '''Run''' button.
* Stop a running script by clicking the '''Stop''' button.
* Save a script having unsaved changes by clicking the '''Save''' button.
* To run a script having unsaved changes, click the '''Save and Run''' button. Note that the script needs to be saved to run it.
* To go back to the list of scripts, click the '''Go back''' button. If there are unsaved changes in any of the opened scripts, you need to either save or cancel the changes.
* To close a script, click the ''Close'' button for the tab showing the script. If there are unsaved changes, you need to either save or cancel changes.


== Script Properties ==
=== Starting Script ===
The Script Properties dialog is used to view and edit the script properties:
# On the left side projects hierarchy, select the project where the script is located.
*'''Name''': the name of the script.
# Open the '''Scripts''' tab.
*'''Script GUID''': the globally unique id of the script.
# Select the script and in the right-click context menu select '''Run'''. Alternatively, you can hover the script and click the ''Run'' button in the end of the row.
*'''Support Link''': the URL of the help page for the script.
*'''Group''': the name of the script group.
*'''Tags''': the tags added to the script.
*'''Description''': the description of the script.
*'''Script Code''': the actual [[Data Extraction, Transformation, and Loading|script]] that is to be run.
*'''Show in Script Gallery''': when this is selected, the script will be shown in the menu that opens by clicking the Run button in the ribbon.
*'''Hide Script Details''': when this is selected, only users who have the right to modify the script can see the script details, when unselected, all users who have view permissions can see the script details.


=== Saving or Discarding Changes ===
Note that when running a script in the UI, the script must not contain commands where ''ExecuteInClientSide'' is enabled, because that is only supported when running scripts using [[QPR_ProcessAnalyzer_ScriptLauncher|QPR ScriptLauncher]].
*After making changes to the script properties, click '''Save''' to save the changes. You can also press '''Ctrl + S''' to save the changes.
*To discard changes done since the script was last saved, click '''Cancel Edit'''.


=== Running a Script ===
=== Stopping Script ===
Click '''Run''' to run the script. Alternatively, you select it from the list on the Script Manager dialog and click '''Run''', or you can clic '''Run''' on the ribbon and select the script to be run from the menu that opens.
# On the left side projects hierarchy, select the project where the script is located.
# Open the '''Scripts''' tab.
# Select the script and from the right-click context menu select '''Stop'''. Alternatively, you can hover the script and click the ''Stop'' button in the end of the row.
 
Note that it may take a while for a script to actually stop, depending on what kind of operation the script is executing when it's stopped.
 
=== Viewing Script Log ===
It's possible to see the script log of the last run, and monitor the currently running script progress. Logs for older runs are not available in the UI, nut they are stored by the system.
 
To see the logs:
# On the left side projects hierarchy, select the project where the script is located.
# Open the '''Scripts''' tab.
# Select the script and in the right-click context menu select either '''View last run log''' or '''View current run log'''. (The script needs to be running to open the current run log.)
# If keeping the current run log open, the latest log entries are updated automatically every two seconds.
 
More information about [[QPR_ProcessAnalyzer_Logs#Script_Log|Script Log]].
 
=== Creating Script ===
# On the left side projects hierarchy, select the project where you want to create a script.
# Open the '''Scripts''' tab.
# Click the '''New''' button and click '''Script'''. Define a name for the script and the scripting '''Language''' (either '''Expression''' or '''SQL'''), and then click '''Create'''. Note that script names must be unique within a project.
 
Note that the scripting language cannot be changed after the script has been created, so a new script needs to be created to change the language.
 
=== Deleting Script ===
# Select the project where the script(s) to be deleted are located.
# Open the '''Scripts''' tab.
# Select one or several scripts to be deleted.
# Click the '''Delete''' button and click '''Delete''' to the confirmation message.
 
Note that if the script is being run, it cannot be deleted.
 
=== Renaming Script ===
# Select the project where the script to be renamed is located.
# Open the '''Scripts''' tab.
# Select the script to be renamed.
# Click the '''Rename''' button.
# Change the script name in the opening dialog and click '''OK'''.
 
=== Moving Script ===
Scripts can be moved by dragging them with the left mouse button from the right side list to the target project in the left side hierarchy. Alternatively, you can first select the scripts, then from the right-click context menu select '''Move to''' and finally select the target project.
 
=== Duplicating Script ===
# Select the project where the script to be duplicated is located.
# Open the '''Scripts''' tab.
# Select the script to be duplicated.
# Click the '''Duplicate''' button. A duplicate of the script is created.
 
=== Viewing Script Run Results ===
Script runs can be [[Managing_Scripts#Running_Script|started]] and [[Managing_Scripts#Stopping_Script|stopped]] in the UI. Note that when running scripts using the UI, return values or results of the script cannot be viewed. If you want to use scripts that return data, there are following options:
* Script can write data to the script log
* Script can write data to a datatable
* Script can be called from a dashboard and use the dashboard to present the returned data (see more below).

Latest revision as of 15:12, 28 March 2024

In QPR ProcessAnalyzer, scripts can be used for ETL tasks and to automate routines. Scripts are managed in the Project Workspace.

Running vs. Calling Scripts

Running a script means starting executing a stored script, which can be done in the UI or using the ScriptLauncher. A script can also call other scripts during the run. The differences between the running and calling are:

  • Script can run only once at a time, whereas there are no limitations on how many times a script can be called at the same time
  • Script log is written to the running script. No script log is written to the called script.
  • Script status shows whether the script is being run or not. The status does not change, when a script is called from other script.

When a script is running, it's not possible to start another run of the same script, so the first run needs to end to start new. Scripts can call other scripts and a called scripts can run multiple times simultaneously. In the stack of called scripts, the script log is generated to the top level script. Also the top level script shows that it's running and the called scripts do not.

Scripts List

When selecting a project and opening the Scripts tab, all scripts in the project can be seen. Scripts list shows following information:

  • Name: Name of the script.
  • Status: Status of the script, which is one of following: Ready, Running or Stopping. For more information about script statuses, see below.
  • Last run duration: Duration of the last ended run of the script (the last run result can be any).
  • Last run date: Date and time when the last run ended. If you need to know the last run start time, subtract the Last run duration from this time.
  • Last run result: Result of the last run of the script. Either of following: Completed, Failed or Aborted. For more information about last run results, see below.
  • Id: Script id that uniquely identifies the script in the system.

Scrips are in either of following statuses:

  • Ready: Script is currently not running, and can be started.
  • Running: Script is currently running, and the script can be stopped. When a script is running, another run of the same script cannot be started.
  • Stopping: Script is currently being stopped. When a script is in this status, the script cannot be started nor stopped, so you need to wait for the script to stop. There may be a delay in stopping a script, depending on the operation currently performed by the script.

The last script run result can be either of the following:

  • Completed: The last run ended successfully, i.e. without any errors or exceptions. Note that despite of the technically successful run, the script might still not work as intended.
  • Failed: The last run ended to an error or exception. To see more information about the reason of the failure, see the last run log.
  • Aborted: The last run was stopped by a user, so the script did not run till the end.

Editing Script

Open the scripts editor as follows:

  1. On the left side projects hierarchy, select the project where the script is located.
  2. Open the Scripts tab.
  3. Select the script and in the right-click context menu select Edit. Alternatively, you can hover the script and click the Edit button in the end of the row.

The script editor can show multiple scripts in the tabs, allowing to easily switch between the scrips. The editor remembers all scripts that have been opened during the session.

In the script editor, you can:

  • Run the script by clicking the Run button.
  • Stop a running script by clicking the Stop button.
  • Save a script having unsaved changes by clicking the Save button.
  • To run a script having unsaved changes, click the Save and Run button. Note that the script needs to be saved to run it.
  • To go back to the list of scripts, click the Go back button. If there are unsaved changes in any of the opened scripts, you need to either save or cancel the changes.
  • To close a script, click the Close button for the tab showing the script. If there are unsaved changes, you need to either save or cancel changes.

Starting Script

  1. On the left side projects hierarchy, select the project where the script is located.
  2. Open the Scripts tab.
  3. Select the script and in the right-click context menu select Run. Alternatively, you can hover the script and click the Run button in the end of the row.

Note that when running a script in the UI, the script must not contain commands where ExecuteInClientSide is enabled, because that is only supported when running scripts using QPR ScriptLauncher.

Stopping Script

  1. On the left side projects hierarchy, select the project where the script is located.
  2. Open the Scripts tab.
  3. Select the script and from the right-click context menu select Stop. Alternatively, you can hover the script and click the Stop button in the end of the row.

Note that it may take a while for a script to actually stop, depending on what kind of operation the script is executing when it's stopped.

Viewing Script Log

It's possible to see the script log of the last run, and monitor the currently running script progress. Logs for older runs are not available in the UI, nut they are stored by the system.

To see the logs:

  1. On the left side projects hierarchy, select the project where the script is located.
  2. Open the Scripts tab.
  3. Select the script and in the right-click context menu select either View last run log or View current run log. (The script needs to be running to open the current run log.)
  4. If keeping the current run log open, the latest log entries are updated automatically every two seconds.

More information about Script Log.

Creating Script

  1. On the left side projects hierarchy, select the project where you want to create a script.
  2. Open the Scripts tab.
  3. Click the New button and click Script. Define a name for the script and the scripting Language (either Expression or SQL), and then click Create. Note that script names must be unique within a project.

Note that the scripting language cannot be changed after the script has been created, so a new script needs to be created to change the language.

Deleting Script

  1. Select the project where the script(s) to be deleted are located.
  2. Open the Scripts tab.
  3. Select one or several scripts to be deleted.
  4. Click the Delete button and click Delete to the confirmation message.

Note that if the script is being run, it cannot be deleted.

Renaming Script

  1. Select the project where the script to be renamed is located.
  2. Open the Scripts tab.
  3. Select the script to be renamed.
  4. Click the Rename button.
  5. Change the script name in the opening dialog and click OK.

Moving Script

Scripts can be moved by dragging them with the left mouse button from the right side list to the target project in the left side hierarchy. Alternatively, you can first select the scripts, then from the right-click context menu select Move to and finally select the target project.

Duplicating Script

  1. Select the project where the script to be duplicated is located.
  2. Open the Scripts tab.
  3. Select the script to be duplicated.
  4. Click the Duplicate button. A duplicate of the script is created.

Viewing Script Run Results

Script runs can be started and stopped in the UI. Note that when running scripts using the UI, return values or results of the script cannot be viewed. If you want to use scripts that return data, there are following options:

  • Script can write data to the script log
  • Script can write data to a datatable
  • Script can be called from a dashboard and use the dashboard to present the returned data (see more below).
Retrieved from "https://wiki.onqpr.com/pa/index.php?title=Managing_Scripts&oldid=24504"