---
title: Configuration
slug: oip-next/v3/core/configuration
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T13:20:44.000Z
---

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](https://www.rabbitmq.com/)
  - 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

```javascript
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` :&#x20;
  - 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&#x20;**`virtual`**&#x20;est une propriété dont la valeur est donnée par l'exécution d'une fonction (spécifiée par la propriété&#x20;**`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&#x20;**`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.

```typescript
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;
```

```javascript
{
  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[]`.

```javascript
{
  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

:::CodeblockTabs
oip.config

```javascript
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

```javascript
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.
