API Client

24 min

L'API client expose les éléments suivants (named exports) :

la méthode start qui permet d'initialiser l'application React

le hook useProcess qui permet la gestion des transitions et des tâches depuis les composants des vues de l'OAV

le composant Router qui permet d'initialiser les routes de l'OAV

l'objet Tokens qui permet la gestion des credentials et du token d'authentification de l'application client

Les imports depuis l'OAV :

import {
  start,
  useProcess,
  Router,
  Tokens
} from '@fasstech/oip-starter-utils/app';

Méthode start

La méthode start initialise l'application React de l'OAV. Elle prend en paramètre un objet de configuration. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// Init client app
(async () => {
  startApp({ /* options */ })();
})();

Options requises

app

Le composant App de l'OAV est attendu en valeur. Le composant App doit impérativement charger le composant Router fournit par la lib. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';
import { Router } from '@fasstech/oip-starter-utils/app';
import views from '../views/client.js';

// App component
const App = () => {
  // ...

  return (
    <>
      <OtherProvider>
        {/* Router component must be returned */}
        <Router views={views} />
      </OtherProvider>
    </>
  );
};

// Init client app
(async () => {
  startApp({
    app: App,
    // ...
  });
})();

processFragment

La définition du fragment graphQL de l'objet process est attendue en valeur. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';
import { gql } from '@apollo/client';

// Process fragment def
const ProcessFragment = gql`
  fragment ProcessFragment on ExtendedProcess {
    # required fields (do not remove)
    projectId
    viewId
    metadata
    sessionId

    # additional fields
    # requested fields must match type definition at server/graphql/types/extended-process-type.mjs
    # add your custom fields here
    # ...
  }
`;

// Init client app
(async () => {
  startApp({
    processFragment: ProcessFragment,
    // ...
  });
})();

Se référer à cette documentation pour plus de détails.

useCustomHandlers

Le hook qui définit les handlers personnalisés est attendu en valeur. Ex. :

// hook declaration
const useCustomHandlers = () => {
  const myCustomHandler = () => {
    // some logic
  };

  const customHandlers = {
    myCustomHandler
  };

  // the hook must return an object `customHandlers`
  return {
    customHandlers
  };
};

// Init client app
(async () => {
  startApp({
    useCustomHandlers,
    // ...
  });
})();

Se référer à cette documentation pour plus de détails.

Options optionnelles

ctxPolicy

Option disponible à partir de la version 3.4.2

Le support de la valeur shadow-crm est disponible à partir de la version 3.6.0 (voir plus bas)

Définit la manière dont la lib cherchera le token du contexte client lors du décrochage. Valeurs possibles : parameters | local-storage | session-storage | url-params | shadow-crm

Par défaut, la lib cherche le token dans les paramètres de l'URL (paramètre token ou projectId)

Exemple :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// from local storage
(async () => {
  localStorage.setItem('ctxToken', 'my-ctx-client-token');
  // or
  localStorage.setItem('fasstProjectId', 'my-fasst-project-id');

  startApp({
    // ...
    ctxPolicy: 'local-storage'
  });
})();

// from session storage
(async () => {
  sessionStorage.setItem('ctxToken', 'my-ctx-client-token');
  // or
  sessionStorage.setItem('fasstProjectId', 'my-fasst-project-id');

  startApp({
    // ...
    ctxPolicy: 'session-storage'
  });
})();

// as parameter
(async () => {
  const ctx = {
    token: 'my-ctx-client-token',
    // or
    projectId: 'my-fasst-project-id'
  };

  startApp({
    // ...
    ctxPolicy: 'parameters',
    ctx
  });
})();

// default like
// URL: https://my.oav.fasst/?token=my-ctx-client-token
// or
// URL: https://my.oav.fasst/?projectId=my-fasst-project-id
(async () => {
  startApp({
    // ...
    ctxPolicy: 'url-params'
  });
})();

Shadow CRM

Utiliser la valeur shadow-crm pour activer le support du shadow CRM lors du décrochage sur l'OAV. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// shadow CRM support
(async () => {
  startApp({
    // ...
    ctxPolicy: 'shadow-crm',
  });
})();

Attention, la prise en charge du Shadow CRM nécessite également la définition des variables d'environnement suivantes :

SHADOW_CRM_URL
SHADOW_CRM_TEAM_API_KEY

ctx

Option disponible à partir de la version 3.4.2

Un objet qui définit le contexte client est attendu en valeur. Doit être utilisé avec l'option ctxPolicy définit par parameters. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

(async () => {
  const ctx = {
    token: 'my-ctx-client-token',
    // or
    projectId: 'my-fasst-project-id'
  };

  startApp({
    // ...
    ctxPolicy: 'parameters',
    ctx
  });
})();

badRequestPage

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur 400 lors de la navigation sur l'OAV. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// bad request component
const BadRequestPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Bad request!</p>
    </div>
  );
};

(async () => {
  startApp({
    // ...
    badRequestPage: BadRequestPage
  });
})();

unauthorizedPage

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur 401 lors de la navigation sur l'OAV. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// unauthorized component
const UnauthorizedPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Unauthorized!</p>
    </div>
  );
};

// init
(async () => {
  startApp({
    // ...
    unauthorizedPage: UnauthorizedPage
  });
})();

forbiddenPage

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur 403 lors de la navigation sur l'OAV. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// forbidden component
const ForbiddenPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Forbidden!</p>
    </div>
  );
};

// init
(async () => {
  startApp({
    // ...
    forbiddenPage: ForbiddenPage
  });
})();

notFoundPage

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur 404 lors de la navigation sur l'OAV. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// not found component
const NotFoundPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Not found!</p>
    </div>
  );
};

// init
(async () => {
  startApp({
    // ...
    notFoundPage: NotFoundPage
  });
})();

internalServerError

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur 500 lors de la navigation sur l'OAV. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// internal server error component
const InternalServerErrorPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Internal server error!</p>
    </div>
  );
};

// init
(async () => {
  startApp({
    // ...
    internalServerError: InternalServerErrorPage
  });
})();

redirectOnError

Option disponible à partir de la version 3.4.2

Boolean. Permet d'activer ou de désactiver la redirection vers la page d'erreur relative lors d'une erreur HTTP lors de la navigation sur l'OAV. Activé par défaut

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// init
(async () => {
  startApp({
    // ...
    redirectOnError: false
  });
})();

rootDivId

Option disponible à partir de la version 3.4.2

String. Permet de définir l'id de l'élément root de l'application client. Par défaut l'id de l'élément root attendu est fasst-oav-root

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// index.html file
<!doctype html>
<html lang="fr">
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- change root id here -->
    <div id="my-custom-root-id"></div>
    <script type="module" src="/app/index.jsx"></script>
  </body>
</html>

// init
(async () => {
  startApp({
    // ...
    rootDivId: 'my-custom-root-id'
  });
})();

isBundle

Option disponible à partir de la version 3.4.3

Cette option est corrélée avec l'utilisation de la propriété bundle du composant Router. cf Router Component

Boolean, false par défaut. Si défini à true l'application client sera démarrée en mode bundle. Ex. :

import { start as startApp } from '@fasstech/oip-starter-utils/app';

// init
(async () => {
  startApp({
    // ...
    isBundle: true
  });
})();

Hook useProcess

À partir de la version 3.4.3, processHandlers expose également l'handler destroyApp utile en mode bundle pour libérer la mémoire lors d'une transition d'un bundle de vues à un autre. context contient également une propriété isBundle qui indique si l'application client a été démarrée en mode bundle ou non.

À partir de la version 3.4.4, processHandlers expose également l'handler onLogout qui permet de détruire la session de navigation actuelle.

Le hook useProcess exposé par la lib permet de récupérer le contexte (Process) de l'OAV et permet la gestion des transitions et des tâches depuis les composants des vues de l'OAV. Ex. :

import { useProcess } from '@fasstech/oip-starter-utils/app';

const MyView = () => {
  const { context, processHandlers } = useProcess();

  const onNext = () => {
    processHandlers.onNext();
  };

  return (
    <div>
      <h2>{context.viewId}</h2>

      <button onClick={onNext}>NEXT</button>
    </div>
  );
};

export default MyView;

Se référer à cette documentation pour plus de détails.

Composant Router

Le composant Router exposé par la lib permet d'initialiser les routes des vues de l'OAV. Ce composant doit être impérativement définit en tant que children du composant App de l'OAV.

Propriétés

views

Les vues de l'OAV sont attendues en valeur. Ex. :

import { Router } from '@fasstech/oip-starter-utils/app';
import views from '../views/client.js';

export const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router views={views} />
      </SomeProvider>
    </>
  );
};

bundle

Propriété disponible à partir de la version 3.4.3

Dans le cas d'un démarrage de l'application client en mode bundle, il est alors nécessaire d'utiliser la propriété bundle (et non la propriété views) pour passer les vues à chargées.

Dans ce cas d'usage, il est également nécessaire de définir l'option isBundle à true lors de l'appel à la méthode start de l'API Client. cf Option isBundle

Ex. :

import { Router } from '@fasstech/oip-starter-utils/app';
import MyBundle from '../views/my-bundle.js';

export const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router bundle={MyBundle} />
      </SomeProvider>
    </>
  );
};

disableQueryStringParams

Propriété disponible à partir de la version 3.5.0

Propriété optionnelle disableQueryStringParams (boolean) false par défaut. Si définie à true, le paramètre d'URL projectId n'est plus affiché au niveau de l'URL de l'OAV.

Ex. :

import { Router } from '@fasstech/oip-starter-utils/app';
import views from '../views/client.js';

export const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router views={views} disableQueryStringParams={true} />
      </SomeProvider>
    </>
  );
};

Objet Tokens

L'objet Tokens exposé par la lib permet la gestion des credentials et du token d'authentification du client (de l'application React) de l'OAV.

Pour plus de détails concernant l'authentification client se référer à cette documentation

Il n'est logiquement pas nécessaire que le code de l'OAV interagit directement avec cette API

Tokens expose 3 méthodes :

getAccessToken = async (refresh: boolean) => tokens : retourne un objet contenant l'access token et le refresh token. Prend en paramètre optionnel un booléen pour rafraîchir ou non les tokens avant de les retourner (false par défaut)

setKey = (clientId: string, key: string) => void : permet de définir les credentials de l'application React clientId et key. Cette méthode est appelée dans le corps de la méthode start pour initialiser l'authentification client

setUseToken = (useToken: boolean) => void : ne pas utiliser cette méthode, comportement indéfini !