As described in previous chapters there are exports for parts of the configuration, like domain definition or selected parameters. If the need to transfer configuration between environments appears or when saving a copy of the current configuration is needed - global exports are most helpful. In the Hyperon Module, there are two kinds of export: Superpack and Snapshot.
Snapshot is a file containing full parametrization from application or only parts of parametrization accordingly to set requirements, it is an alternative for Superpack file. What is the most important about snapshot export: it is less complicated than building a Superpack (batch). User only have to decide from which profile (or profiles) he would like to make an export and basically, thats it. Next step is to decide if all elements in profile should be exported, one may decide to export only selected functions and parameters, or not export functions and parameters at all. Furthermore SNAPSHOT will generate zip file, in which parameterization is described by tree structure, user may check what is within every region and version just by going through folders which are simulating tree structure.
To check xml file from snapshot open snapshot.zip (downloaded file) and go to @domains, file with selected profile name and subfolder @def there you should find xml file named after profile name (profile_name.xml). This xml-file is the same xml-file you can export from Domain Configuration.
Batch/Superpack export allows to:
There are few simple rules you should follow while creating Superpack:
Every step might produce Business Error or System error. Business errors are those which are caused by invalid configuration within Hyperon while import on target environment - examples of those errors are listed in every step description. System Error are unexpected exceptions in application code.
To control how import reacts on any of those errors in steps are attributes :
Depending on settings import might stop or continue when such problem occurs. If that happens, even if import did not stop after error, information about error will be displayed on report sheet, when import ends.
Superpack export is build step by step. User have to design export process and import process, what includes :
What are those steps, then? Steps are settings of export. Since the is no scheme of export, every Superpack is customised plan of data export.
Superpack steps have attributes. They describe, in detail, how each step should be executed. Below is a screen of attributes for one of available steps :
When by the name of attribute symbol of asterisk is visible (1) - then it is obligatory to set value for that attribute. When field for value is greyed out (2) then value will be set automatically. There are attributes with default value (4), those are not marked with asterisk or grayed out. That default value might be overwritten by setting value for such attribute. For selected attributes there are additional guidelines, visible after clicking on question mark icon (3).
It is intended to characterise value, which will be declared during import. This step also provides validation while value is given. When step Property is added to Superpack, it also needs to be linked in other steps. This step by itself have no influence on import or export. It is setup for other attributes values (in other steps).
Attributes:
If Property step is in Superpack export configuration, then while import popup will show:
Settings in example (numbers in brackets are numbers from pictures):
If user tries to insert incorrect value, then appropriate message will occur next to wrongly filled property.
In this case maximum value was set: 20 (4), but regex expression allows only for single character value.
It sets version on target environment
Attributes:
Possible Business Errors:
It sets profile on target environment
Attributes:
Possible Business Errors:
It sets new default value on OnSystemError attribute for all steps added to Superpack.
Attributes:
It sets new default value on OnBusinessError attribute for all steps added to Superpack
Attributes:
It adds selected version to Timeline
Attributes:
Possible Business Errors:
RollBackSession- discards opened session on current user account (all changes from session are reverted to last published state)
There is a rule to never create or import Superpack if user have an open session.
Attributes:
It sets system versions (those active by settings in Timeline) as visible versions, resets versions on whole target environment (in every profile). On profiles, where are no regions or versions, this step will not cause any changes or errors.
Attributes:
It allows to transfer parameter between versions (only if parameter is assigned to region)
This step is divided into three sections: first are basic attributes, next are filter settings and last is multiload configuration table.
Attributes:
Possible Business Errors:
It allows to transfer function between versions (only if function is assigned to region)
This step is divided into three sections (just like MultiLoadParams): first are basic attributes, next is filter settings and last is multiload configuration table.
Attributes:
Possible Business Errors:
It allows to transfer domain elements between versions (only if domain element have business role : PRODUCT and is assigned to region)
This step is divided in two sections : first are basic attributes, second is multiload configuration table.
Attributes:
Possible Business Errors:
It loads list of users (all user information with: login and password) with roles assigned, from export environment. This step does not include information about set roles, only names of those roles. To export roles and grants assigned to them select step LoadRolesAndRights.
Attributes:
Possible Business Errors:
It loads all tags from export environment but does not contain list of parameters or functions with exported tags. To export parameters and functions information, like: tags assigned, add steps LoadParameters / LoadFunctions.
Attributes:
It creates xml file with full configuration of context from selected Profile.
Attributes:
Possible Business Errors:
It loads all roles and grants from export environment
Attributes:
It loads all regions from export environment only for selected profile
Attributes:
LoadParams
It loads all parameters, which in moment of export are visible:
Attributes:
Possible Business Errors:
It loads all functions which in moment of export are visible (assigned to version of region set as visible, in Timeline, in moment of export and all global functions - not assigned to any region)
Attributes:
Possible Business Errors:
It loads domain elements which in moment of export is visible (assigned to version of region set as visible, in Timeline, in moment of export and all global elements of domain - not assigned to any region)
Attributes:
Possible Business Errors:
DeleteParams - allows to delete parameters from current view (assigned to version of region set as visible, in Timeline, in moment of export). Creates list of parameter codes (names) and exports it as txt file. That list is used to search through target environment, then elements from the list:
- will be deleted (if 'leftSelected' step is set: false) or
- will not be deleted (if 'leftSelected' step is set: true) but every element, not named in file, will be deleted.
This step is vulnerable to versioning. Before executing this step make sure both export environment and target environment are set on the right view.
Attributes:
It allows to delete parameters from current view (assigned to version of region set as visible, in Timeline, in moment of export). Creates list of parameter codes (names) and exports it as txt file. That list is used to search through target environment, then elements from the list:
This step is vulnerable to versioning. Before executing this step make sure both export environment and target environment are set on the right view.
Attributes:
It creates a new version on target environment based on existing version from export environment. Creating new version does not influence 'visible version' settings but may change 'system version' settings in My View
Attributes:
Possible Business Errors:
It creates a new region on target environment (on Profile set on target environment) and first version in that region - in Hyperon, region cannot exist without version. Creating region will not cause assigning any elements to new region. If exported elements are assigned to region named the same as new region, then Hyperon will interpret it as the same region.
Attributes:
Possible Business Errors:
It creates a new profile on target environment. Creating new profile will not cause setting it as visible profile on target environment.
Attributes:
Possible Business Errors:
It causes publication of active session. That step may be used at the begging of export (to publish any changes in current user session) or at the end (as autocommit). Commit session may cause Business Error, if during publishing conflict with another user's session will appear. If that happens, Cohesion analysis will be necessary.
Attributes:
Possible Business Errors:
It checks if on target environment, on current user profile is active (open) session. Returns set description if open session is found.
Attributes:
Possible Business Errors:
Full Filter
Basic filter allows to select those elements (functions or parameters) which name contains stated phrase. Not always that is a sufficient criterion. In Full Filter you may create additional conditions for your search. Including:
Additionally you may add time frame for last made (and published) modifications of the element:
Remember that search goes with logical conjunction. Which means that all filters must apply at once.
Suggested order :
Those two are not necessary if you know that there is no active session (on current user account) in the moment of import
Following steps don't need any settings on target environment (no chosen profile, region etc.):
* - steps global for the environment
Batch/Superpack import loads all changes based on provided zip batch file, which was exported. This functionality allows users move Hyperon configuration from one environment to another.
It is safer way to export your data from one environment to another. User doesn't have to export all data, regarding structure, from Hyperon application.
To export snapshot click Tools and Snapshot export on main Toolbar, following view will appear:
As you may see in the picture there is a choice connected to creating a snapshot file. You may export data about Domain (definition, configuration, attributes, values), Functions, Parameters, Profiles and Tags but to avoid errors you should follow few rules. When you want to export Domain, you need to export Profiles as well because in Hyperon application every Domain Configuration is connected to profile and one can not exist without the other. To export Tags it is recommended to export all : Functions and Parameters. Because Tag is kind of a label, which supposed to make search easier, or allow to group you parameters. And if you only export Tags, not Parameters and Functions, you will have a label but in your snapshot there will be no elements with that label even if in profile from which you are exporting data were. If what you want is to export only functions and parameters you also need to export Profile if you want Regionazing and Versioning to work after importing snapshot.
Then you may chose your export settings. To create snapshot file first select source Profile (from which you would like to export data):
Next step is selecting types of objects for export: Domain, Functions, Parameters, Profile with or without Context and Tags. User may choose all or only few of them - as discussed earlier. For every one of those types there is a functionality that may be used:
Those functionalities have influence on data within snapshot file, so be aware which checkboxes are needed for the result you expect.
Here we are going to focus on how to read and edit snapshot file. As previously mentioned it is a zip file containing tree structured parameterization. Depending on what where the settings during export this file may look differently. Here we are going to look into a case of full parameterization export (including: Profile, Tags, Domain, Functions and Parameters) - where we can find domain elements, functions and parameters assign to regions and versions.
When export is made and file is saved (downloaded) user may see what is included in zip file, first layer is general division between Profile, Tags, Domain, Functions and Parameters:
The last file : config.json will be described in the end of this chapter.
Inside file @domain user will find files named by exported profiles, since Domain is assign to profile and cannot exist without it. Then, inside every of those files will find @conf and @def file which are equivalent of Domain Configuration and Domain Definition parameterization.
File @conf is structured in accordance with Domain Definition types, their Components and Business attributes. It is made analogically to navigation, which user can see on Domain Configuration screen, where he can create objects defined by types from Domain Definition.
File @def contains .xml file - the same which may be made in Domain Definition section by using "Export to xml" button.
If type is defined in Domain Definition but in Domain Configuration no element of that type was created then file for that type will not be included in @conf file. Nevertheless that type will be considered while creating @def file.
Let's look into profiles. Inside file @profiles user will find files named after all selected profiles to export. In this case only one profile has been exported and that is profile GROUP. While going further user will find file @regions and context.def (if in export check 'with context' was selected). In @regions file are all regions created in structure. Inside every one of those is catalog @versions where user will find files containing definitions of versions inside selected region- number.ver where number = 1,2,3.. is name of version given by system. What's more in region named file user may check: schedule schedule_regionName.csv (which is responsible for when which version is active) and region definition regionName.info
Structure for parameters and functions is similar only difference is in how function and parameters are defined. for every exported parameter is defined by two depending files : \*.mat and \*.def. First one describes the matrix in parameter and second one parameter definition. Definition of functions is stacked into one \*.js file containing information about function arguments and function code.
Path to parameter files may look like on the picture below:
Path depends from the name (code) of parameter/function and region to which selected parameter is ascribed.
For example in that snapshot file under number 1 is parameter that have no region ascribed (it is a global parameter, that is why it can be find under @global file ) named: group.deviationPerSelectedRider every ' . ' (dot) in name of the element (parameter or function) is interpreted as another file in the structure. If we want to know full name of the second parameter (2) we would have to take every folder name, starting with first folder inside @global: 'group' then add ' . ' (since every dot means going one folder further), next is 'business' another ' . ' and 'activity', so full name of this parameter is : group.business.activity
If instead of going into @global user will check @profiles he would find all the parameters that are ascribed to regions and versions (element that is ascribed to region is always ascribed to version).
What if function is ascribed to region? Then file structure will change, because there will be few additional catalogues (for region and version to which element was added).
If we have functions ascribed to region in file structure it will be placed inside: profile named catalogue, then ascribed to region catalogue, next to version catalogue. In structure of snapshot .zip file in @functions catalogue, that kind of function is placed in @profiles file then inside profileNamed catalogue (1), @region (2) and inside that in regionNamed file, further inside is versionNumber catalogue and then file structure of function like: group.distribution.normal.groovy where functionName.groovy may also be functionName.rhino (depending on the language applied in function definition).
When it goes to @tags: inside this file there always are two other ones, @basic and @access, in both of those user will find files like tagName.tag containing selected Tag definition. Tags are divided between those catalogues because some of those were created with access control and those will be in file @access.
On config.json file influence have only three actions, two may be find on the Snapshot export screen:
Those are responsible for filtering elements during export and import, narrowing or expanding the range of imported changes. The third one may be find in the config.json file: searchWithinParameterMatrix. This action is only used by import if 'Remove elements not included in snapshot' was selected during export, or set on 'true' in config.json file . This action, while set on: 'true' verifies if element, which should be deleted, is called in parametr matrix (is used in parameter matrix), but by default it is set on : 'false'. What means that if user doesn't apply any changes in config.json file parameters matrix won't be checked.
For example, if export is configured like:
Then config.json file:
Generally we can say that config.json file is divided into four sections:
It is not advised to change filters in config.json file because it may cause errors during import. Filters are defined for functions and parameters like: "nameStartsWith":["filter\_1","filter\_2"].
Editing config.json file is advised when user wants to change settings of removeNotInSnapshot (for parameter or function) and searchWithinParameterMatrix (verify usages of element prepared for deletion) which is disabled by default.
Special cases:
When you want to import file just select Import snapshot from toolbar Tools/Import snapshot.
Then window will popup and one will have to select snapshot zip file for import.
Here user may chose from two non-obligatory options:
If snapshot export screen was set like on the picture below:
Then config.json file:
Since we applied filter on functions, now only those which name starts with : "group.util" will be included in SNAPSHOT file. Because second checkbox was not selected none functions should be deleted while import.
When it goes to parameters only those with name starting with: "group.product" should be included in snapshot file. What's more since that filter was set in export configuration and checkbox "Remove elements not included in snapshot" was selected while import only parameters which name starts with words "group.product" will be considered while deleting those not in exported file.
For example:
If in environment (A), from which export is made, following functions exist:
Only group.util.offer.calculateBenefit and group.util.offer.calculateSumLimit will be packed in snapshot.
If in environment, from which export is made, following parameters exist:
Then only group.product.availability is accurate by applied filter.
Then in Snapshot:
Let's assume that on the second environment (B), where import is made, exist functions:
and parameters:
After import: functions from environment B will still be there and those in snapshot file will add to the structure. But when it comes to parameters, after import, all those in environment B which name does start with "group.product" and are not in file, will be deleted (like: group.product.default). Because group.dictionary.pkd and group.product.availability do not start with "group.product", while import, their presence in file is not even checked. In other words, filter is applied not only when exporting structure but also while import, that being said : import may change only those elements which meet the requirements of the filter (if filter is applied).
After Import state of environment B:
Result window will pop up, when process is finished - this import summary is called Import report.
Informs if import went without problems
Warning status may show this icon may show in few cases (in every one of those cases user may click on eye icon to check with which one user is dealing with):
What kind of element was checked during import, influenced by changes
Number of files imported from snapshot file. All elements of selected type included in snapshot export file.
How many files were deleted during import (that is the result of config.json file)
Number of errors that occurred
How many files were skipped, happens when element is contained in snapshot file but it is exactly the same as in environment on which import is made.
Only if option autocommit was selected
Clicking on icon Eye icon opens information window, where user may check message for every element influenced by import.