Building Script-based Report¶
Custom reports are typically built with Model Query Language (MQL), which provides a structured mechanism for querying and manipulating loaded models. There are certainly cases where users want to build special reports that MQL may not be adequate to handle. To support these special use cases, the Tool provides Python scripting support to enable users to create the sophisticated report through scripting. More specifically, the Tool enables users to plug-in scripting functions and plug them in the defined custom report definitions.
In this article, we will use the examples to show users how Python scripting support can be leveraged to build custom reports through scripting.
Hands-on¶
- Load the “Test CIM 14” sample model that comes with the Tool from the data source dropdown list, as illustrated.
- Call a custom report, titled ‘Power Plants (Python)’ via the context menu associated with the loaded model, i.e. Display→Network→Power Plants (Python), as illustrated.
- The Python script generated report shall be displayed, as shown below.
Code Analysis¶
The defined sample custom report, which can be found at \CIMSpy\config\view\Network.xml, has an script-generated custom report, as highlighted below.
Note:
- The module file path doesn’t need to be specified if the module file is under the default scripting folder according to convention. Otherwise the full file path must be specified, for example:
customFunc``=``"Report::..\scripting\Report::GetPowerPlants" - The plugin attribute must be set to ‘true’ for all of the script-generated reports.
The script function used to generate the above custom report is defined at \CIMSpy\scripting\Report.py, and the code is described below.
How Does It Work?¶
When the report generation engine executes the plug-in report generation function, it will prepare a CustomReportFuncCallContext object and pass the information to the triggered script function. The passed information includes a reference to the FullModel and a temporary View object. The custom script function will then be executed to populate the Objects and store them in the View object, which will be carried over to the report generation engine for presentation to users. The exposed APIs of the CustomReportFuncCallContext object are summarized below:
Class¶
CustomReportFuncCallContext¶
Description
Class CustomReportFuncCallContext defines a context object used to exchange information between report generation engine and custom report generation function scripted in Python.
Function¶
Details¶
Description
GetParameters
Syntax
GetParameters()
The function returns a sequence of user-defined parameters.
Returns
StringVector
The returned string vector includes all of the user-defined function parameters in the exactly same sequence.
Parameters
none
AddMessage
Syntax
AddMessage(msg)
The function stores a new message, which will be prompted to users in the UI in the same sequence as it is stored.
Returns
none
Parameters
msg: string
String message to be presented to users
GetView
Syntax
GetView()
The function returns a reference to the View object, which encapsulates a custom report dynamically generated.
Returns
View
View is a dynamically-generated object used to contain the information presented in the custom report
Parameters
none
GetFullModel
Syntax
GetFullModel()
The function returns a reference to the FullModel object from which a custom report will be built.
Returns
FullModel
A reference to the FullModel object from which a custom report will be built.
Parameters
none
Extended MQL-based Custom Reporting¶
Special custom reports can also be generated through extension of MQL through scripting.
Debugging & Logging¶
It is important to note that if there are syntax or run-time errors detected when running the script-generated reporting functionality, the error messages are not displayed to the users in the UI. This is because report generation is executed in a muted mode. The error messages are typically overwhelming for displaying in the UI.
Users can enable the error/message logging by setting attribute loggingEnabled to ‘true’ in the ScriptingConfig element of the CustomConfig.xml, as shown below. When this flag is set to ‘true’, the errors encountered and script-generated messages will be saved in a log file specified by attribute loggingFile. Attribute maxDisplayedMsgs specifies the max number of errors/messages. If attribute maxDisplayedMsgs is 0 (default), all of the errors/messages will be displayed in the server prompt session and logged in the log file. Otherwise, only the first maxDisplayedMsgs will be displayed and logged. For example, only the first 10 errors will be displayed and logged (if enabled) according to the following configuration. Note: the errors/messages will be logged in appending mode until the server is shut down. Then a new logging session will started, overwriting the previous logged messages.
