---
title: Comment ajouter des entités personnalisées ?
slug: oip-next/lqc60cd82q9u90phs6vg
description: Learn how to easily add custom entities to your project using the Open Insurance Platform (OIP) with this comprehensive document. Follow step-by-step instructions for creating a designated folder, updating the OIP configuration, and incorporating handlers
icon: {"lucideIcon":"📘"}
createdAt: 2023-05-26T13:57:06.000Z
---

*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&#x20;*`oip/entities`*&#x20;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`.

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

:::hint{type="warning"}
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.
:::

:::hint{type="info"}
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[]`.

:::hint{type="danger"}
Les *handlers* sont à adapter selon le type de l'entité.
:::

## Handlers

### Entité simple

:::CodeblockTabs
customEntity.mjs

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

```

saveHandler.mjs

```javascript
import { assoc } from 'ramda';

const saveHandler = (parentEntity, customEntity) => {
  return assoc('customEntity', customEntity, parentEntity);
};

export default saveHandler;

```

loadHandler.mjs

```javascript
import { prop } from 'ramda';

const loadHandler = (parentEntity) => {
  return assocType('customEntity', prop('customEntity', parentEntity));
};

export default loadHandler;
```
:::

### Entité tableau

:::CodeblockTabs
customEntity.mjs

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

saveHandler.mjs

```javascript
import { any, assoc, map, append, complement, compose, eqProps, has, ifElse, lensProp, mergeLeft, over, when } from 'ramda';

const saveHandler = (parentEntity, customEntity) => {
  return compose(
    over(
      lensProp('customEntities'),
      ifElse(
        any(eqProps('id', customEntity)),
        map(
          when(eqProps('id', customEntity), mergeLeft(customEntity))
        ),
        append(customEntity)
      )
    ),
    when(complement(has('customEntities')), assoc('customEntities', []))
  )(parentEntity);
};

export default saveHandler;
```

loadHandler.mjs

```javascript
import { filter, map, isNil, find as rfind, propOr, propEq, compose, ifElse, not, whereEq, identity, __ } from 'ramda';
import {assocType } from '@fasstech/oip-core/entities/helpers';

const loadHandler = (parentEntity) => {
  const customEntities = propOr([], 'customEntities')(parentEntity);

  const get = (id) => {
    let customEntity;
    if (!isNil(id)) customEntity = rfind(propEq('id', id), customEntities);
    if (isNil(customEntity)) return null;
    return assocType('customEntity', customEntity);
  };

  const find = (filters) => {
    return compose(
      map(assocType('customEntity', __)),
      ifElse(
        () => not(isNil(filters)),
        filter(whereEq(filters)),
        identity
      )
    )(customEntities);
  };

  return {
    get,
    find
  };
};

export default loadHandler;
```

createHandler.mjs

```javascript
import { assocType } from '@fasstech/oip-core/entities/helpers';
import { v4 as uuidv4 } from 'uuid';

const createHandler = () => {
  return assocType('customMultiEntity', { id: uuidv4() });
};

export default createHandler;

```
:::

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

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

:::CodeblockTabs
customEntityGetters.mjs

```javascript
import { prop, defaultTo } from 'ramda';

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

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

```

customEntitySetters.mjs

```javascript
import { assoc } from 'ramda';

export const setCustomProperty1 = (value, customEntity) => {
  return assoc('customProperty1', value, customEntity);
};

export const setCustomProperty2 = (value, customEntity) => {
  return assoc('customProperty2', value, customEntity);
};
```

customEntityHelpers.mjs

```javascript
export * from './customEntityGetters';
export * from './customEntitySetters';
```
:::

## Utilisation

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

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

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

```

:::hint{type="warning"}
`CustomProperties` ne peut être utilisé qu'après l'initialisation de l'OIP Core.
:::
