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

Suivez les étapes de ce guide de migration pour appliquer les changements requis dans la code-base de votre projet pour la mise à jour des dépendances OIP.

Rappel des dépendances OIP v4 mise à jour :

- @fasstech\@oip-core v4.0.0-rc.3
- @fasstech/oip-tools v4.0.0-rc.6
- @fasstech/oip-starter-utils v4.0.0-rc.10

Déplacez les scripts de migration fournis avec ce guide à la racine de votre projet. Puis suivez, dans l'ordre, les instructions du chapitre suivant.

En cas d'erreur, veuillez contacter l'équipe OIP.

# Étapes de migration

## 0 - Mise à jour du schéma PostgreSQL

**Veillez à créer une sauvegarde de votre base de données avant la mise à jour du schéma.**

- Exécuter le script `db_schema_01.sql` depuis le container de votre instance `PostgreSQL` ;
- Exécuter la commande `./bin/migrate` depuis le container de votre instance `OIP Headless` ;
- Exécuter le script `db_schema_02.sql` depuis le container de votre instance `PostgreSQL`.

## 1- Mise à jour du fichier package.json

Exécuter le script `mig-00-package-json.js` pour mettre à jour le fichier `package-json` :

```shell
node mig-00-package-json.js --execute
```

## 2- Installation et mise à jour des dépendances

Exécuter la commande suivante pour installer et mettre à jour les dépendances du projet :

```shell
npm i
```

## 3- Setup de l'automatisation des migrations du modèle de données

Exécuter le script `mig-01-setup-structure.sh` pour implémenter l'automatisation des migrations du modèle de données :

```shell
./mig-01-setup-structure.sh --execute
```

Puis éditer le fichier `scripts/run-migrations.sh` et remplacer `<my-oav-database>` par le nom de la database de l'OAV.

## 4- Déplacer le dossier des fichiers de transition des vues

Déplacer le dossier des fichiers de transition des vues `config/views/transitions` (avec la fonctionnalité *Refactor* de votre IDE) à la racine du projet : `transitions`

!! Veuillez faire attention de ne pas utiliser des alias d'import comme `@@entities` dans les fichiers de transition !!

## 5- Mise à jour du fichier nodemon.json

Éditer le fichier `nodemon.json` à la racine de votre projet :

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

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

## 6- Nettoyage du dossier des vues

Exécuter le script `mig-02-cleanup-views.sh` pour nettoyer le dossier `views` :

```shell
./mig-02-cleanup-views.sh --execute
```

## 7- Modifier les headers des fichiers générés des vues

Exécuter le script `mig-03-replace-header-views.js` pour modifier les headers des fichiers générés du dossier `views` :

```shell
node ./mig-03-replace-header-views.js --execute
```

## 8- Changer le chemin d'import de l'helper de validation du contexte d'appel dans les resolvers

Exécuter le script `mig-04-validate-resolver-context-views.js` pour changer le chemin d'import de l'helper `validateResolverContext` dans les resolvers graphQL des vues :

```shell
node ./mig-04-validate-resolver-context-views.js --execute
```

## 9- Vérification des imports dans les fichiers client non-générés des vues

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), assurez-vous de remplacer le path d'import de `useCommitMutation`, `useSubscription`, `TaskSubscription` et `TaskWorkflowSubscription` par `@fasstech/oip-starter-utils/app`.

Exemple :

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

## 10- Terminer la migration des vues

Lancer la commande de génération des vues pour terminer la migration des vues :

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

## 11- Mise à jour des fichiers des entités

Lancer la commande de génération des fichiers des entités pour les mettre à jour :

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

## 12- Migration du fichier index du serveur

Migrer manuellement le fichier `server/index.mjs` de votre 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],
  },
};
```

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

Dans le cas où vous testez les resolvers graphQL de vos vues, [vérifiez votre configuration Jest côté serveur](https://github.com/fasst/oip-migration-doc/blob/main/v4/2026-02-12/MIGRATION_REFERENCE.md#v%C3%A9rification-de-la-configuration-de-jest-c%C3%B4t%C3%A9-serveur).

## 14- Migration du Dockerfile

Migrer manuellement le fichier `Dockerfile` de votre projet :

- Supprimer la totalité du stage `config`
- Supprimer les instructions qui font référence au stage `config` dans le fichier (notamment les instructions avec `--from=config`)
- Assurez-vous 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
```

- É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"]
```

## 15- Test du build de l'image docker

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

## 16- Migration des environnements de déploiement

Migrer manuellement les fichiers `docker-compose.yml` et vos environnements Portainer (dev, recette, prod, etc.) :

- Veuillez mettre à jour le tag de l'image `fasstech/oip-headless` de vos services `oip-headless-api` en `0.0.22`
- 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

## 17- Tests finaux

Vous avez terminé d'appliquer les changements requis !

Testez votre OAV en local, via docker, etc. Lancez vos tests. En cas d'erreurs, n'hésitez pas à contacter l'équipe OIP.
