---
title: Migration
slug: oip-next/releases-v4-q1-migration
createdAt: 2026-10-05T10:24:01.120Z
---

Documentation détaillée des changements requis au niveau de la code-base d'un projet v4.

# Mise à jour des dépendances

Mettre à jour les versions des dépendances suivantes dans le fichier `package.json` du projet :

```json
{
  "dependencies": {
    "@fasstech/oip-core": "4.0.0-rc.3",
    "@fasstech/oip-starter-utils": "4.0.0-rc.10",
    "@fasstech/rabbitmq-helper": "0.1.0",
    "dotenv": "17.2.3", // ajout
    "express": "5.2.1",
    "graphql-tag": "2.12.6",
    "node-pg-migrate": "8.0.4", // ajout
    "pg": "8.18.0" // ajout
  },
  "devDependencies": {
    "@apollo/client": "4.1.3",
    "@fasstech/oip-tools": "4.0.0-rc.6",
    "@vitejs/plugin-react-swc": "4.2.3",
    "react": "19.2.4",
    "react-dom": "19.2.4",
    "rxjs": "7.8.2",
    "vite": "7.3.1"
  }
}
```

Puis installer les mises à jour :

```shell
npm i
```

# Suppression des commandes views\:build et config\:gen

Dans le fichier `package.json` supprimer :

- le script `views:build`
- le script `config:gen`

Le build des vues est maintenant fusionné avec la commande `views:gen` :

```json
{
	"scripts": {
		"views:gen": "oip-tools views generate"
	}
}
```

# Support des migrations automatisées du modèle de données

## Ajout du script de migration

Créer le fichier `scripts/run-migrations.sh` à la racine du projet :

```shell
#!/bin/sh

DATABASE_URL=postgres://postgres:postgres@localhost:5432/<my-oav-database>

if [ -n "$1" ]; then
  DATABASE_URL=$1
fi

DATABASE_URL=$DATABASE_URL PGSSLMODE=disable node node_modules/.bin/node-pg-migrate up --migrations-table data_migrations
```

Éditer le script pour remplacer `<my-oav-database>` par le nom de la database de l'OAV du projet.

## Ajout de la commande de migration

Ajouter la commande `migrate:dev` et `start-server:dev` dans le fichier `package.json` :

```json
{
	"scripts": {
		"migrate:dev": "./scripts/run-migrations.sh",
		"start-server:dev": "npm run migrate:dev && npm run server:dev"
	}
}
```

La commande `start-server:dev` assure d'appliquer les migrations en attente avant le démarrage du serveur.

## Dossier des fichiers de migration

Créer le dossier `migrations` à la racine du projet (créer un fichier `.gitkeep` à l'intérieur si le dossier est vide).

C'est dans ce dossier que sont placés les fichiers SQL relatifs aux migrations du modèle de données ainsi que le script d'initialisation de la donnée du projet.

À l'ajout d'un fichier de migration dans le dossier, penser à run la commande suivante pour appliquer la migration :

```shell
npm run migrate:dev
```

# Mise à jour des fichiers des entités

Exécuter la commande suivante pour mettre à jour les fichiers générés des entités dans le dossier `entities` à la racine du projet.

```shell
npm run entities:gen
```

# Dossier des fichiers de transition des vues

Déplacer le dossier des fichiers de transition des vues `config/views/transitions` à la racine du projet => `transitions`

Utiliser la fonctionnalité « Refactor » de l'IDE pour mettre à jour les chemins des imports impactés dans les fichiers de transition.

!! Ne pas utiliser des alias d'import comme `@@entities` dans les fichiers de transition !!

# Fichier nodemon.json

Éditer le fichier `nodemon.json` à la racine du projet pour gérer le déplacement du dossier `transitions` des vues :

```json
// before
{
	"watch": ["config/views/transitions/*", "./server/**/*", "./views/server.mjs", "./views/**/server/**/*"]
}

// after
{
  "watch": ["./server/**/*", "./transitions/**/*", "./views/**/server/**/*"]
}
```

# Dossier des vues

## Racine du dossier des vues

Supprimer les fichiers `client.js` et `server.mjs` à la racine du dossier `views`.

## Dossier `_common`

- supprimer les fichiers `TaskSubscription.js` et `TaskWorkflowSubscription.js` du dossier `_common/client/graphql/subscriptions`
- supprimer les fichiers `useCommitMutation.js` et `useSubscription.js` du dossier `_common/client/hooks`
- supprimer le fichier `validateResolverContext.js` du dossier `_common/server/helpers`

→ Ces fichiers sont maintenant exportés depuis la lib `@fasstech/oip-starter-utils`

## Fichiers client non-générés

Dans les fichiers client non-générés des vues (qui ne possèdent pas le commentaire en en-tête indiquant que le fichier est généré par CLI), remplacer le path d'import de `useCommitMutation`, `useSubscription`, `TaskSubscription` et `TaskWorkflowSubscription` par `@fasstech/oip-starter-utils/app`.

Exemple :

```javascript
// after
import { useCommitMutation, useSubscription, TaskSubscription, TaskWorkflowSubscription } from '@fasstech/oip-starter-utils/app';
```

## Resolvers des vues

Remplacer le path d'import de l'helper `validateResolverContext` si utilisé dans les resolvers :

```javascript
// before
import { validateResolverContext } from '_common/server/helpers/validateResolverContext.js';

// after
import { validateResolverContext } from '@fasstech/oip-starter-utils/server';
```

## Header des fichiers générés

Remplacer le commentaire des fichiers générés :

```javascript
// before
/**
 *
 * WARNING : fichier généré par cli, ne pas le modifier directement
 *
 */

// after
// Code generated by gen. DO NOT EDIT.
```

## Lancer la génération des vues

Enfin, lancer la commande de génération des vues pour terminer la migration des vues :

```shell
npm run views:gen
```

# Vérification de la configuration de Jest côté serveur

Dans le cas où les resolvers graphQL des vues sont testés via *Jest*, s'assurer d'avoir mocké les fonctions importées dans les resolvers depuis `@fasstech/oip-starter-utils/server`.

Exemple d'un fichier `server/__mocks__/oip-server-mock.mjs` qui mock les appels `OK`, `KO` et `validateResolverContext` :

```javascript
/**
 * Mock pour @fasstech/oip-starter-utils/server
 */

export const validateResolverContext = (expectedViewId, actualViewId) => {
  // Lance une exception si les viewIds ne correspondent pas
  if (expectedViewId !== actualViewId) {
    throw new Error(`Invalid resolver context: expected ${expectedViewId} but got ${actualViewId}`);
  }

  return true;
};

// Export OK et KO qui sont également utilisés dans les resolvers
export const OK = (data) => ({ ok: true, ...data });
export const KO = (error) => ({ ok: false, error });

export default {
  validateResolverContext,
  OK,
  KO
};
```

Puis au niveau du fichier de configuration de Jest côté serveur, s'assurer de charger correctement le mock grâce à la propriété `moduleNameMapper` :

```javascript
export default {
  moduleNameMapper: {
    // ...
    '^@fasstech/oip-starter-utils/server$': '<rootDir>/server/__mocks__/oip-server-mock.mjs'
  }
};
```

# Index du serveur

Dans le fichier `server/index.mjs` du projet :

- supprimer l'import et l'utilisation des définitions des types graphQL des vues `loadSchemaTypes`
- ajouter le chargement de la config `dotenv` en 1ère position des imports du fichier

Exemple :

```javascript
import 'dotenv/config'; // ajout

import loadSchemaTypes from '../views/server.mjs'; // suppression

const schemaTypes = await loadSchemaTypes(); // suppression

// before
let serverConfig = {
	// ...
	graphql: {
    resolvers: R.concat(R.pipe(R.map(R.prop('resolvers')), R.reject(R.anyPass([R.isNil, R.isEmpty])))([...schemaTypes, ...myCustomTypesWithResolvers]), [myCustomResolvers]),
    typeDefs: R.concat(R.map(R.prop('typeDefs'), schemaTypes), [ExtendedProcessType, ...myCustomTypes])
  },
};

// after
let serverConfig = {
	// ...
	graphql: {
    resolvers: R.concat(R.pipe(R.map(R.prop('resolvers')), R.reject(R.anyPass([R.isNil, R.isEmpty])))(myCustomTypesWithResolvers), [myCustomResolvers]),
    typeDefs: [ExtendedProcessType, ...myCustomTypes]
  },
};
```

# Build et déploiement

Attention, les instructions suivantes sont peut-être à adaptées si besoin, selon les spécificités du projet.

## Fichier Dockerfile

Dans le fichier `Dockerfile` du projet, appliquer les changements suivants :

1. Supprimer la totalité du stage `config`
2. Supprimer les instructions qui font référence au stage `config` dans le fichier (notamment les instructions avec `--from=config`)
3. S'assurer que les instructions suivantes existent dans le dernier stage du fichier, les ajouter si nécessaire :

```dockerfile
COPY --chown=node:node ./migrations /usr/src/app/migrations
COPY --chown=node:node ./entities /usr/src/app/entities
COPY --chown=node:node ./transitions /usr/src/app/transitions
```

4. Éditer l'instruction finale `CMD` :

```dockerfile
# before
CMD ["dumb-init", "node", "server/index.mjs"]

# after
ENTRYPOINT ["dumb-init", "--"]
CMD ["sh", "-c", "DATABASE_URL=$DATABASE_URL PGSSLMODE=$DATABASE_SSLMODE node node_modules/.bin/node-pg-migrate up --migrations-table data_migrations && node server/index.mjs"]
```

5. Tester le build de l'image de l'OAV avec la commande suivante :

```shell
docker buildx build --build-arg BUILD_DATE=<DATE> --secret id=npmrc,src=<PATH> -t fasstech/oip-starter-v4:latest --no-cache .
```

## Fichiers docker-compose.yml et les environnements Portainer (dev, recette, prod, etc.)

1. Mettre à jour le tag de l'image `fasstech/oip-headless` des services `oip-headless-api` en `0.0.22`
2. Au niveau de l'environnement du service de l'OAV :

- ajouter la variable `DATABASE_URL`, la valeur attendue correspond à l'URL de la database de l'OAV de votre projet
- ajouter la variable `DATABASE_SSLMODE`, avec pour valeur `require` pour un env de production ou `disable` pour un env de développement
