Instance ManagementData Structure

Data Structure Definition

Configure data structure for entities.

Overview

The Data Structure Definition screen allows you to view the list of Entities uploaded to Fynapse and delete individual Entites without the need to re-upload the Configuration Data JSON file.

For more details on the Data Structure, refer to Data Structure.

General Information

Uploading Data Structure Definition

Data Structure Definition is uploaded in the Configuration Data JSON file.

For a detailed structure of the JSON snippet, refer to Data Structure Definition section in Configuration Data chapter.

Data Structure Definition Constraints

The maximum numbers of user defined Entities stored in Fynapse in Finance Data Service is 100.

The definitions uploaded in a JSON file have to meet the following prerequisites:

Entity

  • name:
    • Has to be unique.
    • Has to be composed using the following rules: start with letter, which can be followed by alphanumeric characters and an underscore.
    • Has the maximum length of 128 characters.
  • temporalityType - what kind of data are contained in this Entity:
    • Reference - determines that the entity has a reference data type
    • Transaction - determines that the entity has a transactional data type; these are accounting data that cannot be changed
  • description - you can add an optional description
  • type - determines what type of an Entity this is:
    • ProtectedEntity - this is an entity which is created by the system when you define configurations that are necessary for the functioning of the system.
    • DefinedEntity - this is an entity defined by the user, you can create as many or as little defined entities as required by your data architecture.
  • primaryKeyAttributeNames - this is the definition of Attributes which will constitute the Primary Key and allow to identify the record in the system
    The Primary Key has to:
    • Be unique
    • Consist of only mandatory Attributes
    • Consist of a minimum of 1 Attribute
    • Consist of a maximum of 5 Attributes (this requirement is valid for Defined Entities only)
    • Consist only of primitive attributes

When defining an Entity to be used as target for an extract, remember to add extractId to the Primary Key for Transaction type transient Entities to ensure correct deduplication of data. For more details, refer to Flow.

Attribute

An Entity has to have at least one Attribute.

Defined Entities can have up to 100 attributes (including Inline Entities).

  • name - unique name:
    • Has to be unique.
    • Has to be composed using the following rules: start with letter, which can be followed by alphanumeric characters and an underscore.
    • Has the maximum length of 128 characters.
  • label:
    • Has to be unique
    • Has the maximum length of 128 characters
    • No constraints on syntax
  • mandatory - determines if an attribute is mandatory:
    • true
    • false
  • type - determines whether this is a Primitive or a Complex Attribute:
    • Primitive attributes:
      • UUID

      Please note that the UUID inputs are not generated automatically. You need to generate them either via a third party generator or in your upstream system and include them in the ingest file with the rest of the input data.

      • BOOLEAN
      • TIMESTAMP - the format used in Fynapse is: yyyy-mm-dd HH:mm:ss. This format is hardcoded and cannot be changed.
      • DATE - the date format Fynapse is: yyyy-mm-dd. This format is hardcoded and cannot be changed.
      • TEXT
      • INT
      • DECIMAL - the decimal attribute operates with the following parameters: scale 18 digits and precision 3 digits. This format is hardcoded and cannot be changed.
      • HIGH-PRECISION DECIMAL
    • Complex attributes:
      • Inline Entity - this is an entity attribute type, i.e. a child entity nested within another entity.
      • List - this is an attribute type which can store an ordered collection of data, primitive or complex, e.g. Inline Entities. The data contained within the List will be ordered in accordance with the order they were supplied to Fynapse. An example of this is a ‘person’ Entity with list of ‘children’, ordered from youngest to oldest.
        A special example of this are Protected entities Journal and Journal Line, with Journal Entity containing a list of Journal Line Entities. Their order is determined by Fynapse.

Please note:

  • InLine type complex attribute can only be defined as a nested attribute of a List type attribute; you cannot define InLine type attribute as a standalone attribute
  • It is not possible to define a List type attribute as nested attribute of another List type attribute

Effective From

The Effective From date is a technical field that is mapped do a dateField defined in a Reference Entity.

If you don’t define a dateField in your Reference Entity or the dateField attribute is left empty in your ingestion file, a default Effective From date will be assigned by the system. This means that the Primary Key will be the only identifier of reference data and the newest version of the data, as identified off of the Primary Key, will be used for enrichment.

If you decide to populate the dateField, then when there are multiple versions of reference data the data with Effective From date effective at the time of the Posting Date of an ingested transaction event will be used for enrichment for this transaction.

For Defined Entities, Effective From date is mapped to the Systemic Field Date Type:

  • Core Date for Journal Line Definition
  • Effective Date for Business Event Definition
    For Business Event Definition this is optional. If you don’t configure the Effective Date field, the Effective From date will by default use the current System Date during enrichment.

For Transaction type Reference Data Entities, the dateField works just like Core Date for Journal Line Definition and Effective Date for Business Event Definition, i.e. it is mapped to the Effective From date technical field and used during enrichment to add correct Reference Data to the ingested Transaction Event. If no dateField is configured for a Transaction type Reference Data Entity, the Reference Data are added based off the current system date.

1{
2  "name": "EntityWithDateField",
3  "description": "Reference Entity with Effective From",
4  "type": "DefinedEntity",
5  "temporalityType": "Reference",
6  "dateField": "effectiveDate",
7  "primaryKeyAttributeNames": [
8    "CompanyId"
9  ],
10  "attributes": [
11    {
12      "type": {
13        "typeName": "PrimitiveType",
14        "primitive": "TEXT"
15      },
16      "name": "CompanyId",
17      "label": "Company ID",
18      "mandatory": true
19    },
20    {
21      "type": {
22        "typeName": "PrimitiveType",
23        "primitive": "DATE"
24      },
25      "name": "effectiveDate",
26      "label": "Effective Date",
27      "mandatory": true
28    },
29  ]
30}

Data Retention Policy

The "retentionDays": <integer> parameter for Entities with "temporalityType": "Reference"

This parameter can be set for Reference Entities populated by the extraction process and used as lookups during Flow processing.

Since such data may be regenerated each time the process runs, periodically purging outdated records is recommended to prevent excessive storage consumption. When a retention policy is defined, records will be automatically deleted after the specified number of days from their creation date.

1{
2        "namespace": "fynapse",
3        "name": "ReferenceEntity",
4        "temporalityType": "Reference",
5        "description": "Reference Entity",
6        "type": "DefinedEntity",
7        "retentionDays": 7,
8        "primaryKeyAttributeNames": [
9          "id"
10        ],
11        "attributes": [
12          {
13            "type": {
14              "typeName": "PrimitiveType",
15              "primitive": "TEXT"
16            },
17            "name": "id",
18            "label": "ID",
19            "mandatory": true,
20            "source": "input"
21          },
22          {
23            "type": {
24              "typeName": "PrimitiveType",
25              "primitive": "TEXT"
26            },
27            "name": "name",
28            "label": "Name",
29            "mandatory": true,
30            "source": "input"
31          }
32        ]
33      }

Validations

Validations - you can define your own validations for Business Events
For more details, refer to Validations.

Examples of Attribute Definitions:

Primitive Attributes

1{
2"name": "company",
3"label": "Company",
4"mandatory": true,
5"type": {
6"typeName": "PrimitiveType",
7"primitive": "TEXT"
8    } 
9}
1{
2"name": "glAccount",
3"label": "GL Account",
4"mandatory": false,
5"type": {
6"typeName": "PrimitiveType",
7"primitive": "INT"
8    }
9}
1{
2"name": "timeOfAdmission",
3"label": "A timestamp of the record's admission to the organization",
4"mandatory": true,
5"type": {
6"typeName": "PrimitiveType", 
7"primitive": "TIMESTAMP"
8    }
9}

Complex Attributes

1{
2"name": "personal",
3"label": "Personal data (names, etc.)",
4"mandatory": true,
5"type": {
6    "typeName": "InlineEntityType",
7    "definition": {
8        "name": "PersonalData",
9        "description": "A personal data record",
10        "type": "DefinedEntity",
11        "primaryKeyAttributeNames": [
12        "id"
13        ],
14        "attributes": [
15        {
16        "name": "id",
17        "label": "Record ID",
18        "mandatory": true,
19        "type": {
20        "typeName": "PrimitiveType",
21        "primitive": "UUID"
22        }
23        },
24        {
25        "name": "familyName",
26        "label": "Family name",
27        "mandatory": true,
28        "type": {
29        "typeName": "PrimitiveType",
30        "primitive": "TEXT"
31        }     
32        },
33        {
34        "name": "firstName",
35        "label": "First name",
36        "mandatory": true,
37        "type": {
38        "typeName": "PrimitiveType",
39        "primitive": "TEXT"
40        }        
41        },
42        {
43        "name": "middleNames",
44        "label": "Middle names",
45        "mandatory": false,
46        "type": {
47        "typeName": "ListType",
48        "itemType": {
49            "typeName": "PrimitiveType",
50            "primitive": "TEXT"
51            }
52        }   
53        }
54    ]
55    }
56}         
57}
1{
2"name": "children",    
3"label": "List of children",
4"mandatory": false,    
5"type": {
6    "typeName": "ListType",
7    "itemType": {
8    "typeName": "InlineEntityType",
9    "definition": {
10        "name": "Child",
11        "description": "Record about a child",
12        "type": "DefinedEntity",
13        "primaryKeyAttributeNames": [
14            "childId"
15        ],
16        "attributes": [
17        {
18        "name": "childId",
19        "label": "Child ID",
20        "mandatory": true,
21        "type": {
22            "typeName": "PrimitiveType",
23            "primitive": "UUID"
24            }
25        },
26        {
27        "name": "gender",
28        "label": "Gender",
29        "mandatory": true,
30        "type": {
31            "typeName": "PrimitiveType",
32            "primitive": "TEXT"
33            }
34        },
35        {
36        "name": "personal",
37        "label": "Personal data (names, etc.)",
38        "mandatory": true,
39        "type": {
40            "typeName": "InlineEntityType",
41            "definition": {
42                "name": "PersonalChildData",
43                "description": "A personal data record of a child",
44                "type": "DefinedEntity",
45                "primaryKeyAttributeNames": [
46                    "id"
47                ],
48                "attributes": [
49                {
50                "name": "id",
51                "label": "ID",
52                "mandatory": true,
53                "type": {
54                    "typeName": "PrimitiveType",
55                    "primitive": "UUID"
56                    }
57                },
58                {
59                "name": "familyName",
60                "label": "Family name",
61                "mandatory": true,
62                "type": {
63                    "typeName": "PrimitiveType",
64                    "primitive": "TEXT"
65                    }
66                },
67                {
68                "name": "firstName",
69                "label": "First name",
70                "mandatory": true,
71                "type": {
72                    "typeName": "PrimitiveType",
73                    "primitive": "TEXT"
74                    }
75                },
76                {
77                "name": "middleNames",
78                "label": "Middle names",
79                "mandatory": false,
80                "type": {
81                    "typeName": "ListType",
82                    "itemType": {
83                        "typeName": "PrimitiveType",
84                        "primitive": "TEXT"
85                        }
86                    }
87                }
88                ]
89            }
90            }
91        }
92        ]
93    }
94    }
95}
96}

Data Structure Definition Screen

The Data Structure Definition screen comprises the following sections:

The Data Structure Definition screen comprises of a grid with the following information:

  • Entity name - unique name of the Entity
  • Entity status - status of the Entity
    • Creating - a temporary status displayed in the grid when creating is in progress
    • Created - the Entity has been created
    • Error creating - an error occurred during creating the Entity
    • Deleting - a temporary status displayed when deleting is in progress
    • Error deleting - an error occurred during deleting the Entity
  • Type - type of the Entity, can be either Reference or Transactional
  • Stored? - information whether the Entity is an Entity that stores data in the FDS or is a transient Entity used by extracts
  • Added by - username of the user who uploaded the Entity
  • Added on - timestamp of when the Entity was uploaded

The Actions column has the following actions:

  • View entity structure - redirects you to the details screen of the given Entity
  • Delete entity structure - deletes the selected Entity

Additionally, you can select one or multiple Entities to delete using the checkboxes in the first column of the left. Once selected, the Delete entity button becomes active and you can delete the selected Entities.

Entity Details Screen

The Entity details screen comprises of two sections.

Entity Information

The Entity information section comprises of the following information:

  • Entity name - unique name of the Entity
  • Entity type - type of the Entity, can be either Reference or Transactional
  • Store data - information whether the Entity is an Entity that stores data in the FDS or is a transient Entity used by extracts

Field information

The Field information section comprises of a grid with the following information:

  • Id - ordinal number of item in the grid
  • Primary key - information whether the field is a Primary Key field
  • Field label - configured label of the field
  • Field type - data type of the field
  • Mandatory? - information whether the field is mandatory; additionally if a field is a Primary Key field or an Effective Date field, there will be information, PK or ED, in brackets

Tutorials

Currently, you cannot edit an Entity directly from UI.

  1. Go to System Configurations > Configuration Data.
  2. Upload a new Configuration Data JSON file containing the modified Entity using the Upload button.
  3. Go to System Configurations > Data Structure > Data Structure Definition. Click the Refresh button to see the new Entity in the grid.
  1. Go to System Configurations > Data Structure > Data Structure Definition.
  2. In the grid, click the row containing an Entity you want to delete.

    Note that deleting an Entity cannot be reverted.

  3. Click the Delete button.
  4. Confirm your action. The selected Entity will be deleted using Schema Repository from the database and as a result from the grid as well.
  5. Click the Refresh button to see the results of deletion.
  1. Go to System Configurations > Data Structure > Data Structure Definition.

Note that deleting an Entity cannot be reverted.

  1. Click the Delete all button.
  2. Confirm your action. All Entities will be deleted using Schema Repository from the database and as a result from the grid as well.
  3. Click the Refresh button to see the results of deletion.