About the ModelStateDescriptor.txt file
The ModelStateDescriptor.txt file
Package states provide a systematic approach for tracking the maturity and developmental state of a package. These states are configurable and are defined in the ModelStateDescriptor.txt file, which can be located in one of the following folders:
 |
The location of the ModelStateDescriptor.txt file determines which model, version or database it affects.
|
• In the individual model version folder
Example: %PROGRAMDATA%\PTC Integrity Modeler\ModelerATFiles\Examples\59cbb5bb-76b5-4d55-bdf4-d99dd826eaa6\2\ModelStateDescriptor.txt
Affects only the particular version of the model.
• In the individual model folder
Example: %PROGRAMDATA%\PTC Integrity Modeler\ModelerATFiles\Examples\00a486ec-e0e6-4198-869b-db89bf6c239e\ModelStateDescriptor.txt
Affects the particular model and all its versions.
• In the database folder
Example: %PROGRAMDATA%\PTC Integrity Modeler\ModelerATFiles\Examples\ModelStateDescriptor.txt
Affects all the models and their versions in the specified database.
• In the global ATFiles folder
Example: %PROGRAMDATA%\PTC Integrity Modeler\ModelerATFiles\ModelStateDescriptor.txt
Affects all the databases, models and their versions located within the ATFiles folder.
Click
here to view an example of the ModelStateDescriptor.txt file. You can use this ModelStateDescriptor.txt file as a template to create your own states for your models.
The ModelStateDescriptor.txt provides the lifecycle workflow capabilities for a package. Additionally, you can also configure the following capabilities for various states of a package:
• As mentioned above, you can define a set of states that define the workflow lifecycle for your packages.
• Each state can have a unique ID and a name.
• For each state, you must set the MakeProtected property. This property is mandatory and should be specified to protect or unprotect the package immediately upon entering the new state.
• With the CanEditVersion property, you can define whether the package can be editable or not upon change of state. The package version property can be editable only when the package is in the CanEditVersion state.
• For each state, you can set the Disabled property to inform the user that the state is obsolete in the lifecycle and cannot be entered into (however, it is possible to exit from such a state).
• You can assign an icon for every defined state. When the icon is assigned, the icon full filename should be specified in a shared directory, such as the ATFiles directory, so that all the machines where Modeler is installed can access the icons from the common location.
• For every state, you can define the TransitionTo property to set the allowed transition states for the current package state.
• For every state, you can define an entry script. Entry scripts are triggered on two occasions (both these instances are triggered immediately after changing state):
◦ Upon clicking the Validate (Global) button: This instance triggers the ValidateState script. You can trigger this script to verify the state transition, customizing the message that is displayed in the Issues section of the dialog upon state change.
The following is an example of the ValidateState script:
Function ValidateState
If ThePackage("Name") = "DontChangeMyState" Then
Script.Result = "Cannot change state from " + OldState + "to " + NewState
ValidateState = False
Else
Script.Result = ""
ValidateState = True
End If
End Function
If ThePackage("Name") = "DontChangeMyState" Then
Script.Result = "Cannot change state from " + OldState + "to " + NewState
ValidateState = False
Else
Script.Result = ""
ValidateState = True
End If
End Function
The ValidateState function uses the following variables:
▪ ThePackage (Object) — This is the target Package (or Model) for which the state change operation is attempted.
▪ OldState (String) — The ID of the current state of the target Package (or Model).
▪ NewState (String) — The ID of the new state of the package (or Model) that you are transitioning to.
The above function returns a value of True or False after a full validation of the model. You can write a valid reason for denial message in to the Script.Result variable. If the ValidateState returns False or specifies a non-empty reason for deny message, then the validation fails and the transition to the new State is denied.
◦ Upon clicking the OK button. This instance triggers the CommitState script. You can trigger this script to perform tasks such as changing the Version of the model immediately upon state change, setting other properties to prepare for review or to release the package contents.
|
|
Use this function to make updates to the model. This function is run as a transaction, so any changes made by the script are immediately visible in Modeler, and the changes can be undone. Also, do not use the CommitState function to interact with users as items in the model will be locked and unavailable to other users while the user interaction takes place.
|
The following is an example of the CommitState script:
Function CommitState
If ThePackage("Name") = "ChangeMyVersion" Then
'Change object version
Dim V
V = ThePackage("Package Version")
If V = "" Then
V = Cstr(1)
Else
V = Cstr(Cint(V) + 1)
End If
ThePackage("Package Version") = V
End If
CommitState = True
End Function
This function is triggered during Commit and after the new state and the history has been updated on the target object. The function is triggered while the object is not “Protected”. The CommitState function uses the following variables:
▪ ThePackage (object) — The target Package (or Model) for which the state change operation is attempted.
▪ OldState (string) — The ID of the old state of the target Package (Model). Note that the script is invoked only when the state has already been changed to the new state.
▪ NewState (string) — The ID of the new state of the package (or Model) that you are transitioning to (note that this is the state ID in the object’s “Package State” property when the script is triggered).
The CommitState function returns either True or False. The value in the Script.Result is ignored. If the function returns False, the operation is aborted and the transaction is rolled back (this includes all the other objects that are successfully processed for the same State Change session). The state of the model is restored to the state before triggering this function.