Scripting for Model Transformation¶
The model transformation process is guided by the transformation profile based on Model Query Language (MQL). In many exceptional cases, the model transformation engine relies on are built-in helper functions to deal with special model conversion cases. There are certainly cases where users want to program their own helper functions to deal with special cases where the built-in functions may not be able to handle. To support these special use cases, the Tool provides Python scripting support to enable users to create the sophisticated helper through scripting. More specifically, the Tool enables users to plug-in scripting functions and plug them in the transformation profile at both class mapping and property mapping levels.
In this article, we will use an example to show users how Python scripting support can be leveraged to build custom reports through scripting.
Hands-on¶
- Change the sample transformation profile located \CIMSpy\config\transformation\ CIM14ToCIM16.xml, by disabling the existing property mapping and enabling a script-based mapping, as illustrated below.
- Load the “Test CIM 14” sample model that comes with the Tool from the data source dropdown list, as illustrated.
- Invoke a model transformation process via the context menu associated with the loaded model. Select CIM14 to CIM16 from the popup dropdown list
- A new model, based on CIM 16, shall be loaded. It is converted from the loaded test model. Check the converted model to verify that attribute Breaker.ratedCurrent has been renamed as Switch.ratedCurrent. The change of property name is accomplished via script-based helper function.
- Restore the original transmission profile.
Code Analysis¶
The example above has demonstrated how a script-based property mapping helper function can be embedded in the transformation profile.
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: helper``=``"MTFExtension::..\scripting\ MTFExtension::RenameProperty”.
The script function used to generate the above custom report is defined at \CIMSpy\scripting\MTFExtension.py, and the code is described below.
How Does It Work?¶
When the model transformation engine executes the plug-in helper function, it will prepare a helper context object and pass the information to the triggered script function. The passed information includes all of the information declared at the class/property mapping level. The custom script function will then be executed to perform the special model transformation steps, typically impacting the target model/object. Like the built-in helper functions, the script-based custom helper functions can be plugged at both class mapping and property mapping levels. The corresponding context object APIs are summarized below:
Class
MTFClassHelperContext¶
Description
Class MTFClassHelperContext defines a context object used to exchange information between the model transformation engine and the custom class mapping helper 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
GetSourceModel
Syntax
GetSourceModel ()
Called to return a reference to the FullModel object which serves as the source model in the model transformation process.
Returns
FullModel
A reference to the FullModel object which serves as the source model in the model transformation process.
Parameters
none
GetTargetModel
Syntax
GetTargetModel()
Called to return a reference to the FullModel object which serves as the target model in the model transformation process.
Returns
FullModel
A reference to the FullModel object which serves as the target model in the model transformation process.
Parameters
none
SourceClassName
Syntax
SourceClassName ()
Called to return the full name of the class which serves as the source class in the model transformation process.
Returns
str
The full name of the class which serves as the source class in the model transformation process. The namespace prefix is included.
Parameters
none
TargetClassName
Syntax
TargetClassName()
Called to return the full name of the class which serves as the target class in the model transformation process.
Returns
Parameters
none
Skip
Syntax
Skip(className, propName)
The function is only used for by-exception model transformation. It tells the model transformation engine not to copy the specified class/property from the source model to target model during the post-exception transformation process.
Returns
none
Parameters
className: str
Full name of the class, including namespace prefix.
propName: str
Full name of the property, including namespace prefix. If empty, the whole class will be skipped.
Class
MTFPropertyHelperContext¶
Description
Class MTFPropertyHelperContext defines a context object used to exchange information between the model transformation engine and the custom property mapping helper 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
GetSourceModel
Syntax
GetSourceModel ()
Called to return a reference to the FullModel object which serves as the source model in the model transformation process.
Returns
FullModel
A reference to the FullModel object which serves as the source model in the model transformation process.
Parameters
none
GetTargetModel
Syntax
GetTargetModel()
Called to return a reference to the FullModel object which serves as the target model in the model transformation process.
Returns
FullModel
A reference to the FullModel object which serves as the target model in the model transformation process.
Parameters
none
SourceClassName
Syntax
SourceClassName ()
Called to return the full name of the class which serves as the source class in the model transformation process.
Returns
str
The full name of the class which serves as the source class in the model transformation process. The namespace prefix is included.
Parameters
none
TargetClassName
Syntax
TargetClassName()
Called to return the full name of the class which serves as the target class in the model transformation process.
Returns
str
The full name of the class which serves as the source class in the model transformation process. The namespace prefix is included.
Parameters
none
GetSourceObject
Syntax
GetSourceObejct ()
Called to return a reference to the Object which serves as the source object in the model transformation process.
Returns
Object
A reference to the Object which serves as the source object in the model transformation process
Parameters
none
GetTargetObject
Syntax
GetTargetModel()
Called to return a reference to the Object which serves as the target object in the model transformation process.
Returns
Object
A reference to the Object which serves as the target object in the model transformation process
Parameters
none
SourcePropertyName
Syntax
SourcePropertyName ()
Called to return the full name of the property which serves as the source property in the model transformation process.
Returns
str
The full name of the property which serves as the source property in the model transformation process. The namespace prefix is included.
Parameters
none
TargetPropertyName
Syntax
TargetPropertyName()
Called to return the full name of the property which serves as the source property in the model transformation process.
Returns
str
The full name of the property which serves as the target property in the model transformation process. The namespace prefix is included.
Parameters
none
PropertyType
Syntax
PropertyType ()
Called to return the type of the property
Returns
PropertyType (enum)
Type of the property, i.e. attribute/association/enumeration
Parameters
none
Skip
Syntax
Skip(className, propName)
The function is only used for by-exception model transformation. It tells the model transformation engine not to copy the specified class/property from the source model to target model during the post-exception transformation process.
Returns
none
Parameters
className: str
Full name of the class, including namespace prefix.
propName: str
Full name of the property, including namespace prefix. If empty, the whole class will be skipped.
Extended MQL-based Model Transformation¶
Model transformation can also be customized by extending MQL through scripting.
Debugging & Logging¶
It is important to note that if there are syntax or run-time errors detected when running the script-based model transformation, the error messages are not displayed to the users in the UI. This is because model transformation 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.
