Comment ajouter des entités personnalisées ?

10 min

Cette page explique comment ajouter des entités personnalisées à un projet en utilisant l'OIP (Open Insurance Platform). Il fournit des instructions pour créer un dossier oip/entities dans l'application et y ajouter les entités personnalisées. La configuration de l'OIP doit être mise à jour pour inclure l'entité personnalisée, ainsi que ses gestionnaires et son schéma. Le document fournit également des exemples de code pour la création, le chargement et la sauvegarde d'entités personnalisées. Il suggère de séparer les getters et les setters dans des fichiers distincts pour une meilleure organisation. Enfin, il montre comment utiliser les entités personnalisées dans le projet.

Introduction

Il est possible d'étendre les entités de l'OIP en ajoutant des entités personnalisées.

Par convention, les entités personnalisées se placent dans le dossier oip/entities.

OIP configuration

La déclaration des entités personnalisées dans la configuration de l'OIP est réalisée via la propriété entities.

L'exemple ci-dessous déclare une nouvelle entité tableau nommée CustomEntity.

module.exports = {
  [...],
  entities: {
    customEntity: {
      entity: customEntity,
      actions: {
        loadHandler: customEntityLoadHandler,
        saveHandler: customEntitySaveHandler
      },
      multiple: {
        name: "customEntities"
      },
      parents: ['project', 'customer'],
      schema: {
          myCustomProperty1: { type: String },
          myCustomProperty2: { type: Number }
      }
    }
  }
}

A partir de la version 2.5.0, des handlers par défaut (create, delete, load et save) peuvent être automatiquement générés.

Deux utilisations sont alors possibles :

Les deux propriétés entity et action sont omises : des handlers par défaut sont générés.

Les deux propriétés entity et action sont définies : seuls ces handlers existent.

La convention est de préfixer le nom de l'entité par custom. L'objectif est d'éviter de possibles conflits lors des migrations.

Options

La propriété schema est un objet qui définit la structure de données de l'entité personnalisée. Dans l'exemple, l'entité CustomEntity dispose de deux propriétés : myCustomProperty1::String et myCustomProperty2::Number.

La propriété parents est un array/tableau qui définit à quelles entités est rattachée l'entité personnalisée. Dans l'exemple, l'entité CustomEntity est rattachée aux entités Project et Customer.

Les propriétés entity et actions permettent de définir les handlers de l'entité personnalisée. Un exemple détaillée est disponible ci-dessous.

La propriété multiple est optionnelle. Elle permet de définir que l'entité personnalisée est de type array/tableau. Le champ name est quant à lui obligatoire. Il définit le nom de la propriété de type entité personnalisée dans les entités parentes. Dans l'exemple, les entités Project et Customer auront une propriété nommée customEntities::CustomEntity[].

Les handlers sont à adapter selon le type de l'entité.

Handlers

Entité simple

import { assoc } from 'ramda';

const CustomEntity = () => {
  let handlers = {};

  const setLoadHandler = (loadHandler) => {
    handlers = assoc('load', loadHandler)(handlers);
  };

  const setSaveHandler = (saveHandler) => {
    handlers = assoc('save', saveHandler)(handlers);
  };

  const get = (parentEntity) => {
    return handlers.load(parentEntity);
  };

  const save = (parentEntity, customEntity) => {
    return handlers.save(parentEntity, customEntity);
  };

  return {
    get,
    save,
    setLoadHandler,
    setSaveHandler
  };
};

export default CustomEntity;

Entité tableau

import { assoc } from 'ramda';

const CustomEntity = () => {
  let handlers = {};

  const setCreateHandler = (createHandler) => {
    handlers = assoc('create', createHandler)(handlers);
  };

  const setLoadHandler = (loadHandler) => {
    handlers = assoc('load', loadHandler)(handlers);
  };

  const setSaveHandler = (saveHandler) => {
    handlers = assoc('save', saveHandler)(handlers);
  };

  const create = async () => {
    return handlers.create();
  };

  const get = async (parentEntity, id) => {
    return handlers.load(parentEntity).get(id);
  };

  const findAll = async (parentEntity, filters) => {
    return handlers.load(parentEntity).find(filters);
  };

  const save = async (parentEntity, customEntity) => {
    return handlers.save(parentEntity, customEntity);
  };

  return {
    create,
    findAll,
    get,
    save,
    setCreateHandler,
    setLoadHandler,
    setSaveHandler
  };
};

export default CustomEntity;

Accesseurs

La propriété generateAccessors dans la configuration de l'OIP indique si les accesseurs doivent être automatiquement générés ou non. La valeur par défaut est true.

module.exports = {
  [...],
  entities: {
    customEntity: {
      generateAccessors: false
    }
  }
}

Dans la cas où les accesseurs sont générés, ils sont accessibles en important l'objet CustomProperties depuis le module @fasstech/oip-core/entities.

Dans le cas où les accesseurs ne sont pas générés, la convention est de les définir dans des fichiers séparés. Ci-dessous un exemple.

import { prop, defaultTo } from 'ramda';

export const getCustomProperty1 = (customEntity) => {
  return prop('customProperty1', customEntity);
};

export const getCustomProperty2 = (customEntity) => {
  return defaultTo(0, prop('customProperty2', customEntity));
};

Utilisation

Les entités personnalisées s'utilisent de la même manière que les entités natives de l'OIP.

Ci-dessous un exemple d'une entité simple nommée CustomEntity :

import { Entities } from '@fasstech/oip-core';
import { CustomProperties } from '@fasstech/oip-core/Entities';

const { 
  getCustomEntityCustomProperty1, 
  setCustomEntityCustomProperty1
} = CustomProperties;

let projectEntity = Entities('Project').create();
const customEntity = Entities('CustomEntity').get(projectEntity);

setCustomEntityCustomProperty1(42, customEntity);
project = await Entities('CustomEntity').save(project, customEntity);
await Entities('Project').save(ProjectEntity);

const customEntityFromProject = await Entities('CustomEntity').get(project);
getCustomEntityCustomProperty1(customEntityFromProject); // 42

CustomProperties ne peut être utilisé qu'après l'initialisation de l'OIP Core.