Creating an Entity

This topic describes how to create a new Entity and its specific properties.

 

To create an Entity, click on "+ ENTITY" and fill in all fields as required. Click on SAVE CHANGES when done.  To know more about Entity properties, see next paragraph.

The Entity creation panel requires a "SAVE CHANGES" confirmation before allowing access to the CONTENT and ANALYSIS tabs.

The number of Entities in each Data model should not exceed one thousand.

 

Entity properties

The following properties are available when creating a new Entity:

  • Name (required). The name of the Entity, as it will be displayed across the application. This field accepts any character.

    When a new Entity is created, Board assigns an unique internal identifier (UID) for that Entity. The UID is then used to refer to the Entity across Board: reports, Procedures, Data readers, and other objects will all refer to a single Entity using its UID. Consequently, changing the Entity name will not affect existing Capsules (and related reports and Procedures) or other Data model objects in any way.

  • Group (required). Choose a Group for the Entity or create a new one by entering a name for it. Groups are useful for locating a specific Entity or understanding the purpose of all Entities listed in the Entities table and in other sections of Board. 

    Groups are not part of the multidimensional Data model (i.e. they cannot be used in reports or Procedures): the only purpose of groups is to improve reading and searching through the list of Entities.

  • Code width. The maximum number of characters that the member code can contain. The code is a unique value that identifies every single member of the Entity. Leave it to 0 to have the system accept any number of characters for the code,

    It is not strictly required to specify the code width. When the Entity members are loaded (manually or via a Data Reader), the system will set the most appropriate value accordingly.
    The Code width does not represent a limit to the size of the incoming data: it can be changed dynamically as you load the Entity members, manually or via a Data Reader. Any loaded item exceeding the maximum Code width will not be discarded nor truncated, as Board will automatically increase the Code width value by multiples of 10.
    If members are loaded via a Data Reader with the "fixed width" option turned on, changing the code width will cause the Data Reader to fail.

  • Desc width. The maximum number of characters that can be used for the description of each member. You can set this field to zero if no description for members is needed or to have the system accept any number of characters for the description.

    It is not strictly required to specify the description width. When the Entity members are loaded (manually or via a Data Reader), the system will set the most appropriate value accordingly.
    The Desc width does not represent a limit to the size of the incoming data: it can be changed dynamically as you load the Entity members, manually or via a Data Reader. Any loaded item exceeding the maximum Desc width will not be discarded nor truncated, as Board will automatically increase the Desc width value by multiples of 10.

  • Max Item number. The maximum number of members that the Entity can hold. It is important to set a value that would suit the potential rate of growth of new members over the life of the application, but this value shouldn't be unrealistically high, as it is used for allocating memory in the application and for optimizing the physical data structure of Entities and Cubes.

    - When creating a new Entity, it is not required to define the Max Item number. Once the Entity is created, you can populate it via a Data reader and then set a Max Item number according to the actual number of members the Entity holds. When setting this number, attention should be given to not only the current number of items but the potential rate of growth over the life of the application
    - The Max item number can also be left to "Auto", in that case Board will automatically define its value automatically based on an internal optimization algorithm
    - When an Entity is used in a cube structure, a Max Item number is automatically calculated for that entity in that structure, using an internal algorithm that optimizes compression and performance. - The calculation of the Max Item number occurs only after an Entity has been populated with members and at the first load of data in the Cube in whose structure the Entity is present (i.e. the Max Item number is not defined as long as the Cube is empty)
    - If an Entity is used in a Cube version, the Cube cannot be populated if the Max item number is zero, a non-zero value must always be entered.
    - The ratio between the number of members of an Entity and the Max Item number is the Saturation % value shown in the Entities page: this value should always be less than 100%.
    - If a Data Reader exceeds the Max Item number when loading Entity members, a warning message appears and the Data reader will discard all excess members from that point on. If the Data reader log has been enabled from the Data reader table, a log file of the rejected records for each Data reader will be created. Lear more about Data reader log in this page.

  • Sort by. Default sort option. Select one of the four available options:
    • None: displays Entity members following the order in which they are created
    • Code: sorts Entity members according to the code field, in ascending/alphabetical order
    • Desc: sorts Entity members according to the description field, in ascending/alphabetical order
    • Custom: applies a custom sort to Entity members as explained below:
      • Manually from the "CONTENT" tab. Drag and drop the element to the desired position in the list: for example you can move the first member in position 3 by dragging it from the top to the third position. Use the drag and drop handle (six dot icon) on the left to drag a member. You can also set the order of each member by double-clicking in the order field and entering the desired position (number): for example, if you want to move the first member to the third position, you can enter "3" in the order field before the first element.

      New members added or any members not included in the file are placed at the end of the member list following the order in which they were originally created.

      • Using a Data reader. When at least one Entity sort option is set as "Custom", then a "Sorting entity members" checkbox will appear when creating new Data readers: once the option is enabled, only the Entity fields can be used in the Data reader as it will only be able to set the order of members. The order in the file/query read by the Data reader will be used in the custom sort. All members not read by the sorting Data reader are placed at the end of the member list following the order in which they were originally created. New members added (manually or via the Data reader) to a custom sorted Entity are also placed at the end of the member list, in order of creation.
  • Display. The default display behaviour of the members, either Code, Description, or both. Select one of the three available options:
    • Desc: displays the member's description
    • Code: displays the member 's code
    • Both: displays both code and description for each member
  • User view. Controls the order and groupings of Entities in the Capsule environment, for example in the Select window and in the Layout configuration window
  • Allow user in view (enabled by default). Clear the checkbox to hide the Entity in the Capsule environment, both in Design and in Play mode
  • Roll-up Entity. This flag determines whether the Entity will behave as a Roll-up Entity, automatically determining an aggregation hierarchy based on the codes of its members: enable this option to have Board automatically calculate totals and subtotals based on  the codes of the members. This feature is still available for back-compatibility reasons, however we strongly recommend that you use the Unbalanced Hierarchy feature instead. Refer to this page on the previous documentation for more details
  • Unbalanced hierarchy. This flag determines whether the Entity will include an Unbalanced Hierarchy. This type of Entity supports the definition of parent-child relations between its members, with on the fly data aggregation along the hierarchy. These structures are typically used in financial reporting or in organization structures and are common to many other business models. See Unbalanced Hierarchies for more details

    This type of Entity is similar to the Roll-up Entity, but without the requirement that the member codes need to be hierarchical along the roll-up. Roll-up Entities continue to be supported for back-compatibility but Unbalanced Hierarchies Entities are more powerful and their use is highly recommended.

 

 

Adding members to an Entity

You can add new members to an Entity in two ways:

  1. Manually, from the "CONTENT" tab. This process is useful for adding single members to an Entity or for populating small Entities which do not exist in your source data systems.
    To manually add new members to an Entity, proceed as follows:
    1. Select the desired Entity
    2. Click on "CONTENT"
    3. Click on "ADD NEW MEMBER"
    4. Enter the code and description of the new member
    5. Click on "ADD NEW MEMBER". Repeat the process from the previous step to add as many members as needed
    6. Click on "SAVE ADDED MEMBERS"

    If you're creating a new Entity, the "CONTENT" tab becomes available only after the first "SAVE CHANGES" confirmation.
    From the "ADD NEW MEMBER" section you can easily add new members in bulk from a spreadsheet by copying and pasting the columns that you wish to use. You should only copy two columns of data, with the first column being the code and the second column being the description. Do not include column headers in your selection.
    You must also bear in mind the Code and Description widths that are set for the Entity, as well as the Max item number, as these parameters cannot be exceeded. If any of the parameters are exceeded, no new members will be added until the incorrect members are removed.

  2. Via a Data reader. The Data reader is a Board tool which allows you to import data from text files, ODBC, OLE DB- or OLAP connections into the Board database. After mapping the source data to an Entity, running the Data reader will load members into it following the saved configuration. This method is the most common and appropriate for populating large Entities. See Data reader basic concepts for more details