Basic Configuration

Config folder

Most of the the configuration is managed in the config/ folder provided. In this folder is where the entities, hooks and translation resources are stored and created/updated automatically when queried from the API.

Entities json files

The entities json file can be in either the config/development/entities/active/ or config/production/entities/active/ folder depending on the enviroment.

Structure of an entity:

{
  "object_label": "",
  "object_name": "",
  "datasource": "",
  "layout": "",
  "show_on_menu": true,
  "use_adapter": false,
  "importable": true,
  "read_only": false,
  "audited": true,
  "layout_properties": [],
  "recursive_queries": [],
  "relationships": [
    {
      "name": "",
      "type": "",
      "label": "",
      "layout": "",
      "relation_name": "",
      "relationship_type": "",
      "l_entity": "",
      "r_entity": "",
      "l_key": "",
      "r_key": "",
      "key": "",
      "join_entity": "",
      "join_l_key": null,
      "join_r_key": "",
      "layout_properties": [],
      "fields": []
    },

  ],
  "fields": [
    {
      "type": "",
      "inline_edit": true,
      "reportable": true,
      "searchable": true,
      "importable": false,
      "indexable": false,
      "editable": true,
      "readonly": false,
      "required": true,
      "audited": true,
      "visible": true,
      "unique": false,
      "default_value": "",
      "default_exp": "",
      "comments": "",
      "group": "",
      "label": "",
      "regex": "",
      "name": "",
      "help": "",
      "precision": 0,
      "size": 0,
      "len": 0,
      "options": [],
      "options_exp": "",
      "layout_properties": [{}]
    }
  ]
}

Translation resources

The translation resources used in the Backend API are files managed used i18n called bundles. They are stored on the /config/resources/active/ folder.

Each bundle belongs to a namespace and together they form the name of the bundle, ej: application.web.json. There are currently two namespaces used:

• Application namespace: Used for the global translations of the application. Found as files in the pattern application.*.json
• Entities: Used for the specific translations of the entities created in the application. Found as files in the pattern entities.*.json

Translation Bundle Structure

Translation bundles are JSON files containing localized text and metadata. They follow this structure:

{
  "$meta": {
    "engine": "i18n",
    "format": "json",
    "language": "en",
    "name": "entities.actor",
    "created": "2021-09-01T00:00:00.000Z",
    "modified": "2022-09-01T00:00:00.000Z"
  },

  // Language-specific translations
  "en": {
    // Entity naming translation
    "name": "actor",
    "label": "Actor",

    // Nested structure for field translations
    "fields": {
      "firstName": "First Name",
      "lastName": "Last Name",
      "employmentStatus": "Employment Status",
      "employmentStatus>options": {
        "employed": "Employed",
        "unemployed": "Unemployed",
        "retired": "Retired",
        "student": "Student",
        "other": "Other"
      }
    },

    // Translations for relationships
    "relationships": {
      "episodes": "Relationship between actors and episodes",
      "movies": "Relationship between actors and movies",
      "shows": "Relationship between actors and shows"
    }
  }

  // Other languages would be added here with their translations.
}

About the bundle file:

• Named section $meta: Metadata about the bundle, includes some relevant information like the following:

  • created: The creation timestamp
  • modified: The last modification timestamp
  • format: The format of the bundle (e.g., "json")
  • language: The language code (e.g., "en", "es")
  • engine: The translation engine used (e.g., "i18n")
  • name: The namespace and entity name (e.g., "entities.actor")

• Language-Specific Sections: The keys within the top-level object (excluding $meta) represent language codes. Each language section contains the translations for that language.

• Nested Structures: Complex entities can have nested structures to represent field labels, options for dropdown menus, or other relationships. The example shows how to handle dropdown options using the key>options pattern (e.g., "employmentStatus>options").

Other configuration files

There are other configuration files inside of the config folder, but most of these are generated automatically and need no manual interaction.

• datasources.json: For use with the external datasources plugin. Lists the properties required to create a connection to a external database.
• menu.json: Has information about the current entities.
• versions.json: Has information about the versions currently available.

Enviroment Files (.env)

A default default.development.env env file is provided. The corresponding values should be updated depending if the project is going to run on production or development:

• NODE_ENV: the environment to be run.
• DEV_SIGNATURE_TOKEN: the signature for the jwt token
• CONFIG_DIR: location of config/ folder
• HOST: host name
• PORT: Port number
• (Optional) DB_MAX_CONNECTIONS: limit of database connections
• DB_NAME: database name
• DB_USER: database username
• DB_PASSWORD: database password
• (Optional) DEFAULT_USER_TASK: The default number for the user task