Configuration
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.