Configuration

11 min

L'OIP Core se paramètre via un fichier de configuration.

Le fichier de configuration est un fichier JavaScript qui doit nécessairement avoir une instruction export default.

Configuration générale

debug :

type : boolean

description : Active ou désactive le mode debug

optionnel ; valeur par défaut : false

database :

type : object

description : Regroupe la configuration de la base de données

database.url :

type : string

description : Spécifie l'URL de la base de données

rabbitMQ :

type : object

description : Regroupe la configuration de RabbitMQ

optionnel

rabbitMQ.name :

type : string

description : Spécifie le nom de la queue

tasks :

type : Record

description : Regroupe la configuration de chaque tâche

tasks.[/^[a-z][a-zA-Z0-9]*$/] :

type : function | object

description : Spécifie la fonction associée à une tâche ; si la tâche doit être répétée, une propriété cron peut être transmise en plus de la propriété callback.

transitions :

type : object

description : Regroupe la configuration des transitions

transitions.useHistory :

type : 'after' | 'before'

description : Spécifie si l'historique des transitions est utilisé pour les transitions previous. Par défaut, il n'est pas utilisé ; les transitions previous sont résolues par le TransitionManager à l'aide des informations définies dans le workflow. La valeur after signifie que l'historique des transitions est utilisé si le TransitionManager n'a pas pu résoudre la transition previous. La valeur before signifie que l'historique des transitions est utilisé en lieu et place du TransitionManager.

entities :

type : Record

description : Regroupe la configuration de chaque entité

entities.[/^[A-Z][a-zA-Z0-9]*$/] :

type : object

description : (voir section ci-dessous)

Exemple

export default {
  debug: true,
  database: {
    url: process.env.OIP_DB_URL
  },
  rabbitMQ: {
    name: process.env.OIP_MQ_QUEUE_NAME
  },
  tasks: {
    task1: {
      callback: () => {},
      cron: '5 0 * 8 *'
    },
    task2: async ({ metadata, taskHandler }) => {},
    task3: {
      callback: () => {}
    }
  }
};

Configuration d'une entité

entities est un objet permettant de modifier des entitiés natives de l'OIP-core ou d'ajouter des entités personnalisées. Cet objet est optionnel.

Les éléments configurables sont :

generateAccessors :

type : boolean

description : Génère ou non les accesseurs des propriétés de l'entité

optionnel ; valeur par défaut : true

properties :

type : Record

description : Regroupe la configuration de chaque propriété de l'entité

optionnel

properties.[/^[a-zA-Z][a-zA-Z0-9]*$/] :

type : object

description : (voir sous-section ci-dessous)

relations :

type : Record

description : (voir sous-section ci-dessous)

Le nom d'une entité doit commencer par une majuscule (/^[A-Z][a-zA-Z0-9]*$/).

Propriété

properties est un objet permettant d'ajouter ou modifier des propriétés à une entité. Cet objet est optionnel.

Le nom d'une propriété doit commencer par une lettre (/^[a-zA-Z][a-zA-Z0-9]*$/).

Les éléments configurables sont :

type :

type : boolean | date | number | object | string | boolean[] | date[] | number[] | object[]| string[] | virtual

description : Spécifie le type de la propriété

default :

type : même type que la propriété type

description : Spécifie la valeur par défaut à utiliser

optionnel

enum :

type : T[], T est défini par le type de la propriété : boolean | date | number | object | string

description : Spécifie les valeurs possibles d'une propriété

optionnel ; ne peut être combiné avec validator

readOnly :

type : boolean

description : Spécifie si la propriété est en lecture seule ou non

optionnel ; valeur par défaut : false

validator :

type : object

description : (voir sous-section ci-dessous)

optionnel ; ne peut être combiné avec enum

get :

type : Function

description : Spécifie la fonction à exécuter pour calculer la valeur de la propriété virtuelle

obligatoire si et seulement si le type est virtual

anon :

type : object

description : Spécifie le type d'anonymisation à appliquer.

anon.algorithm :

type : 'dataMasking' | 'pseudonymization'

description : Spécifie l'algorithme à utiliser pour l'anonymisation.

anon.effectPeriod :

type : number

description : Spécifie le nombre de mois au bout duquel appliquer l'anonymisation.

Le type d'une propriété d'une entité native ne peut pas être modifié.

Une propriété dont le type est virtual est une propriété dont la valeur est donnée par l'exécution d'une fonction (spécifiée par la propriété get).

Déclarer une énumération (enum) sur une propriété native en possédant déjà une ajoute de nouvelles valeurs à celle-ci.

Il est uniquement possible d'ajouter des valeurs à une énumération existante.

La valeur par défaut d'une propriété est utilisée à l'appel de la méthode Entities([...]).save(). Ceci implique que si un projet surcharge le save handler généré pour une entité alors la gestion des valeurs par défaut de cette entité doit être gérée par le projet.

Validateur

Validator est un objet permettant d'ajouter ou de modifier un contrôle sur une propriété d'une entité.

Les éléments configurables sont :

validate :

type : function

description : Fonction de contrôle à appliquer à la propriété. Cette fonction retourne un tuple [boolean, Error[]]. Le premier élément est une valeur booléenne indiquant si la valeur de la propriété respecte le validateur. Le second élément est une liste d'erreurs. Elle est vide quand la valeur de la propriété respecte le validateur (i.e. le premier élément du tuple est true). Elle contient les erreurs levées quand la valeur de la propriété ne respecte pas le validateur (i.e. le premier élément du tuple est false).

L'OIP-core expose un objet Validator pour faciliter la création d'un validateur.

type ValidationFunc = "lowerCase" | "upperCase";
type ValidationRegex = "internationalPhone" | "localPhone" | "mail" | "postal";

export type Validation = (options: {
    exactLength?: number;
    maxLength?: number;
    minLength?: number;
    type?:
      | Function
      | RegExp
      | ValidationFunc
      | ValidationRegex
      | (Function | RegExp | ValidationFunc | ValidationRegex)[];
  }) => {
    validate: <T>(value: T) => [boolean, Error[]];
  };
  
  export const Validator: Validation;

{
  type: 'number',
  validator: Validator({ type: (value) => value > 0 && value <= 100 })
}

Relations

relations permet de spécifier les relations descendantes d'une entité.

Chaque clé de la propriété relations doit être un type d'entité valide (native ou personnalisée).

La valeur associée à chaque clé est un tuple ['multiple' | 'simple', string]. Le premier élément est un litéral indiquant si la relation est de type simple ou multiple. Le second élément indique le nom de la propriété associée à cette relation. Le nom de cette propriété respecte la même convention que le nom des propriétés définis dans l'objet properties (/^[a-zA-Z][a-zA-Z0-9]*$/).

Considérant l'extrait de code ci-dessous, l'entité Contact dispose :

une propriété nommée company de type Company.

une propriété nommée document de type Document[].

{
  Contact: {
    relations: {
      Company: ['simple', 'company'],
      Document: ['multiple', 'documents']
    }
  }
}

A l'exécution, il ne peut exister au plus qu'une relation entre une entité parent et une entité enfant. Si le fichier de configuration en définit une simple et une multiple, la relation simple sera utilisée.

Certaines entités natives entrent dans ce cas de figure. Par exemple, il existe nativement les relations Project => BankAccount et Project => BankAccount[]. Si aucune relation n'est spécifiée dans le fichier de configuration, seule la relation Project => BankAccount sera utilisable.

Exemple

export default {
  entities: {
    Company: {
      properties: {
        ranking: { type: 'number' }
      },
      relations: {
        BankAccount: ['multiple', 'bankAccounts'],
        Custom1: ['simple', 'custom1'],
        Custom3: ['multiple', 'customs3']
      }
    },
    Contact: {
      relations: {
        Company: ['simple', 'company']
      }
    },
    Email: {
      properties: {
        value: { validator: Validator({ type: /@fasst\.io$/ }) }
      }
    },
    Grantee: {
      relations: {
        Custom1: ['multiple', 'customs1'],
        Custom2: ['simple', 'custom2']
      }
    },
    User: {
      properties: {
        birthdate: { type: 'date', readOnly: true },
        login: { validator: Validator({ minLength: 8 }) }
      }
    },
    Custom1: {
      properties: {
        toto: { type: 'number', validator: Validator({ type: (value) => value > 0 && value <= 100 }) },
        titi: { type: 'object' },
        tata: {
          type: 'string[]',
          enum: ['REMINDER1', 'REMINDER2']
        }
      },
      relations: {
        Address: ['simple', 'address'],
        Phone: ['multiple', 'phones'],
        Custom3: ['multiple', 'customs3']
      }
    }
  }
};

Cas particuliers

Entité Project

Deux hooks peuvent être rattachés à la sauvegarde de l'entité Project. Le premier s'exécute avant la sauvegarde de la nouvelle entité Project. Le second s'exécute après la sauvegarde de la nouvelle entité Project.

Ces hooks se déclarent comme suit :

actions.hooks.update :

type : Record<'before' | 'after', Function>

description : Regroupe la configuration de chaque hook

optionnel

const onAfterUpdateProject = async (project) => {};

const onAfterUpdateProject = async (project) => {};

export default {
  entities: {
    Project: {
      actions: {
        hooks: {
          update: {
            before: onBeforeUpdateProject,
            after: onAfterUpdateProject
          }
        }
      }
    }
  }
};

Entités

Le nom des entités personnalisées doit être préfixé par Custom. L'objectif est d'éviter de possibles conflits lors des migrations.