Récupérer une trame projet
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 :
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.
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'));
EOFEnvoi manuel
La bibliothèque OIP Core exporte une fonction requestEntitySnapshot pour forcer l'envoi d'une trame.
La signature de cette fonction est :
const requestEntitySnapshot: (
entity: Entity,
metadata?: object,
) => Promise<void>;Exemple
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 :
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) => {
// ...
});Le type du message envoyé est :
{ type: string; data: object; metadata?: object }La trame projet est alors accessible via la propriété data.
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 :
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
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"],
});
},
);