---
title: Récupérer une trame projet
slug: oip-next/d75i-envoyer-une-trame
icon: {"lucideIcon":"📘"}
createdAt: 2025-12-01T13:07:46.000Z
---

# Vue d'ensemble

La récupération d'une trame est possible via deux mécanismes :

- automatisé : le service OIP Headless publie une trame lorsqu'un déclencheur est activé ;
- manuel : le service OIP Headless expose une API dédiée.

L'envoi de trames s'effectue dans les deux cas via le protocole AMQP.

# Envoi automatisé

L'envoi automatisé est conditionné à l'activation d'un déclencheur.
Un déclencheur correspond à un changement de valeur d'une propriété d'une entité. Par exemple, la valeur de la propriété `firstName` d'une entité `Grantee` passe de `Foo` à `Bar`.

Les déclencheurs sont gérés par le service OIP Headless.

## Enregistrement d'un déclencheur

Un déclencheur s'enregistre dans la table `settings` de la base de données associée au service OIP Headless.

La commande SQL à exécuter pour l'enregistrement d'un déclencheur est de la forme :

```sql
insert into settings (scope, key, value, application_id) values (100, 1010, '{ "type": "<ENTITY_NAME>", "key": "<PROPERTY_NAME>" }', <APPLICATION_ID>);
```

où :

- `ENTITY_NAME` est le nom d'une entité (colonne `type` de la table `entities_types`) ;
- `PROPERTY_NAME` est le nom d'une propriété de l'entité `ENTITY_NAME` ;
- `APPLICATION_ID` est l'identifiant de votre application (colonne `id` de la table `applications`).

## Exemple

Ci-dessous un exemple de configuration afin d'envoyer une trame au changement de la propriété `status` d'une entité de type `Project`.

```shell
psql -U postgres -d oip_headless << EOF
insert into settings (scope, key, value, application_id) values (100, 1010, '{ "type": "Project", "key": "status" }', (select id from applications where name = 'MyApp'));
EOF
```

:::BlockQuote
Info
Veillez à remplacer `MyApp` par le nom réel de votre OAV.
:::

:::BlockQuote
**Info**
La commande SQL ci-dessous doit être exécutée depuis le container hébergeant la base de données PostgreSQL du service OIP Headless.
:::

# Envoi manuel

La bibliothèque OIP Core exporte une fonction `requestEntitySnapshot` pour forcer l'envoi d'une trame.

La signature de cette fonction est :

```typescript
const requestEntitySnapshot: (
  entity: Entity,
  metadata?: object,
) => Promise<void>;
```

## Exemple

```javascript
import { requestEntitySnapshot } from "@fasstech/oip-core";

// Request a snapshot of the entity tree starting from the `project` entity
await requestEntitySnapshot(project);

// Request a snapshot of the entity tree starting from the `project` entity,
// add `{ foo: "bar" }` as metadata to the published message
await requestEntitySnapshot(project, { foo: "bar" });
```

# Récupération

La récupération des trames est assurée par le code ci-dessous :

```javascript
import { getEnv } from "@fasstech/oip-starter-utils/server";
import { queueService } from "@fasstech/rabbitmq-helper";

// Register a consumer to handle entity messages
queueService.consumeMessage(`${getEnv("OAV_ID")}.entities`, 0, (args) => {
  // ...
});
```

:::BlockQuote
**Info**
Ce code peut être placé à la fin du fichier `server/index.mjs` de votre OAV.
:::

Le type du message envoyé est :

```typescript
{ type: string; data: object; metadata?: object }
```

La trame projet est alors accessible via la propriété `data`.

:::BlockQuote
**Info**
La trame projet suit la structure suivante :
\- chaque sous-entité a pour clé son type (e.g. `Customer`, `Grantee`, etc.) ; aucun traitement n'est réalisé sur cette clé (i.e. la casse est respectée) ;
\- chaque sous-entité est associé à un tableau, indépendamment du nombre d'éléments.
:::

# Normalisation

La bibliothèque OIP Core exporte une fonction `normalizeEntitySnapshot` pour appliquer des transformations à une trame.
Elle réalise pour chaque entité les transformations suivantes :

- ajout d'une propriété `publicId` correspondant à l'identifiant public de l'entité ;
- ajout d'une propriété `auditInfo` correspondant à la liste des opérations d'écriture réalisées sur l'entité ; le type de cette liste est : `{ publicId: string; createdAt: Date; updatedAt: Date; createdBy: string; updatedBy: string }[]` ;
- suppression des propriétés techniques : `__id`, `__createdAt`, `__updatedAt`, et `__auditInfo` ;
- suppression des chemins listés dans `opts.exclude`.

La signature de cette fonction est :

```typescript
const normalizeEntitySnapshot: (
  obj: object,
  entityType: string,
  config: object,
  opts?: { entityTypeMapper?: (type: string) => string; exclude?: string[] },
) => object;
```

où :

- `obj` est une trame projet ;
- `config` est la configuration des entités présente dans le fichier `entities/entities.mjs`.
- `opts.entityTypeMapper` est une fonction pour modifier le type des entités (e.g. forcer la première lettre en minuscule) ;
- `opts.exclude` est une liste de chemins à exclure ; pour un chemin, le caractère `*` permet d'ignorer un ou plusieurs niveaux de profondeur ; par exemple :
  - `*.Address.auditInfo` supprime la propriété `auditInfo` rattachée à n'importe quelle entité `Address` ;
  - `*.Company.Address` supprime l'entité `Address` rattachée à n'importe quelle entité `Company` ;
  - `*.Grantee.name` supprime la propriété `name` rattachée à n'importe quelle entité `Grantee` ;
  - `*.country` supprime la propriété `country` rattachée à n'importe quelle entité ;
  - `externalId` supprime la propriété `externalId` de l'entité `Project` (entité racine).

## Exemple

```javascript
import { normalizeEntitySnapshot } from "@fasstech/oip-core";
import { getEnv } from "@fasstech/oip-starter-utils/server";
import { queueService } from "@fasstech/rabbitmq-helper";
import config from "../entities/entities.mjs";

// Register a consumer to handle entity messages
queueService.consumeMessage(
  `${getEnv("OAV_ID")}.entities`,
  0,
  ({ entity, data }) => {
    // Normalize snapshot without excluding anything
    normalizeEntitySnapshot(data, entity.type, config);

    // Normalize snapshot while excluding all `auditInfo` data
    normalizeEntitySnapshot(data, entity.type, config, {
      exclude: ["*.auditInfo"],
    });
  },
);
```
