1

Стандарт оформления Rules в Calculation Manager

Автор: Шамаев Иван (ivan.shamaev@gmail.com) - ivan-shamaev.ru Использовал материалы с сайта essbase.ru - Расюк Евгений (er@essbase.ru)

2

Оглавление Оглавление ................................................................................................................................................................... 2 Цель документа ........................................................................................................................................................... 3 Введение ...................................................................................................................................................................... 3 Краткое описание объектов Calculation Manager ..................................................................................................... 3 Стили именования ....................................................................................................................................................... 5 Правила именования объектов Rules ........................................................................................................................ 5

Наименование Rules ................................................................................................................................................ 5 Наименование переменных ................................................................................................................................... 5

Требования к объектам программирования в Calculation Manager ....................................................................... 6 Использование переменных запуска (Runtime-Prompt, RTP) в правилах расчета ............................................. 6

Требования к оформлению кода в Calculation Manager .......................................................................................... 7 Требования к структуре кода бизнес-правил (Rules) ............................................................................................ 7 Требования к форматированию текста программы ............................................................................................. 7 Перечисление элементов в разделе FIX ................................................................................................................ 8 Порядок следования FIX блоков ............................................................................................................................ 8 Требования к версии ............................................................................................................................................... 9 Требования к комментариям ................................................................................................................................. 9

Рекомендации по разработке бизнес-правил ........................................................................................................ 10 Ключевые факторы хорошего кода (выжимка из вышеописанного) ................................................................ 10 Шаблон бизнес-правила (BR07 0208.01: Бюджет ИТ - Расчет Итого. Шаблон) ................................................ 11

Общее построение бизнес-правила ................................................................................................................. 11 Содержание шаблона с настроечными параметрами расчета ..................................................................... 11 Содержание скрипта ......................................................................................................................................... 12 Заполнение свойств скрипта............................................................................................................................. 12

Перенос бизнес-правила из EAS Console в Calculation Manager ........................................................................ 12 Какие переменные можно использовать, а какие запрещено использовать .................................................. 13 Как используем Templates .................................................................................................................................... 13

Приложение 1. «Краткое описание настроечных параметров» ........................................................................... 14 1. Data Volume ........................................................................................................................................................ 16 2. Data Handling ...................................................................................................................................................... 16 3. Memory usage ..................................................................................................................................................... 17 4. Threading ............................................................................................................................................................. 17 5. Logging ................................................................................................................................................................. 17

3

Цель документа Документ является соглашением по оформлению и написанию Rules в Hyperion Calculation Manager. В документе приведены основные правила оформления кода.

Цели документа:

Предоставить краткое описание существующих объектов в Calculation Manager;

Предоставить общие правила, позволяющие сохранить единый стиль написания кода, облегчив тем самым его понимание всеми участниками команды;

Ввести базовые правила написания кода, что позволит повысить предсказуемость выполнения кода, а также избежать ошибок при написании кода новыми участниками команды, не знакомыми с внутренними стандартами разработки.

Введение Для разработки бизнес правил должен использоваться Calculation Manager. Все правила создаются

путем набора локальных скриптов и шаблонов. Все алгоритмы, которые используется в коде более одного раза, должны быть определены в шаблонах (например, агрегация). Далее требования одинаковы как для шаблонов и локальных скриптов, так и для бизнес-правил.

Краткое описание объектов Calculation Manager Substitution variable - Эти объекты и значения переменных хранятся на сервере EssBase и

применяются для управления процессом расчета. В этой переменной можно сохранить текстовые значения длиною до 255 символов. Эти сущности являются основными для управления процессом бюджетного контроля и расчета.

Rules (бизнес-правила) – расчеты, реализованные в системе на специальном языке. Как правило, бизнес-правила прикрепляются к формам ввода и могут запускаться автоматически при определенных действиях пользователей (открытии или сохранении данных в форме ввода).

RuleSets (набор бизнес-правил) – совокупность бизнес-правил, которые вместе составляют единый расчетный процесс. RuleSet запускает последовательно или одновременно бизнес-правила в зависимости от логики расчета.

User Variables – Пользовательская переменная, создается администратором (администратор ассоциирует пользовательскую переменную с измерением Hyperion Planning) и используется в формах данных. Значения переменной задаются пользователем при входе в приложение Hyperion Planning. Тем самым пользователь определяет контекст, в разрезе которого ему необходимо отображать информацию на формах, в которых используется эта пользовательская переменная. Например, в форме данных в строках выводятся бизнес-юниты, которые пользователь задает через пользовательскую переменную. При запуске бизнес-правил можно передавать значения пользовательской переменной в бизнес-правило, если только стоит настройка «use members on form» и пользовательская переменная находится в POV или Page формы данных.

Formula - определенный набор логики бизнес-правила или синтаксис, который может использоваться в нескольких бизнес-правилах. Когда требуется обновить логику, требуется внести изменение только в формулу (локализация изменений) и обновление фактически будет внесено в каждое из правил. Формула состоит из набора расчетных операторов (calculation statements), которые пользователи могут написать или спроектировать, используя members, functions и, опционально, условные операторы (conditional statements).

4

Script – состоит из набора автономных расчетных операторов или функций (calc command/functions statements).

Templates - это набор предопределенных стандартных расчетов (например, Clear data, Copy Data, Essbase commands, Amount= Rate*Unit, Aggregate, Allocate). Выделяются системные шаблоны и шаблоны, которые определены пользователями (custom templates). Вы можете включать системные и определенные пользователями шаблоны в бизнес-правила, перетащив их в редакторе бизнес-правила из соответствующих разделов. В качестве компонентов бизнес-правил, шаблон содержит ряд шагов, в которые вводятся параметры.

Execution variable – это переменная VAR или ARRAY типа. В текущем проекте запрещается использовать данные переменные.

Replacement Variable – переменная, которая задается через Variable Designer. Для изменения значения переменной необходимо зайти в Variable Designer и внести изменения. Доступные типы для Replacement Variable в Calculation Manager:

Numeric; Integer; String; Essbase; Cross Dimension; Dimension; Member; Members; Percent; StringAsNumber; DateAsNumber; Member Range

RunTime Promt (RTPs) – это replacement variable, у которой в настройке стоит галочка у пункта RTP. При запуске правила необходимо подтвердить значение переменной по умолчанию, либо ввести другое значение.

Иллюстрация взаимосвязей между компонентами Calculation Manager:

5

Стили именования

Camel case (UpperCamelCase): первая буква первого слова в идентификаторе в верхнем регистре, все первые буквы последующих слов также начинаются в верхнем регистре.

Пример: DepartmentFrom;

Camel case (lowerCamelCase): первая буква первого слова в идентификаторе в нижнем регистре, все первые буквы последующих слов – в верхнем.

Пример: переменная vSaleBusinessUnits;

Правила именования объектов Rules

Наименование Rules

Имя правила не может превышать 50 символов. Наименование бизнес-правила состоит из следующих частей:

<Префикс объекта Calculation Manager> + <Номер приложения> + ПРОБЕЛ + <Номер папки> + “.” + <Порядковый номер объекта> + <Краткое описание объекта>

BR07 0208.01: Бюджет ИТ – CAPEX BR07 0208.02: Бюджет ИТ – OPEX BR07 0208.03: Бюджет ИТ – AGGR TOTAL TM07 0208.01: Шаблон алгоритма расчета OPEX

Номер папки – номер папки с формами данных. Префикс объекта – это краткое обозначение объекта для упрощенной идентификации принадлежности объекта к той или иной функциональной группе Calculation Manager. Если объект не относится к какой-либо папке, то используем нули, например:

TM07 0000.01 – Общие параметры расчета

Префиксы объектов Calculation Manager:

BR – бизнес-правила (rules);

TM – Шаблоны (Templates);

FR – Формулы (Formulas);

SC – Скрипты (Scripts);

RS – Наборы правил (Rule Sets).

Наименование переменных

Для имен переменных используется стиль Camel case (lowerCamelCase), при этом первым символом является префикс “v”. В имени переменной не должно быть символов и кириллицы. Пример: vSaleBusinessUnits.

6

Требования к объектам программирования в Calculation Manager

Для разработки бизнес правил должен использоваться Calculation Manager. Все правила создаются путем набора локальных скриптов и шаблонов. Все алгоритмы, которые используются в коде более одного раза, должны быть определены в шаблонах или скриптах (например, агрегация). Далее требования одинаковы как для шаблонов и локальных скриптов, так и для бизнес-правил.

Использование переменных запуска (Runtime-Prompt, RTP) в правилах расчета

Создан единый набор переменных Runtime-Prompt для каждого измерения:

Допускается использование только перечисленных RTP переменных. В случае острой необходимости добавления новой переменной, Вы обязаны согласовать требуемое изменение с участниками команды.

С целью унификации использования переменных RTP, в случае интеграции с внешними скриптами, переменные продублированы в EAS Console (как Essbase Substitution Variables):

7

Управление Substitution Variables для внешних скриптов осуществляется в интеграционном скрипте MXL:

Требования к оформлению кода в Calculation Manager

Требования к структуре кода бизнес-правил (Rules)

Код программы должен состоять из следующих частей: 1. «Шапка» бизнес-правила, в которой указывается следующая информация:

Имя правила, дата создания, версия правила, кто создал правило;

Краткое функциональное описание бизнес-правила, производимых действий над данными (например, Скрипт рассчитывает бюджет ИТ, считаются такие-то показатели по таким-то бизнес-юнитам, для того-то и того-то производится аллокация доходов или расходов);

Перечисление форм с входными параметрами, входящие данные для расчета (т.е. даем краткое описание источников данных для расчета с указанием ключевых элементов среза) и результирующие данные (рассчитываемый срез данных). При использовании виртуальных иерархий на единичках необходимо описать, что в данном скрипте задействована виртуальная иерархия. Данные хранятся в тех блоках, где на пересечении двух измерений бизнес-юнитов по такой-то статье загружены единички.

История изменений (должна включать в себя автора изменений, версию, краткое описание изменений). Также в тексте правила, в комментариях к отдельным частям расчета, необходимо давать расшифровки по внесенным изменениям;

2. Настроечные параметры бизнес-правила для запуска расчета (более подробная информация по настроечным параметрам - https://docs.oracle.com/cloud/latest/financialscs_gs/FATCR.pdf). В каждом скрипте используем шаблон «TM07 0000.01 Общие параметры расчета» (порядок использования шаблона описан в пункте «Общее построение бизнес-правила» документа). Шаблон состоит из следующих настроечных параметров (сами настройки с течением времени могут претерпевать изменения):

SET MSG SUMMARY;

SET UPDATECALC OFF;

SET AGGMISSG ON;

SET EMPTYMEMBERSETS ON;

SET FRMLBOTTOMUP ON;

SET CREATEBLOCKONEQ OFF;

SET CACHE ALL;

SET CACHE HIGH;

SET LOCKBLOCK HIGH;

SET CALCPARALLEL 4;

SET CALCTASKDIMS 2; 3. Код бизнес-правила.

Требования к форматированию текста программы

Для повышения читаемости бизнес-правил необходимо придерживаться следующих рекомендаций:

Каждый настроечный параметр расчета необходимо снабжать комментарием, что регулирует данная настройка;

Отображать вложенные FIX с отступом в табуляцию;

В условиях FIX элементы каждого направления располагать на отдельных строчках;

8

Снабжать элементы, из имени которых не понятно, что они означают, комментариями с его алиасом или описанием;

Внутри FIX расчеты тоже отображать с отступом;

Каждый элемент расчета писать на новой строчке и начинать с унарного оператора;

Снабжать каждый элемент расчета комментарием с его алиасом или описанием;

Обязательно помечать, если расчет базируется на блоках, которые были созданы в других скриптах, в каком скрипте, зачем, как и почему это было сделано.

Перечисление элементов в разделе FIX

Конструкции вида FIX…ENDFIX, IF…ENDIF используются для ограничения или фильтрации среза данных в расчетах. Если требуется выполнить расчет по набору элементов, то нужно стремится выражать срез расчета через функции, возвращающие список элементов (например, @RELATIVE("YearTotal",0)).

При использовании в FIX конструкций сравнения вида:

"Member(member list/range) AND Variable/Member(member list/range)"

или функций типа

@REMOVE(Member(member list), Member(member list))

Их необходимо выделять в отдельный FIX (несмотря на требование выше) и использовать команду

SET EMPTYMEMBERSETS ON перед этим FIX или вначале бизнес-правила (rule). Несоблюдение этих требований может привести к некорректному определению среза и увеличению времени расчетов.

Вложенные FIX по одному измерению приводит к объединению срезов описанных в каждом, а не к их пересечению.

Порядок следования FIX блоков

Первая строчка указывает параметры запуска расчета, передаваемые по стандартным измерениям (год, версия, сценарий). Вторая перечисляет все пользовательские измерения, причем те измерения, которые нужны для расчета в детализации, так же здесь указываются, их нужно ставить в комментариях. Затем происходит раскрытие детальных аналитик.

9

Перед основным телом расчета всегда должен быть раздел с зачисткой исходных данных.

Требования к версии

Переменная vVersionCalc в каждом бизнес-правиле должна проходить проверку на принадлежность к ветке «VER_CALC», которая находится в измерении версий:

Требования к комментариям

Комментарии должны содержать только функциональное описание текущего расчета. Закомментированный код нужно удалять.

Обязательно заполняются все Description поля у всех объектов Calculation Manager. Запрещается комментирование на английском языке, необходимо все описывать на русском языке. Нельзя использовать жаргонные слова в комментариях, сокращения также не допустимы. Стараться

использовать общепринятую в рамках проекта терминологию. Это необходимо для аудита качества информации аналитиками и облегчения передачи скриптов другому разработчику.

Если используется специфический метод расчета, у которого есть наименование, то необходимо в комментариях указать это наименование. Плюс кратко описать суть методики расчета.

10

Рекомендации по разработке бизнес-правил

Ключевые факторы хорошего кода (выжимка из вышеописанного)

Диаграмма MindMap, представленная ниже, содержит основные пункты, которых необходимо придерживаться для написания качественного кода:

11

Шаблон бизнес-правила (BR07 0208.01: Бюджет ИТ - Расчет Итого. Шаблон)

Общее построение бизнес-правила

Построение бизнес-правила сводится к следующим шагам: 1. Перетаскиваем шаблон со стандартными настроечными параметрами в бизнес-правило

(шаблон хранится в кубе D02FUNCB); 2. Перетаскиваем из New Object «Script» в бизнес-правило; 3. Заполняем в скрипте Properties (это шапка скрипта); 4. Пишем код в скрипте на вкладке Script.

Желательная структура скрипта:

Содержание шаблона с настроечными параметрами расчета

Шаблон с настроечными параметрами является общим для всех бизнес-правил. При необходимости настроечные параметры переопределяются в скрипте расчета.

12

Содержание скрипта

Пример заполнения скрипта по стандарту оформления. Комментарии, которые относятся к коду, заполняются в объекте Script.

Заполнение свойств скрипта

Шапка скрипта заполняется в поле Description. Входные данные и история изменений хранятся в поле Comments.

Перенос бизнес-правила из EAS Console в Calculation Manager

Чтобы не терять графический интерфейс разработки бизнес-правил, необходимо текст бизнес-правила, которое вручную переносится из EAS Console в Calculation Manager, вводить в объект Script. Последовательность действий:

1. Создаем бизнес-правило. 2. Переносим шаблон с настроечными параметрами расчета в бизнес-правило. 3. Переносим в режиме Designer из New Object элемент Script в бизнес-правило. 4. Вставляем в скрипт подготовленный код бизнес-правила (переопределяем настроечные

параметры расчета, если это необходимо). 5. Заполняем в Properties поля. 6. Код бизнес-правила можно разрабатывать «вручную» без других элементов из New Object.

13

Какие переменные можно использовать, а какие запрещено использовать

1. EXECUTION VARIABLE запрещено использовать, т.к. могут возникнуть те или иные проблемы с производительностью.

2. Используем только Replacement Variables и substitution variable.

Как используем Templates

Создаем Templates и в коде бизнес-правила прописываем строчку с параметрами:

%Template( name:="D02FUNCB Норматив=средний по юниту" ,application:="D07FUNC" ,plantype:="D02FUNCB" ,dtps:=() )

Иллюстрация использования Templates в Rules:

14

Приложение 1. «Краткое описание настроечных параметров» Настройка Обязательность

использования Краткое описание

SET AGGMISSG Используем SET AGGMISSG specifies whether Analytic Services consolidates #MISSING values in the database. The default behavior of SET AGGMISSG is determined by the global setting for the database.

SET CACHE Используем SET CACHE specifies the size of the calculator cache.

SET CALCTASKDIMS Используем SET CALCTASKDIMS specifies how many of the sparse dimensions in an outline are used to identify potential tasks that can be run in parallel.

SET CALCHASHTBL Не используем Не используется (настройка устарела).

SET CALCPARALLEL Используем SET CALCPARALLEL enables Analytic Services to use parallel calculation. Analytic Services analyzes each pass of a calculation to determine whether parallel calculation is possible. If it is not, Analytic Services uses serial calculation even if CALCPARALLEL is set.

SET CLEARUPDATESTATUS Опционально SET CLEARUPDATESTATUS specifies when Analytic Services marks data blocks as clean.

SET DATAEXPORTOPTIONS Опционально Each SET DATAEXPORTOPTIONS command specifies a set of option values that are in place until the next SET DATAEXPORTOPTIONS command is encountered. At that time, option values are reset to default, and newly specified option values are set.

SET EMPTYMEMBERSETS Используем If EMPTYMEMBERSETS is ON, and a FIX command evaluates to a empty member set, the calculation within the FIX command stops and the following information message is displayed: "FIX statement evaluates to an empty set. Please refer to SET EMPTYMEMBERSETS command." The calculation resumes after the FIX command. If a calculation script contains nested FIX commands, the nested FIX commands are not evaluated.

SET COPYMISSINGBLOCK Опционально SET COPYMISSINGBLOCK allows DATACOPY to avoid creating #MISSING blocks during the copy of data from a dense dimension.

SET CREATEBLOCKONEQ Используем If calculations result in a value for a sparse dimension member for which no block exists, Analytic Services creates a new block. Sometimes, the new blocks are not desired; for example, when they contain no other values. In large databases, creation and

15

processing of unneeded blocks can increase processing time as well as the storage requirement for a database.

SET CREATENONMISSINGBLK Controls whether or not potential blocks are created in memory for calculation purposes and whether or not #MISSING blocks are stored. The SET CREATENONMISSINGBLK command affects the results of calculations on both sparse and dense dimensions.

SET FRMLBOTTOMUP Используем Optimizes the calculation of complex formulas on sparse dimensions in large database outlines. This command tells Analytic Services to perform a bottom-up calculation on formulas that would otherwise require a top-down calculation.

SET LOCKBLOCK Используем Specifies the maximum number of blocks that Analytic Services can get addressability to concurrently when calculating a sparse member formula. You can choose one of three levels. The number of blocks that Analytic Services can get addressability to at each level is defined using the CALCLOCKBLOCK setting in the essbase.cfg file.

SET MSG Используем Sets the level of messaging you want returned about calculations, and enables simulated calculations.

SET NOTICE Опционально This setting provides completion notices at intervals during the calculation. The number of notices depends on the level you specify.

SET UPDATECALC Используем SET UPDATECALC turns intelligent calculation on or off. Using intelligent calculation, Analytic Services calculates only dirty blocks, such as updated data blocks and their dependent parents.

SET UPTOLOCAL Опционально Restricts consolidations to those parents with the same defined currency. The default is OFF.

SET DATAIMPORTIGNORETIMESTAMP Опционально Specifies whether to ignore the outline timestamp captured at the time the data was exported. The DATAEXPORT "Binfile" command captures the outline timestamp when it creates a binary export file. By default, when the file is imported, Essbase checks the import file timestamp against the existing outine timestamp to ensure the correct import file is read. You can use SET DATAIMPORTIGNORETIMESTAMP to bypass checking the timestamp. Caution: Bypassing the check enables potentially importing the wrong file.

SET CCTRACKCALC Опционально Specifies whether Analytic Services checks the flags set by the CCTRACK setting to

16

determine if the currency data has already been converted. By default CCTRACK is turned on. Analytic Services tracks which currency partitions have been converted and which have not. The tracking is done at the currency partition level: a database with two partitions would have two flags that could be either "converted" or "unconverted." Analytic Services does not store a flag for member combinations within a partition.

SET FRMLRTDYNAMIC Опционально Enables you to turn off calculation of all dense Dynamic Calc members during batch calculation if runtime dependent functions are included in formulas on stored members. This command improves batch calculation performance by removing the overhead of calculating all Dynamic Calc members.

SET REMOTECALC Опционально For applications with transparent partitions, turns remote calculation to the source on or off. When you are working with transparent partitions and are sure that a calculation script does not include remote values in the calculations, you can use SET REMOTECALC OFF to improve calculation performance.

SET RUNTIMESUBVARS Опционально Declares runtime substitution variables that are used in a calculation script. Every runtime substitution variable used in a calculation script must be declared in the SET RUNTIMESUBVARS command. The name of a runtime substitution variable is required. Specifying a default value for the runtime substitution variable is optional. Also optional is a description of the runtime substitution variable's data type and data input limit, which is a string in the <RTSV_HINT>rtsv_description</RTSV_HINT> tag.

1. Data Volume

(UPDATECALC) Specify whether to calculate only dirty blocks, such as updated data blocks and their dependent parents, or all data blocksDefault (CLEARUPDATES) Specify when data blocks are marked as cleanDefault (EMPTYMEMBERSETS) Specify whether to stop the calculation within a FIX command if the FIX evaluates to an empty member setDefault (FRMLBOTTOMUP) Specify whether to optimize the calculation of complex formulas on sparse dimensions in large database outlinesDefault

2. Data Handling

(AGGMISSING) Specify whether to consolidate #MISSING values in the databaseDefault (CLEARBLOCKONEQ) Specify, within a calculation script, whether new blocks are created when a calculation formula assigns anything other than a constant to a member of a sparse dimensionDefault

17

(CREATEONMISSINGBLOCK) Specify whether potential blocks are created in memory for calculation purposes and whether #MISSING blocks are storedDefault (FRMLRTDYNAMIC) Specify whether to turn off calculation of all dense dynamic calc members during batch calculation if runtime dependent functions are included in formulas on stored members. (This command improves batch calculation performance by removing the overhead of calculating all dynamic calc members.)Default (REMOTECALC) Specify whether to turn remote calculation to the source on or off for applications with transparent partitionsDefault

3. Memory usage

(CALC CACHE) Specify the size of the calculator cacheNo changes (Use System default) (LOCKBLOCK) Specify the maximum number of blocks to get addressability to concurrently when calculating a sparse member formulaNo changes (use system default)

4. Threading

(CALC PARALLEL) Specify whether to enable parallel calculation or serial calculation (the default)Default (CALCTASKDIM) Specify the number of sparse dimensions included in the identification of tasks for parallel calculation

5. Logging

(MSG) Specify the level of messaging you want returned about calculations. (This option enables simulated calculations.)Default (NOTICE) Specify the intervals to receive completion notices about the progress of the calculationNo changes (Use default)