|
Tip: There are sample templates for plug-in usage, delivered along with the RayQC application resources. As soon as RayQC is installed, samples are stored within the RayQC program folder (e. g. C:\Program Files (x86)\RayQC\Samples\Sample Checklist.rqct, which is designed to present some functions of the RayQC plug-ins, along with their configuration options). |
How to Trigger Plug-in Execution
Once a plug-in has been integrated into the checklist template file, it may be run from the Checklist Viewer interface.
|
Be aware: Even though it is technically not required, it is highly recommended to save the current checklist definition before a test run is executed. Especially the integration and execution of external plug-ins may lead to severe system interferences. Please keep in mind, that RayQC does not prevent critical script logic to be run as part of external plug-ins. It is the plug-in and checklist authors area of responsibility to make sure no harm is caused by their functions on the affected systems. |
The representative box for a checklist element contains an arrow icon to indicate plug-in existence. As soon as the evaluating user clicks this button, the plug-in logic is executed according to the settings defined within the checklist, the plug-in script logic, and the current state of the target system, or respectively any other object of investigation within plug-in reach.
The screenshot below displays some element boxes taken from the plug-ins checklist template sample. The trigger icons for plug-in execution are shown within checkpoint, user comment, and comment element boxes. However, it is also possible to integrate plug-in execution into the interface of multi-option items.
In order to provide correct and reliable execution results, users should evaluate the whole sequence of checklist items until the one with the plug-in is reached. It is very common that plug-ins require results of prior elements as input parameters. The plug-in execution would fail if there were missing element results which are actually used by the current plug-in configuration. Therefore, it is recommended to run through the whole checklist evaluation course to make sure the parameter call is triggered from a realistic checklist status.
The actual result of plug-in execution depends on the plug-in selected, the function called, the parameters used, and - of course - the status of the target system that is checked or manipulated by the plug-in logic. Let us take a look at the Command plug-in example shown below. The Data Field element (1) available from the sample checklist group "I: Valid path values" is about to call the Registry Editor (regedit.exe) of the local machine. With a click on the plug-in trigger button, the configured command line is fired. The file name and full path to the executable was provided and regedit is started successfully. But how about the other examples? Will they plug-in execution for element 2 launch the Registry Editor as well?
Yes, it does launch the Registry Editor - but only on those machines, who have C:\Windows\ added to the PATH environment variable. RayQC reads these variables during executable path resolution.
The same notation would also work for notepad.exe or explorer.exe as long as the underlying Windows operating system is not highly customized regarding its system settings and default parameters. Addressing applications in non-standard local or network locations requires to give the fully qualified path (e. g., C:\Program Files (x86)\RayPack\RayPack.exe to launch RayPack). The executable whose execution is triggered by element no 3 resides within the RayQC program directory (typically something like C:\Program Files (x86)\RayQC\), which is by default checked for a matching file as well. All other plug-in parameters that represent paths have to be given fully qualified, the Command plug-in is the only exception on this rule.
Run Single Plug-in vs. Run All Plug-ins
As outlined before, it is possible to trigger a single plug-in execution with a click on the rightwards pointing arrow icon which is available directly from the elements box representation. However, there may be automated checklists, which fully consist of stacked plug-in-based checks. If these checklists are opened for evaluation, it is faster and more convenient to use the Run All button from the Swipe Bar below the checklist area.
The sequence of plug-in execution is initially determined at the beginning. When the first currently available checklist item with an integrated plug-in is reached and executed, the results are written to the checklist project residing within the session memory. At this point, the group and item sequence is recalculated in order to be able to consider result-driven changes to the availability of upcoming checklist objects (please refer to the conditions section for details).
This procedure of
a)plug-in run
b)sequence recalculation according to plug-in run results
c)proceeding to the next plug-in according to the newly calculated sequence
is repeated until all checks have been run according to the requirements defined by the checklist template and the actual execution results.
|
Be aware: If a plug-in does not run fully automated, but requires user interaction (e. g. when a browser dialog invocation is triggered), the next plug-in execution will not be launched until the execution of the last one has finished (e. g. a file has been selected from a system browser dialog, or a registry value has been read). However, it does not matter if the plug-in execution was successful or not, as soon as the triggered function has terminated, RayQC proceeds to the next checklist plug-in call. |
Typical Plug-in Execution Issues
In our example above, the plug-in execution ran flawlessly. Unfortunately, there may be less lucky circumstances that raise issues on plug-in execution.
For example, when a plug-in logic requires additional resources that are not available, because executing user does not have sufficient access rights to the affected system parts, a path information is invalid, or the like. If an external plug-in script is triggered from a checklist, but this plug-in is not present in a known and reachable location, a Windows Script Host Error message is shown, outlining the reasons for the invalidity of the plug-in script invocation. There are some troubleshooting hints given later in this document, which may be of help in such a situation. However, the following screenshot displays a typical RayQC message, caused by an invalid command name argument (e. g., according to our sample checklist: regedit.dll instead of regedit.exe in element no 2.)
If a plug-in has not been configured correctly, there may be issues with parameter settings that are incorrect towards format restrictions, or with missing parameter information that is mandatory for plug-in execution. In this cases, RayQC usually displays an error message, describing the parameter that actually raised the issue, along with some helping notes on how to solve it.
|
Note: If the plug-in execution does not run as expected, adjust the configuration, use the troubleshooting advice provided within this document, contact your local RayQC system administrator, or send a support request to Raynet: https://raynetgmbh.zendesk.com. Please keep in mind that our support team cannot assist on the elimination of issues caused by external plug-in logic that you implemented on your own. If there are further requirements for Raynet specialist back up regarding external plug-ins, there are additional trainings or consultant services Raynet is always pleased to offer. |
Multiple Plug-in Execution
Whenever a checklist evaluation has been started by giving element results and / or running plug-ins, RayQC stores the current item availability and result state within the session memory. Due to conditional statements, changing a single item result may significantly change the availability of checklist items and groups. Combining the idea of plug-in execution results which may be injected as results into element results, and conditions that depend on element results, it becomes clear that rerunning a plug-in may lead to differing results (especially during the checklist preparation phase when the configuration settings or system preconditions usually change between the plug-in executions).
In order to make sure that users are aware of rerunning a plug-in, RayQC displays an info dialog, asking for a confirmation of the follow-up triggering. Please make sure that overwriting existing data is really the intended action. To be absolutely sure about the correct checklist flow results, it is recommended not to rerun a single plug-in, but to reset the whole checklist and start again from the beginning. Especially results generated from highly complex conditional statements may turn out to be confusing when only parts of a checklist are rerun, or retriggered in case of plug-ins.