Configurer les entités

18 min

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.

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]*$/).

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.

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.

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.

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.

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

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é.

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.

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]*$/).

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.

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

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

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/.