---
title: Configurer les entités
slug: oip-next/v3/configurer-entites
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T12:51:47.000Z
---

# Ajouter des propriétés à une entité native

Une entité est une couche d'abstraction entre le modèle de données et la structuration de la donnée brute. L'OIP Core propose un ensemble d'entités par défaut, appelées entités natives ou *core entities*.

La liste des entités natives est disponible [ici](https://doc.fasst.tech/oip-core/PH68-liste).

Une propriété est ajoutée à une entité via le chemin : `entities.ENTITY_NAME.properties.PROPERTY_NAME`.

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

Le type d'une propriété peut être : `boolean | date | number | object | string | boolean[] | date[] | number[] | object[]| string[]`.

```javascript
export default {
  entities: {
    Customer: {
      properties: {
        foo: { type: 'string' }
      }
    }
  }
};
```

***

# Déclarer les propriétés  d'une entité personnalisée

Les entités de l'OIP Core peuvent être étendues. Ces entités sont appelées entités personnalisées ou *custom entities*. Une entité personnalisée prend en charge des données spécifiques à un projet.

Une entité personnalisée est ajoutée via le chemin : `entities.ENTITY_NAME`.

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

La convention est de préfixer le nom d'une entité personnalisée par `Custom`.

```javascript
export default {
  entities: {
    Custom1: {
      properties: {
        foo: { type: 'string' }
      }
    }
  }
};
```

***

# Déclarer une propriété en lecture seule

Une propriété est déclarée en lecture seule via le chemin : `entities.ENTITY_NAME.properties.PROPERTY_NAME.readonly`.

```javascript
export default {
  entities: {
    User: {
      properties: {
        birthdate: { type: 'date', readonly: true }
      }
    }
  }
};
```

***

# Déclarer une propriété virtuelle

Une propriété virtuelle est une propriété dont la valeur est donnée par l'exécution d'une fonction.

Pour déclarer une propriété virtuelle, il faut :

- Utiliser `virtual` pour son type ;
- Déclarer une fonction `get`.

```javascript
export default {
  entities: {
    User: {
      properties: {
        name: { type: 'virtual', get: (a) => `${getUserFirstName(a)} ${getUserLastName(a)}` }
      }
    }
  }
}
```

***

# Ajouter une énumération à une propriété

Une énumération est ajoutée à une propriété via le chemin : `entities.ENTITY_NAME.properties.PROPERTY_NAME.enum`.

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.

```javascript
export default {
  entities: {
    Company: {
      properties: {
        type: { enum: ['NEW_TYPE'] }
      }
    },
    Custom1: {
      properties: {
        foo: {
          type: 'string',
          enum: ['REMINDER1', 'REMINDER2']
        }
      }
    }
  }
};
```

```javascript
let company = Entities('Company').create();

// Native value
setCompanyType(CompanyTypeEnum.HEAD_OFFICE, company);

// Custom value declared in OIP configuration
setCompanyType('NEW_TYPE', company);
```

***

# Ajouter une valeur par défaut à une propriété

Une valeur par défaut est ajoutée à une propriété via le chemin : `entities.ENTITY_NAME.properties.PROPERTY_NAME.default`.

Le type de la valeur par défaut doit correspondre au type de la propriété.

```javascript
export default {
  entities: {
    Email: {
      value: { default: 'foo' }
    }
  }
};
```

***

# Ajouter un validateur à une propriété

Un validateur est ajouté à une propriété via le chemin : `entities.ENTITY_NAME.properties.PROPERTY_NAME.validator`.

```javascript
import { Validator } from '@fasstech/oip-core/entities/helpers/validator';

export default {
  entities: {
    Company: {
      ranking: { validator: Validator({ type: (value) => value > 0 }) }
    },
    Email: {
      value: { validator: Validator({ type: /@foo.io$/ }) }
    }
  }
};
```

***

# Ajouter une relation

Une relation est ajoutée via le chemin : `entities.ENTITY_NAME.relations.RELATION`.

La clé d'une relation doit être un type d'entité valide (native ou personnalisée).

La valeur d'une relation 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]*$/`).

```javascript
export default {
  entities: {
    Customer: {
      relations: {
        Company: ['simple', 'company'],
        Document: ['multiple', 'documents']
      }
    }
  }
};
```

***

# Ajouter un hook à la sauvegarde de l'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`.

Un *hook* est ajouté via le chemin : `entities.Project.actions.hooks.update`.

```javascript
const onBeforeUpdateProject = async (project) => {};

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

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

***

# Déclarer une tâche dans votre fichier de configuration

```javascript
export const taskContext = {};

export default {
  tasks: {
    // Tâche synchrone
    task1: () => {        
      taskContext.x += 1;
    },
      
    // Tâche asynchrone
    // avec mise à jour du statut de la tâche
    task2: async ({ metadata, taskHandler }) => {        
      taskContext.msg = `Hello World: ${taskHandler.get().taskName}!`;

      await taskHandler.updateState({ metadata, state: { status: 'ONGOING', statusCode: 42 } });
    }
  }
};
```

***

# Déclarer une tâche récurrente dans votre fichier de configuration

```javascript
export const taskContext = {};

export default {
  tasks: {
    // Tâche récurrente
    // avec une exécution tous les jours à minuit
    task1: {
      callback: async () => {
        taskContext.y += 2;
      },
      cron: '0 0 * * * *'
    }
  }
};
```

Pour déterminer la valeur à donner à la propriété `cron` vous pouvez utiliser [https://crontab.guru/](https://crontab.guru/).
