xP&A CX Commercial Planning - Understanding the technical structure of Stories

In this step you will learn about the structure of UI elements in each story.

Planning Reporting and Admin Pages Overview Pages

Depending on which story you are looking at, the high level structure of the UI elements may differ, but the core concept remains the same. In the following example we will take a look at the List Price Planning story to understand how reporting and planning stories are structured from a technical perspective.

Each page consists of multiple bigger groups or respectively Panels to put it in technical SAC terms.

These panels are used to structure the different sections of the story into different components in order to make the story more modular.

The CONTENT section is the section where the main part of the content is located. Based on what you have learned in the introduction tutorials, that could cover the header section with the high level graphs, but also the main area where the planning tables reside, for instance.

The ShellBar section is where the shell bar on the top is configured. All of the stories apart from the Overview Pages contain a bespoke shell bar built specifically for this content package, which consistently provides the exact same functionality across all stories.

The pnl_LeftSidePanel section is where the left-side panel is configured. As this component is used across all planning and reporting stories as well, it deserves to have an own container outside the CONTENT section.

The MainNavMenu section is where the navigation menu is configured. Other than the other sections, the MainNavMenu section is a composite object which is configured outside the story as this component is used across almost all stories of this content package.

In this step you will learn about the naming convention of UI elements and script objects in each story.

You may have noticed that most of the objects have some sort of abbreviations as prefix.

The abbreviations indicate what kind of technical object is used for the specific widget. Afterwards follows a descriptive naming. The following list will help you to understand the meaning of the abbreviations:

In this step you will learn about script variables and how they are named.

Generally the Script Variables section is the place where you can define global variables for your story.

In the scope of this content, two different groups of variables have been created.

• All variables with the prefix cfg_ are considered to be constant variables which are never changed.

• In native JavaScript language, these variables would be declared as const. As the in-built SAC IDE does not offer this, we decided to mark constant variables with the cfg_ prefix.

• All variables with the prefix g_ are considered to be ordinary global variables which can be changed or overwritten during runtime.

• In native JavaScript language, these variables would be declared as let. As the in-built SAC IDE does not offer this, we decided to mark these variables with the g_ prefix.

• Some of the variables are initialized directly in the menu provided by the builder panel.

  

• Other variables are initialized in the onInitialization script of the story. The following screenshot provides such an example.

  

Many variables are re-used across all stories while some of the variables only exist inside a particular story. The following list provides an overview of the most important and common variables and how they are used:

• The variable cfg_chartCollection is an array of chart objects which can be found in many stories and is initialized in the onInitialization script. It is used to store all chart objects of a particular story.

• The variable is mainly used in order to loop over all chart objects, making it easy to address all chart widgets of a story at once.

  

• The variable cfg_tableCollection is an array of table objects which can be found in many stories and is initialized in the onInitialization script. It is used to store all table objects of a particular story.

• The variable is mainly used in order to loop over all table objects, making it easy to address all table widgets of a story at once.

  

• The variable cfg_dimensionMapping of type Selection is initialized in the onInitialization script and serves as a dictionary which stores all dimension IDs of the data model and provides a descriptive naming to these dimensions.

  

• The left column, also known as the key, provides the descriptive naming for the dimension ID, whereas the right column, also known as the value represents the technical dimension ID as it is stored in the data model.

• This variable is used in order to ease the usage of dimension IDs in the scripts. By using this dictionary, you can work with the easy descriptions instead of having to write the entire dimension ID each time you call a script or API where you need to specify a dimension.

• If for instance your product dimension has a different dimension ID, you can simply replace the value in the dictionary with your own ID and the scripts will still work without having to change the dimension in every single line of code where the product dimension is used.

  

• The variable cfg_displayMode of type string is initialized in the onInitialization script.

• It is hard coded to one single value present and is used when switching over to other stories when using the navigation menu. The script used to open a new story consumes this variable and opens the story in present mode respectively. If you want to open the story in another mode than the present mode, you may change the value to any other valid value than present.

  

• The variable cfg_iconRepository of type Selection is initialized in the onInitialization script and serves as a dictionary to store the unicode of an icon together with its descriptive name in a key-value fashion similar to cfg_dimensionMapping.

• Also here, the main use case is to ease the usage and addressing of icons in the scripts.

  

• The variable cfg_measureMapping of type Selection is initialized in the onInitialization script and serves as a dictionary which stores all measure IDs of the data model and the story and provides a descriptive naming to these measures.

  

• Similar to the variable cfg_dimensionMapping, this dictionary is mainly used to ease the usage of measure IDs in the scripts. In addition to that it also provides more flexibility, as you can change the measure IDs in your data model freely and only need to update the new ID on one single spot instead of having to go into every single script where the measure is called.

  

• The variable cfg_planVersion of type string is initialized in both the onInitialization script and the Right-side panel where it is provided a default value.

• It is hard coded to the default plan version of this content package, which is the public.Plan version.

  

• The variable g_versionText of type string is used for the same purpose, except that it does not store the prefix but only the version text itself. Similar to cfg_planVersion, it is hard coded to the value Plan.

  

• The variable cfg_storyIds of type Selection is initialized in the onInitialization script and serves as a dictionary which stores all story IDs of the content package and provides a descriptive naming to these stories.

• This dictionary is used for the navigation menu. By having initialized this dictionary in a central place, you can create new stories or copy existing stories and maintain everything in one single spot instead of having to look for the button or widget where the script to open another story is called.

  

• The variable g_actionConfirmReset of type string is not initialized on startup and does not posses a default value. It is used in the process of publishing or reverting a version and stores information on whether the version will be published or reverted.

• Depending on the story, there may also be additional variables which have not been mentioned here. Covering every single variable which was created to serve for one particular purpose would go beyond the scope of this tutorial. Please check the in-line documentation to find out what they are used for and where they are used by using the in-built search function in SAC.

  

In this step you will learn about script objects and how they are clustered.

Generally the Script Objects section is the place where you can create scripts which then can be called by different events, such as onClick or onChange events for instance.

In the scope of this content, you will find three different groups of scripts, which are clustered in applicationScripts, layoutScripts and utilityScripts.

• The applicationScripts group is the place where all story specific scripts are stored. These kind of scripts are not re-usable as they execute a very specific task designed for one particular story only.
• The layoutScripts group is the place where all layout related scripts are stored. These kind of scripts are used to change the layout of the application and come into action when you collapse a table for example or expand a section.
• The utilityScripts group is the place where generic scripts are stored. These kind of scripts are reusable and provide basic functions which can be executed independent of the story you are working on, such as converting a date to a string or similar things.

Congratulations! You have finished the tutorial and are now able to navigate through the story from a technical perspective.

If you want to learn more about the modules of this content package, check out the following tutorials:

• xP&A Commercial Planning - Get to know the Sales Planning module
• xP&A Commercial Planning - Get to know the Portfolio Planning module
• xP&A Commercial Planning - Get to know the Marketing Planning module

If you want to customize the content and adjust it according to your own business requirements, the following resources might be helpful:

• xP&A Commercial Planning - Introduction to the Data Model
• xP&A Commercial Planning - Data Integration
• xP&A Commercial Planning - Manage data loads
• xP&A Commercial Planning - Add additional sections to a story
• xP&A Commercial Planning - Add an additional story to the Navigation Menu
• xP&A Commercial Planning - Customize Default Settings
• xP&A Commercial Planning - Customize Table Settings Dialogue
• xP&A Commercial Planning (Marketing) - Add a new Driver
• xP&A Commercial Planning (Marketing) - Add a new Version
• xP&A Commercial Planning (Marketing) - Extend activity spend dates
• xP&A Commercial Planning (Sales) - Add a new Version
• xP&A Commercial Planning (Sales) - Add a new Tactic
• xP&A Commercial Planning (Sales) - Add a new Spend Type

If you want to get an overview of the entire xP&A Commercial Planning content package, make sure to check out the Mission.

Interested in more xP&A topics and related business content packages? Visit our community page Extended Planning & Analysis Business Content.