# Best practices for creating a data model ## Introduction to data modeling When creating a data model for an application in Eximee, you should follow principles that make system maintenance easier and ensure data consistency across the entire organization. A well-designed model is the foundation of efficient information flow between the user interface and the process engine. ### Key naming standards An effective data model should be intuitive. When designing keys, follow the technical standards below: | Aspect | Rule | Example (Good) | Example (Bad) | | -------------------- | -------------------------------------------------------------------------- | ----------------------- | ------------------ | | **Format** | Use camelCase, one language (English), no Polish characters and no spaces. | `startDateOfEmployment` | `Data_Rozpoczecia` | | **Logic (Boolean)** | Start with `is` or `has`. | `isPoliticallyExposed` | `czy_pep` | | **The "of" pattern** | Use the "of" construction for clarity of context. | `countryOfResidence` | `residenceCountry` | | **Identifiers** | Avoid generic `id`. Add business context. | `customerId` | `id` | ### Principles of structure and development design The following rules define the approach to the model architecture and its evolution over time: | Rule | Description and business justification | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Hierarchy and structure** | The tree structure must reflect the natural hierarchy of business data. Group fields into semantic objects (e.g. `customerData.name` or `registerAddress`). This makes it easier to map entire structures to services and increases model readability. | | **Data vs Calculations** | Store source data (e.g. dates), not variable or calculable values (e.g. age). If a calculation is necessary, add it as a neighboring field dynamically supplied by the provider. | | **Avoiding duplication** | Before adding a field, check whether similar information already exists. Different objects (e.g. addresses) should share the same internal key names (e.g. `streetName`), to maintain technological consistency. | | **YAGNI strategy** | Do not model structure "just in case." Add only those fields that are actually required at the current stage of the process. An overly large model makes analysis more difficult. | | **Reusability** | When designing a new structure, treat existing models in other applications as a reference point. Maintain consistent naming for the same concepts across the entire organization. | | **Requirements update** | Whenever the BPMN process is modified (e.g. adding or removing a step) or the form is changed (e.g. adding a new data section), perform an impact analysis on the data model. Lack of synchronization is the most common cause of errors. | ### Documentation and technical parameters The data model in Eximee is not only a structure, but also metadata that facilitates integration and maintenance: | Parameter | Rule and best practices | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Attribute `docs`** | Document the business meaning and the context of keys and providers. In the application documentation, use full dot notation (e.g. `customerData.address.street`). | | **Value `defaultValue`** | Allows assigning a default value (e.g. the `false`flag), when sources do not provide data. This prevents errors of the `null pointer`. | | **Multiplicity** | Parameters must precisely reflect the business logic. For required fields `Min=1`. For lists of unlimited length, use `Max=null`. | | **Source logic** | Document the order and mappings of providers. Remember - the first source that returns a value other than `null`, has priority. | ## Common mistakes and how to avoid them Below is an overview of the most common mistakes made when creating a data model and using it - their causes, effects, and how to avoid them. | Error | Cause | Effect | Solution | | ------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No link to the form | Forgot to set the "Data model key" in the component. | The data is not saved (the field is empty after refresh). | Set the key in the component properties by entering the exact field key from the data model. After saving the form, the component will save its value to that field, and on startup it will retrieve the existing value from the model. | | Typos and name mismatches | Manually typing names in the "Data model key" option. | The component will not connect to the correct field in the data model - the value will not be saved to the model. | "Use the copy icon next to the key in the data model. | | Incorrect use of arrays | Omitting index notation (e.g. `products.price`). | The syntax without \[] or an index is incorrect and will cause an error preventing the form from running. | In repeating sections, use the notation `products[].price`. | | Invisible data model | No artifact in the application. | The model has not been initialized. | Use the "Initialize data model" button in the application's "Data model" tab. |