Splicer Basics
- Adam Davis
Splicer Rule Parsing
In order to accurately comprehend area statements, Splicer needs to dissect the entire rule file and decompose it into its fundamental syntax elements. It employs the TM1 rules grammar to parse the rule and to deconstruct the area statement, facilitating further processing. As such, it's essential that the syntax of the rules remain valid at all times. If it doesn't, Splicer will terminate its operation due to a syntax error.
In order to keep processing times to minimum, Splicer will not be able to match elements in the area statement to individual dimension if context of the dimension is not explicitly stated in the area statement. Therefore it is important to always explicitly define dimension and optionally hierarchy when specifying element names in the area statement (this is however a best practice that should be observed at all times).
Splicing Directive Validity
A splicing directive is only applicable within certain portions of the rule. The association between the splicing directive and its applicable region is established by the directive's syntax (explained later).
Traditional region definition is employed to outline the splicing directive's validity. The splicing directive will only be activated within rules encapsulated by the defined region, which simplifies region identification when using the Arc editor.
Specific rules govern situations where competing splicing directives might apply to the same rule area statement and dimension. The splicing directive whose region is closest to the rule is prioritized, and the others are ignored.
Regions can intersect and nest within each other. There's no limit to the number of overlapping or nested regions.
To indicate the start of a region, use the following syntax: #Region <REGION>
To denote the end of a region, use the following syntax: #EndRegion <REGION>
REGION is the name of the region that determines the validity of the splicing directive.
You can verify the validity of a region using Arc. It will automatically display region collapse/expand controls with each #Region statement in the rule. This feature is helpful when checking matching #Region and #EndRegion statements.
If an #EndRegion for a certain REGION isn't defined, Splicer will assume the region terminates at the end of the cube rule file.
By convention we are using COMMON region to define region applying to the entire cube rule file.
Splicing Directives
Splicer utilises statements to identify targets within the area statement of each rule, and in the event of a match, determines which elements to substitute for the matched ones. These directives are specifically applicable to certain sections of the rule file, and will not be operational in others (refer to Splicing Directive Validity for more information).
These directives, situated at the top of the rule, form an integral part of it. To prevent them from meddling with the rule syntax, they are designed in the comment syntax. Thus, even after modification by Arc or Architect, the rule remains compatible.
Specific syntax rules must be followed while working with Splicer's splicing directives, below is basic syntax:
#Expand-Area-Definition(REGION, MDX_ID):DIM:HIER:PATTERN.
REGION refers to the area where the directive is operational and ties to existing region in the cube rule file.
MDX_ID is the ID of the MDX query executed to fetch a list of elements that will replace the matching DIM:HIER elements in the area statement.
The queries are defined in fpm.json file which serves as a catalog of MDX queries.
DIM denotes the dimension on which the directive acts (the directive does not apply to any other dimension in the area statement).
HIER is optional and outlines the hierarchy of the DIM dimension where the directive will solely be active.
PATTERN can either be a regular expression defining the matching pattern for the elements being replaced, or it could be the literal @mdx which implies validity across all DIM and HIER elements, if defined. It's important to note that only elements that match the pattern will be replaced.
Splicing directives are never applied to any other part of rule than the area statement. Splicer never checks validity of rule parts that follow area statement and will never modify it.
Splicing
Splicing is defined as search and replace running on a list of cube rule files followed by saving of each processed rule file.
Splicing has following parts:
Fetching the matching cube rule file | Splicer offers two operational modes: it can be applied to all cube rule files as outlined in fpm.json, or it can be restricted to cubes that incorporate a particular dimension in their structure as dictated by a command line parameter. This feature aids in reducing the number of cube rules requiring saving, thereby minimizing processing time. |
Generating KPI section | If the cube rule file contains a special FPM-KPI region, KPI rule statements will be spliced into the region according to settings in FPM Chart of Accounts module. |
Parsing the cube rule file | Cube rule file is parsed and splicing directives are assigned to each rule based on region definitions. Area statement of each rule is decomposed and pattern matching is run on each dimension/hierarchy elements in the area statement. Pattern matching is based on Python regular expressions syntax. All elements of specified dimension/hierarchy will be matched by specifying @mdx literal instead of a regular expression pattern. |
Establishing list of replacement elements | Splicer will run MDX query as dictated by matching splicing directive for each dimension/hierarchy combination that indicated match in previous step to obtain replacement elements. Two operational modes exist for MDX query operations when the MDX query returns an empty set. In the first scenario, an error message is displayed and a rollback of changes is triggered. In the second scenario, a fallback element as specified in fpm.json is utilized. |
Replacing matching elements | New area statement will be spliced by keeping non-matching dimension/hierarchy elements in place and replacing matching dimension/hierarchy elements with elements obtained in previous step. Part of the rule following area statement will be copied regardless its contents. |
Compilation and saving the cube rule file | Initially, the rule file that is due for modification will be backed up within the rules folder located in the Splicer installation directory. Also, the revised cube rule will be stored in the rules folder first, under a designated name as the proposed rule file for further troubleshooting purposes. In case TM1 does not report any errors, the rule can be saved on the TM1 server. However, if any issues are identified, Splicer will attempt to revert all changes to prevent non-functional rule files from residing in the TM1 server. |
De-splicing
De-splicing serves a critical role in FPM development as it generates a rule file devoid of any model-specific elements. This allows for the rule files to be uploaded to a development GIT system and distributed among the FPM development team. In the majority of situations, de-splicing doesn't hold significant relevance for the everyday functioning of the client's FPM model.
Â