Glossaire

Note : La réalisation du nouveau système Back Office étant en cours, merci de noter que la terminologie utilisée dans ce document pour décrire les applications, les différentes étapes du workflow ou les productions/fichiers, n'est pas définitive.

APPLICATIONS :

Portail : ou Portail Sésame. Site d'accès unique pour les utilisateurs (Île-de-France Mobilités et Transporteurs) aux applications Île-de-France Mobilités de gestion des données "transport" (notamment de type Back Office SIM).

Référentiel Arrêts : Système permettant la collecte et la gestion des données arrêts, groupe d'arrêts et accès pour l'Île-de-France. Application actuellement nommée REFLEX, demain ICAR. ICAR comportera la gestion des correspondances.

Référentiel Lignes : Système permettant la collecte et la gestion des données de description des lignes (comprenant aussi les concepts liés à la ligne : transporteurs, réseaux, modes, etc.) pour l'Île-de-France. Application anciennement nommée CODIFLIGNE, désormais ILICO.

Back Office Offre Théorique (IBOO) : Système permettant la collecte et la gestion des données d'offre théorique pour l'Île-de-France.

Back Office SIM : Ensemble des applications : Référentiel Arrêts, Référentiel Lignes, Back Office Offre Théorique.

DUALE : Base de donnée au cœur du système actuel de collecte des données d' "offre théorique". Elle concentre l'ensemble des données arrêts, lignes, offre et correspondances d'Île-de-France, et permet l'alimentation des front office d'Île-de-France Mobilités et de ses partenaires. Sera remplacée à terme par le nouveau Back Office SIM.

Note : Le terme "Back Office" est fréquemment abrégé "BO" dans la suite de ce document

FICHIERS :

Fichiers d'import : Fichiers acceptés pour l'alimentation des Back Office Île-de-France Mobilités (au format NETEX)

Fichiers publiés : Fichiers produits en sortie des Back Office Île-de-France Mobilités (en général au format NETEX)

Import Offre : Type de jeu de fichiers accepté en entrée du Back Office Offre. Les fichiers qu'il contient sont au format NETEX. Le jeu décrit les données d'offre pour un ensemble cohérent : pour une liste de lignes et sur une période donnée.

Export Offre IDF : Type de jeu de fichiers publié par le Back Office Offre. Les fichiers qu'il contient sont au format NETEX. Le jeu décrit l'offre théorique pour toutes les lignes de transport d'Île-de-France sur une période limitée.

Export Ligne Offre : Type de jeu de fichiers publié par le Back Office Offre. Les fichiers qu'il contient sont au format NETEX. Le jeu décrit l'offre théorique pour une seule ligne de transport sur toute la période fournie par le transporteur référent.

Export Correspondances : Fichier au format NETEX. Il contient toutes les correspondances entre les "arrêts" d'Île-de-France. (format non défini pour l’instant)

Organisation : Entité d'appartenance pour les utilisateurs listés dans le Portail. Concept utilisé pour définir sur un périmètre fonctionnel les droits dans les systèmes Back Office Île-de-France Mobilités. Il correspond en général à un groupe de transporteur, transporteur, "réseau" transporteur, etc.

SOUS-ENSEMBLES BACK OFFICE OFFRE :

Espace de travail : Espace propre à chaque organisation permettant d'importer/modifier/gérer des données d'offre théorique.

Jeu de données : Au sein de l'espace de travail, unité cohérente définie par un périmètre de ligne et une période de validité ; elle correspond à un "fragment d'offre". Un "Import Offre" alimenté dans le Back Office Offre produit un jeu de données.

Offre Consolidée Organisation : Ensemble existant pour chaque organisation et comprenant l'ensemble des données d'offre théorique pour celle-ci. Elle est produite à partir de la consolidation des jeux de données poussés par le transporteur.

Offre Agrégée IDF : Ensemble unique comprenant l'offre théorique pour toutes les lignes d'Ile de France. Elle est produite à partir de l'agrégation de toutes les Offre Consolidée Organisation.

WORKFLOW BACK OFFICE OFFRE : 

Importation Offre : Alimentation d'un ou plusieurs Import Offre dans l'Espace de Travail. Chaque "Import Offre" produit un jeu de données.

Consolidation Offre : Dans le Back Office Offre, mise à jour d'une Offre Consolidée Organisation avec l'insertion d'un ou plusieurs jeux de données poussés par un utilisateur.

Agrégation Offre : Dans le Back Office Offre, mise à jour de l'Offre Agrégée IDF à partir des Offre Consolidée Organisation qui ont été mises à jour.

Publication : Production des "Exports" depuis l'Offre agrégée IDF.

Introduction

Ce document s’inscrit dans le programme de modernisation du Back-Office SIM. Celui-ci vise à mettre en œuvre une nouvelle chaîne de collecte et de distribution des données des données Information Voyageur en Île De France.

Dans le cadre de la phase 1 de ce programme, Île-de-France Mobilités assure un portage iso-fonctionnel des objets actuellement transmis par les Transporteurs vers la base DUALE. Contrairement à la base DUALE actuelle, qui concentre l’ensemble des données IV fournies par le Transporteur dans une unique base de données, le futur Back-Office Offre Théorique modernisé prévoit de s’appuyer sur les référentiels Arrêts et Lignes pour isoler les concepts relatifs aux arrêts et correspondances d’une part, et aux lignes commerciales d’autre part.

Ce document présente le format et les interfaces d’import des données d’offre de transport en commun dans le sous-système BO Offre Théorique Ces systèmes seront mis à disposition des transporteurs sous contrat avec Île-de-France Mobilités.

Pour rappel, le BO Offre Théorique permettra également de saisir directement son offre dans l'interface web du système,  via IHM. Le système est basé sur le logiciel Chouette.

Organisation des imports

Deux mécanismes sont proposés pour l'intégration des fichiers dans le BO : 

• via upload depuis l'IHM du  BO Offre Théorique 

• via API (protocole RESTful)

Ces mécanismes sont détaillés dans le chapitre : Interface d’import

Règles et restrictions

Tableaux d’attributs

Les tableaux d’attributs dans les chapitres suivants précisent pour chaque objet NeTEx exploité, le traitement attaché à chacun des attributs de l’objet. Les tableaux sont constitués de 4 colonnes : 

Pour les attributs ayant une cardinalité commençant par "0:" (attribut non obligatoire), il est possible de ne pas indiquer la balise dans le fichier d’import. En fonction du type de valeur, il peut aussi être accepté d'indiquer la balise avec une valeur vide. Pour les types comme enum, integer, time ou datetime par exemple, une balise "vide" provoquera une erreur XSD.  Afin d'éviter les erreurs, si une information n'est pas du tout gérée par le transporteur, Île-de-France Mobilités préconise de ne pas indiquer cette balise.

Règle d’exploitation des informations NeTExation des informations NeTEx

Les couleurs utilisées dans les tableaux permettent de mettre en valeur les objets et attributs exploités ou non lors de l’import dans le BO IV. Trois cas de figure sont possibles :

• Information (donnée ou objet) non exploitée : l’information fait uniquement l’objet de contrôles de conformité au format XML et aux règles définies par NeTEx. En dehors de ces contrôles, l’information est totalement ignorée dans le processus d’import. Si cette information est optionnelle, il est fortement conseillé de ne pas la fournir afin de réduire les volumes et les temps de traitements lors de l’import dans le BO IV.

• Information (donnée ou objet) exclue : l’information est rejetée car le BO IV ne peut pas l’importer. La présence de l’information rend alors invalide la ligne contenant cette information ou si l’information est commune au jeu de donnée, celui-ci est globalement invalide. L’exclusion est traduite par un point de contrôle obligatoire spécifique à l’import et la présence d’une information exclue sera restituée en erreur dans le rapport d’import produit par le BO IV. 

• Donnée ou objet exploité : l’information a une utilité à l’import, toutefois, celle-ci n’est pas obligatoirement restituée à l’identique dans l’offre obtenue à l’issu de l’import dans le BO IV ; pour ces données, la définition issue du profil est rappelée afin de faciliter la lecture et si nécessaire, le traitement réalisé à l’import BO IV; par défaut, l’information est importée dans un attribut de l’objet BO IV correspondant. Pour les données optionnelles, sauf mention contraire dans les tableaux, la donnée est laissée vide dans le BO IV si elle n’est pas renseignée à l’import. 

Delivery et Frames

Cadres de version ou frames

Les cadres de version sont de 2 types :

• GeneralFrame : Contient uniquement des objets métiers. La liste des objets autorisés dépend de l’attribut ‘TypeOfFrameRef’ du cadre et est définie par le Profil  

• CompositeFrame : Contient uniquement d’autres cadres de versions, la liste des cadres de version autorisés dépend de l’attribut ‘TypeOfFrameRef’ du cadre et est définie par le Profil IDF.

Chaque fichier XML respecte les règles de format du Profil IDF ; ils sont donc tous composés d’un objet racine de type ‘PublicationDelivery’. Cet objet contient ensuite les cadres de versions qui sont structurés comme indiqué dans le chapitre B 3 Delivery et Frames.

PublicationDelivery

Données caractérisant l’objet PublicationDelivery :

Entités abstraites et héritage

NeTEx définit une hiérarchie d’objets et certains attributs des objets importés sont issus de ces héritages. Afin de simplifier la lecture des attributs relatifs à chaque objet intervenant dans l’import, les attributs issus d’un héritage ne sont rappelés seulement s’ils sont requis pour l’import de l’objet considéré.

Dans le cas de l’utilisation  d’un attribut hérité dans un objet à importer, une nomenclature  est utilisée dans les tableaux d’attributs pour les repérer : le nom de l’attribut en question est précédé d’une abréviation entre parenthèses. Cette abréviation correspond au nom de l’objet qui fournit l’attribut en héritage. :

• (E) pour l’objet ENTITY

• (EIV) pour l’objet EntityInVersion 

Ces deux objets parents sont décrits ci-dessous :   
Entity (E)

Règle de syntaxe des identifiants : Les identifiants des objets, autres que les arrêts, respectent la codification suivante : 

[CODESPACE]:[type d'objet]:[identifiant Technique]:LOC

Avec :

[CODESPACE] : identifiant de fournisseur qui prendra comme valeur  soit le nom du groupe de transport qui fournit la donnée (c'est à dire KEOLIS, OPTILE, RATP, SNCF, ou TRANSDEV) soit le nom de l'organisation (par exemple LACROIX).

[type d'objet]: classe de l'objet sous la forme du nom du tag XML qui le porte

[identifiant Technique] : identifiant interne unique composé de caractères ‘0-9’, ‘A-Z’, ‘a-z’, ‘-‘ et ‘_’. Les caractères accentués (‘é’, ‘ô’, …) et les autres caractères spéciaux (‘ç’, …) sont à remplacer systématiquement par ‘_’.

Note : Île-de-France Mobilités préconise de privilégier l'utilisation de caractères numériques ou simples (par exemple : "-")

LOC: permet de préciser que l'identifiant a été défini de façon locale entre les parties engagées dans l'échange, et qu'il ne fait donc pas partie du référentiel partagé (régional, national, etc.) L'utilisation de ce qualificatif est obligatoire quand l'identifiant est local (hors identifiants Référentiel Arrêts ou Référentiel Lignes).

EntityInVersion (EIV) hérite de Entity :

Si l'attribut hérité n'est pas obligatoire, il n'est pas rappelé dans les tableaux du chapitre B-Import Offre Théorique.

Règles de syntaxe des références

Pour certains attributs, il est attendu des références à des objets dits ‘internes’ (l’objet référencé doit être défini dans le même fichier XML)  ou à des objets ‘externes’ (l’objet référencé est présent dans un autre fichier du jeu de données ou dans une autre source de données comme par exemple dans les Référentiels Arrêts ou Lignes).

Ces références comportent 2 champs obligatoires : l’identifiant de l’objet référencé et sa version.

Syntaxe pour les références à un objet du jeu de données:

• Référence interne (objet dans le même fichier) : 

<ObjetRef ref="[ID de l'objet]" version="[VERSION de l'objet]" />

• Référence externe (objet dans un fichier différent du même jeu de données)

<ObjetRef ref="[ID de l'objet]"> version="[VERSION de l'objet]"</ObjetRef >

Avec : 

[ID de l'objet] : l’attribut respecte la syntaxe des identifiants (voir Entités abstraites et héritage) 

[VERSION de l'objet] : l’attribut correspond au même numéro de version que celui indiqué pour l'objet dans le jeu de données.

Exemple :

Référence au sein d'un fichier offre_[ID REF LIGNE]_[Nom ligne].xml :

<RouteRef  ref="TRANDEV:Route:1234:LOC" version="any"/>

Référence d'un fichier offre_[ID REF LIGNE]_[Nom ligne].xml à calendriers.xml :

<DayTypeRef  ref="TRANDEV:DayType:64:LOC"> version="any"</DayTypeRef>

Syntaxe pour les références à un objet stocké dans le Référentiel Lignes (Ligne commerciale ou Transporteur) ou dans le Référentiel Arrêts (ZDEP) : 

<LineRef ref="FR1:Line:[ID REF LIGNE]:">version="any"</LineRef>

<OperatorRef ref="FR1:Operator:[ID TRANSPORTEUR]:LOC ">version="any" </OperatorRef>

<QuayRef ref="FR::Quay:[ID ZDEP]:FR1">version="any"</QuayRef>

Avec : 

[ID REF LIGNE] : Identifiant de la ligne commerciale dans le Référentiel Lignes

[ID TRANSPORTEUR] : Identifiant du transporteur dans le Référentiel Lignes

[ID ZDEP] : Identifiant de la Zone d'Embarquement Particulière dans le Référentiel Arrêts 

Import Offre Théorique

Organisation des imports

Que ce soit via upload depuis l'IHM ou via API, la fonction d’import du BO Offre Théorique s’attend à recevoir les données d’une offre de transport dans un ensemble de fichiers organisés comme suit :

Le lot de fichiers est rassemblé dans un fichier archive au format ZIP (avec l’option deflate standard et non deflate64).

Il contient un ou plusieurs dossiers correspondants chacun à un jeu de données. L'envoi d'une archive contenant plusieurs jeux de données est uniquement accepté pour les transferts via API.

Fichiers et cadres de version : 

Chaque fichier xml du dossier contient des données relatives à un ou plusieurs cadres de version et sera contrôlé par l’application :

• commun.xml : Contient les objets du cadre de version NETEX_COMMUN. Ce fichier est optionnel : il est inutile de le fournir s’il ne contient aucun objet utile à l’import.

• calendriers.xml : Contient les objets du cadre de version NETEX_CALENDRIER.

• offre_[ID REF LIGNE]_[nom ligne].xml : Chaque fichier contient les données d’offre pour une ligne réparties dans les cadres de version NETEX_STRUCTURE et NETEX_HORAIRE. Ceux-ci sont regroupés au sein d’un cadre de version de type NETEX_OFFRE_LIGNE.

Dans un fichier XML donné, il ne doit y avoir qu’une seule valeur du CODESPACE.

Règles de nommage : 

Le nom des fichiers XML est imposé et contrôlé. Pour offre_[ID REF LIGNE]_[nom ligne].xml :

• [ID REF LIGNE] : code de la ligne commerciale issu du Référentiel Lignes est contrôlé. Il doit respecter strictement son format d’origine avec un C majuscule et des chiffres après comme par exemple C01456.

• [nom ligne] : nom court de la ligne commerciale est non contrôlé mais préconisé.

Seuls les caractères ‘0-9’, ‘A-Z’, ‘a-z’, ‘-‘ et ‘_’ sont autorisés. Les caractères accentués (‘é’, ‘ô’, …) et les autres caractères spéciaux (‘ç’, …) sont à remplacer systématiquement par ‘_’.

Les noms des dossiers et de l'archive ne sont pas contrôlés, mais Île-de-France Mobilités impose les règles de nommage suivantes :

• Préfixe : "OFFRE_[ID ORGA]_", avec [ID ORGA] correspondant à l'identifiant de l'organisation gérée dans le Portail Transporteur par Île-de-France Mobilités (notion correspondant à la notion actuelle de "site de saisie")

• Le reste du nom doit permettre d'identifier clairement le jeu de données pour le producteur. Il peut s'agir d'un numéro de version, si des versions sont gérées dans son système, ou plus simplement la date de production du fichier (préconisation de format : AAAAMMJJhhmmssZ - heure universelle)

• Dans le cas d'une archive ne contenant qu'un seul jeu de données, le nom de l'archive est le même que celui du dossier qu'elle contient. Dans le cas d'une archive contenant plusieurs dossiers (envoi multi-jeux), le nom de l'archive est similaire à ceux des dossiers (voir exemple précédent).

Périmètre du jeu de données 

Chaque jeu rassemble un ensemble de données d’offre valide :

• sur une même période calendaire : celle-ci est précisée dans le fichier calendriers.xml. La période peut être discontinue.

• pour une liste de lignes : L'utilisateur qui réalise l'import dans l'IHM ou le flux API doit posséder des droits en modification sur ces lignes commerciales. Ses droits sont définis par rapport à son Organisation d'appartenance. Ces droits sont définis dans le Portail Transporteur par Île-de-France Mobilités.

Dans une "action d’import", deux jeux de données distincts dont les périodes de validité se chevauchent ne doivent pas décrire de l’offre sur une même ligne. 

De même, si l'on souhaite décrire l'offre d'une ligne dans différents jeux de données (ex : un jeu de données pour l'offre d'été et un autre pour l'offre d'hiver) dans une même archive, les périodes de validité des jeux de données ne doivent pas se chevaucher.

Exemple :

Cette règle de gestion de non chevauchement des périodes de validité pour une ligne est également applicable dans l’espace de travail de l’outil : l'espace de travail d'un utilisateur (IHM du BO Offre Théorique où l'utilisateur peut consulter les données qu'il a importé) ne peut contenir plusieurs jeux de données "en cours", ayant des périodes qui se recouvrent pour une même ligne commerciale.

Le statut "En cours" signifie que le jeu de données a été importé dans le BO mais n'a pas encore été poussé en production (transmis à Ile-de-France Mobilités pour agrégation).

Si le jeu de données a déjà été poussé en production (action manuelle ou automatisable dans le BO Offre Théorique) ou si le jeu de données a été supprimé volontairement par le transporteur (action d'archive manuelle), il est possible alors d'importer un nouveau jeu de données "chevauchant".

Si ce nouveau jeu est poussé en production, alors, pour les lignes concernées :

• pour les données ayant les mêmes intervalles de validité (chevauchement) :

  • celles du nouveau jeu écraseront celles de l’ancien jeu,

• pour les données n’ayant pas les mêmes intervalles de validité :

  • celles de l’ancien jeu resteront valides,

  • celles du nouveau jeu s’ajouteront à celles de l’ancien jeu.

Modélisation des données métier échangées

Les données sont échangées selon la norme NeTEx et s'appuient sur le Profil d’échange IDF défini par Île-de-France Mobilités. Le schéma suivant présente tous les objets requis lors d’un l’import dans le BO Offre Théorique :

Les objets représentés sont regroupés dans des cadres de version (ou ‘Frames’) qui servent de conteneurs pour transporter les objets. 

Chaque cadre de version est identifié par une couleur distincte : 

• NETEX_LIGNE (raccourci de FR1:TypeOfFrame:NETEX_OFFRE_LIGNE:)

• NETEX_STRUCTURE (raccourci de FR1:TypeOfFrame:NETEX_STRUCTURE:)

• NETEX_HORAIRE (raccourci de FR1:TypeOfFrame:NETEX_HORAIRE:)

• NETEX_CALENDRIER (raccourci de FR1:TypeOfFrame:NETEX_CALENDRIER:)

• NETEX_COMMUN (raccourci de FR1:TypeOfFrame:NETEX_COMMUN:) 

Les objets présentés en gris ne font pas partie des données à fournir à l’import, seule une référence externe (au sens NeTEx) est nécessaire.

Delivery et Frames

Les cadres de version attendus à l’import sont structurés de la manière suivante :

	commun.xml	calendriers.xml	offre_[ID REF LIGNE]_[Nom ligne].xml

Les données caractérisant chaque cadre de version (illustrés ci-dessus en vert) sont précisées dans les chapitres suivants.

Chaque fichier XML respecte les règles de format du Profil IDF ; ils sont donc composés d'abord d’un objet racine de type ‘PublicationDelivery’ (voir PublicationDelivery).

Cadre de version ‘NETEX_COMMUN’ 

Organisation et hiérarchie du cadre de version :

Dans celui-ci ne seront traités que des objets de type ‘NOTICE’.

Les autres types autorisés dans ce cadre de version par le Profil IDF sont ignorés (voir ci après).

Description de la General Frame NETEX_COMMUN

Objets pris en compte par le BO Offre Théorique

NOTICE (Note) : Un texte à vocation informationnelle, en général concernant des exceptions d'utilisation, et rattaché dans le cadre du BO Offre Théorique à des SERVICE JOURNEY (Courses)

*Le typage des notes indique sur quel type d'objet la note porte. Des notes de type "LineNotice" (portant sur une ligne entière) peuvent également être renseignées, mais celles-ci doivent être saisies dans le Référentiel Lignes (ex : indication de l'obligation de réservation pour une ligne TAD).

Exemple de restitution de l’objet "NOTICE" au niveau d’un média IV (fiche horaire) :

La référence à la note ("NoticeAssignement") se trouve au niveau de l'objet SERVICE JOURNEY (Course), présent dans les fichiers offre_[ID REF LIGNE].xml livrés dans le même jeu de données. Ces références doivent correspondre à des objets Notice indiqués dans le fichier Commun.xml, sinon aucune note ne sera affectée à la course.

Les notes peuvent être "partagées" par toutes les lignes d'une offre du jeu de données. Toutefois, dans le BO Offre théorique, ces notes seront dupliquées pour être attribuées à chacune des lignes concernées. 

Objets ignorés dans le cadre de version 

 (La présence d’un objet de l’un de ces types ne perturbe pas l’import si la grammaire XML et XSD NeTEx est respectée ; toute erreur XML ou XSD provoque l’interruption de l’import et le rejet total du jeu de données) :

• ALTERNATIVE NAME

• NOTICE ASSIGNMENT

• ORGANISATION

• RESPONSIBILITY ROLE ASSIGNMENT

• TYPE OF FRAME

• TYPE OF VALUE

• VALIDITY CONDITION

Cadre de version ‘NETEX_CALENDRIER’

Organisation et hiérarchie du cadre de version : 

Dans celui-ci ne seront exploités que des objets de type ‘DAY TYPE’, ‘OPERATING PERIOD’ et ‘DAY TYPE ASSIGNMENT’.

L'exclusion du type ‘OPERATING DAY’ signifie que seuls les jours calendaires (de 0h à 23h59) sont gérés par le BO Offre Théorique. Pour une course, l'attribution du calendrier se fait par rapport au jour calendaire du premier horaire de la course. Une course démarrant à 23h58 et une autre démarrant 10min après ne peuvent pas être indiquées sur le même calendrier.

Note : Cette contrainte existe déjà dans les formats d'échanges actuels.

La relation entre les objets est la suivante : 

Les courses référencent un ou plusieurs DAY TYPE (Type de Jour), cet objet est donc la référence pour modéliser un calendrier.  Dans le BO Offre Théorique, chaque objet DAY TYPE avec ses dépendances est transformé en un objet BO Offre Théorique nommé ‘Calendrier’.

Description de la General Frame NETEX_CALENDRIER

*La Frame NETEX_CALENDRIER indique la Période de Validité (ValidBetween) du jeu de données entier. Elle peut se composer

d'un ou de plusieurs intervalles de temps (date de début / date de fin) qui ne doivent pas se chevaucher. 

Ce fonctionnement est une nouveauté par rapport au Back Office actuel, qui suite à un import écrasait les données sur toute la période gérée dans la base communautaire (1 an 1/2, glissant tous les ans). Il permettra notamment de gérer plus facilement les périodes de transition lors d'une restructuration.

Objets pris en compte par le BO Offre Théorique

DAY TYPE (Type de Jour) : Objet servant de base à la construction du calendrier. Il est référencé par les SERVICE JOURNEY (Courses).

DAY TYPE ASSIGNMENT : Objet permettant d' "assigner" (ajouter ou retrancher en fonction du critère IsAvailable) des dates ou des OPERATING PERIOD (Périodes d'Exploitation) à un DAY TYPE.

Note : Un DAY TYPE doit obligatoirement être référencé dans un DAY TYPE ASSIGNMENT, sinon il ne sera pas pris en compte. 

OPERATING PERIOD : Intervalle de temps continu, défini par une date de début et de fin. Rattaché à un ou plusieurs DAY TYPE (Type de Jour) via l'objet DAY TYPE ASSIGNEMENT.

*Format pour les dates de type : <FromDate>2017-06-01T00:00:00</From Date>

En combinant ces 3 objets, il est possible de modéliser ses calendriers de différentes façons.

Exemple n°1 :

Courses circulant du 1^er au 31 juillet, tous les jours sauf les dimanches et sauf le 14 juillet

Exemple n°2 :

Courses circulant le 14 juillet

Un DAY TYPE peut aussi contenir des dates d'exception de circulation (isAvailable=false). C’est le cas de l’exemple n°1 option 2.

La combinaison de ce DAY TYPE avec un autre au niveau du SERVICE JOURNEY permettra de "soustraire" des jours à ce 2ème DAY TYPE. Ce principe peut permettre de plus facilement gérer la modélisation des exclusions de service les jours fériés.

Ce DAY TYPE "négatif" n'est pas conservé tel quel dans le BO Offre Théorique. Le résultat de la soustraction de ce DAY TYPE à un second DAY TYPE génère un seul calendrier dans le BO.

Règles d'import / Cohérence entre les fichiers

• A l’issu de l’import, les calendriers qui ne couvrent aucun jour de la période de validité du jeu de donnée ne sont pas présents,

• Les courses qui n’étaient associées qu’à ces calendriers ne sont pas importées,

• Par effet cascade, les missions commerciales se retrouvant sans courses ne sont pas importées, ainsi que les itinéraires.

Cette règle étant associée à un point de contrôle d’import, les données ignorées seront tracées dans le rapport d’import.

Les calendriers qui définissent des dates en doublon seront simplifiés, comme par exemple :

• Date calendaire déjà présente dans une période

• Périodes se chevauchant

Objets ignorés dans le cadre de version 

La présence d’un objet de l’un de ces types ne perturbe pas l’import si la grammaire XML et XSD NeTEx est respectée ; toute erreur XML ou XSD provoque l’interruption de l’import et le rejet total du jeu de données :

• OPERATING DAY

• SERVICE CALENDAR

Toute relation entre ces objets et ceux exploités lors d’import sera aussi ignorée

Cadres de version constituant l’offre d’une ligne (NETEX_OFFRE_LIGNE)

Organisation et hiérarchie du cadre de version : 

Chaque fichier offre_[ID REF LIGNE]_[Nom ligne].xml contient les informations permettant de décrire l' "offre" pour une ligne commerciale (un fichier .xml par ligne).

Il contient une Frame Composite "NETEX_OFFRE_LIGNE", qui doit indiquer dans son identifiant le code de la ligne commercial issu du Référentiel Lignes. 

Cette information est importante car elle indique le périmètre qui sera "écrasé" dans le Back Office Offre par cette mise à jour (critère cumulé avec la période de validité indiquée dans la frame NETEX_CALENDRIER du fichier Calendrier.xml du jeu de données). 

Ainsi, contrairement aux formats actuellement utilisés par SNCF et OPTILE, il ne sera plus obligatoire de fournir toutes ses lignes dans un jeu de données, sous peine d'effacer l'offre d'une ligne qui aurait été "oubliée".

NETEX_OFFRE_LIGNE est une Composite Frame ; elle contient elle-même deux Frames : NETEX_STRUCTURE (description de la structure de la ligne) et NETEX_HORAIRE (description des courses et horaires).

Fichier offre_[ID REF LIGNE]_[Nom ligne].xml "vide" :

Si l'attribut modification dans la Frame NETEX_OFFRE_LIGNE est "delete", et que celle-ci ne contient aucune frame NETEX_STRUCTURE ni NETEX_HORAIRE, alors il est considéré que la ligne ne circule pas sur la période de validité du jeu de données (période définie dans la frame NETEX_CALENDRIER). Si une offre sur cette période a déjà été importée précédemment à Ile-de-France Mobilités, elle sera donc "écrasée".

Cadre de version ‘NETEX_STRUCTURE’

Organisation et hiérarchie du cadre de version

NETEX_STRUCTURE ne contient que des objets relatifs à l’aspect topologie d'une ligne. 

Les deux objets centraux sont : 

• La ROUTE (Itinéraire) : Premier niveau de subdivision de la ligne commerciale. Il correspond à une suite ordonnée de points définissant un seul chemin à travers le réseau routier (ou ferré). Il est orienté : la suite de ces mêmes points ordonnée dans le sens contraire constitue un autre itinéraire.

• Le SERVICE JOURNEY PATTERN (Mission Commerciale) : il décrit la façon dont "circulent" les véhicules : tous les points d'une mission (STOP POINT IN JOURNEY PATTERN) sont desservis. Une mission est associée à un unique itinéraire.

Dans le format défini pour le BO Offre Théorique, les points sur mission ne peuvent être associés qu'à des points de montée ou de descente des passagers dans le véhicule, c'est à dire qu'à des SCHEDULED STOP POINT (Points d'arrêts planifiés) et non à des points de passage, de régulation, etc.

L'affectation de ces èzqpoints d'arrêts planifiés à une description physique se fait au travers de l'objet PASSENGER STOP ASSIGNMENT. L’import NeTEx IDFM supporte deux syntaxes pour associer un PassengerStopAssignmentà un arrêt:

L’une avec la balise QuayRef:

L’autre avec StopPlaceRef:

Dans les deux cas, la mission et son itinéraire sont associés à l’arrêt désigné par la référence.

La balise QuayRef est réservée à une référence à un arrêt de type ZDE / Arrêt. La balise StopPlaceRef à une référence à un arrêt de type ZDL / Zone d'Arrêts. L’import ajoute un message de warning si la balise et le type d’arrêt ne correspondent pas.

Enfin, la Frame peut aussi contenir l'objet ROUTING CONSTRAINT ZONE (Zone de contrainte), qui peut permettre de décrire des Interdictions de Trafic Local.

Important : 

Afin de simplifier les échanges, la description des points d'itinéraire (POINT ON ROUTE) n'a pas été retenue dans le cadre de ce format. Lors de l'import dans le BO Offre Théorique, la structuration de l'itinéraire est déduit de l'ordre indiqué sur les points de chacune des missions rattachées à celui-ci. 

Dans cet exemple, si l'ordre n'est pas renseigné, le système ne peut savoir si le point D est avant ou après le point C.

Pour une mission, les numéros d'ordre indiqués sur les STOP POINT IN JOURNEY PATTERN peuvent donc être discontinus car ils doivent correspondre à l'ordre sur l'itinéraire global.

Note : si lors dans un jeu de données, un arrêt n’est présent dans aucune des missions importées, alors l’itinéraire résultant ne sera pas le même que pour un jeu de données où une mission dessert cet arrêt.

Les relations entre tous ces objets sont décrites de façon générale dans le schéma suivant. 

Il représente l'organisation générale dans la Frame pour un itinéraire ayant deux missions : une complète et une partielle, et comportant un ITL sur deux arrêts : 

*Interdiction de trafic local au sein de CERGY

Description de la Generale Frame NETEX_STRUCTURE

Objets liés à la définition d'une ROUTE (itinéraire)

ROUTE (Itinéraire) : Liste ordonnée de POINTs définissant un seul chemin à travers le réseau routier (ou ferré). Un Itinéraire peut passer deux fois par un même POINT.

Le regroupement d'itinéraire que constituait la sous-ligne n'existe pas dans NETEX. Toutefois, les itinéraires aller et retour peuvent être couplés deux à deux en indiquant la référence à l'itinéraire inverse dans l'attribut " InverseRouteRef".

Si un itinéraire (A) référence un itinéraire (B) comme son inverse, l'itinéraire B ne peut pas référencer un 3ème itinéraire (C) comme son propre inverse. De plus, les deux itinéraires opposés doivent se référencer mutuellement, sinon l'association sera invalidée à l'import et une alerte sera communiquée.

DIRECTION (Direction) : Direction de la ROUTE (Itinéraire). 

Le nom de la direction est souvent indiqué sur la fiche horaire en haut des tableaux horaires.

Il correspond souvent au nom du dernier arrêt de l'itinéraire ou au dernier arrêt de la mission la plus fréquente de l'itinéraire. Dans ce cas, Ile-de-France Mobilités préconise de structurer le nom ainsi : 

Nom de l'arrêt (Nom de la Commune)

La direction peut aussi correspondre à une zone plus large, comme par exemple le nom d'un quartier, ou encore juste un nom de commune, si cette information suffit à la compréhension de l'usager.

Exemple : 

Objets liés à la définition d'un SERVICE JOURNEY PATTERN (Mission commerciale)

Un même itinéraire peut être utilisé par de nombreuses missions commerciales (soit qu'elle l'utilise complètement ("omnibus"),  partiellement (ex : mission "express"), soit qu'elle fasse varier la liste des arrêts effectivement desservis. 

Note : Pour rappel, une ligne peut contenir plusieurs itinéraires aller et retour.

SERVICE JOURNEY PATTERN (Mission Commerciale) : Liste ordonnée de Points d'Arrêts Planifiés sur un unique Itinéraire, décrivant le plan de déplacement pour les véhicules de transport public. Une Mission peut passer par le même Point plus d'une fois. Le premier Point d'une Mission est l'origine. Le dernier Point est la destination.

DESTINATION DISPLAY : Une destination d'une mission particulière, affichée au public en général sur une girouette ou sur tout autre afficheur embarqué. 

Le nom de la destination (FrontText) correspond souvent au nom du dernier arrêt de la mission. Dans ce cas, Ile-de-France Mobilités préconise de structurer le nom ainsi : 

Nom de l'arrêt (Nom de la Commune).

Si une information sur le via est indiquée, Ile-de-France Mobilités préconise la structuration suivante :

Nom de l'arrêt (Nom de la Commune) VIA Nom du via

Les indications diverses, par exemple "Service partiel", sont mis à la fin.

Comme pour la direction de l'itinéraire, le nom de la destination (FrontText) peut aussi correspondre à une zone plus large, comme par exemple le nom d'un quartier, ou encore juste un nom de commune, si cette information suffit à la compréhension de l'usager.

STOP POINT IN JOURNEY PATTERN (Point sur Mission) - inclus dans SERVICE JOURNEY PATTERN : Un SCHEDULED STOP POINT (Point d'Arrêt Planifié) dans un SERVICE JOURNEY PATTERN (Mission Commerciale) indiquant son rang dans cette Mission.

TypeType*Interdictions de montée/descente : Les informations ForAlighting (Descendre) et ForBoarding (Monter) relatives à la description d’un ITL non zonal seront communes à l’itinéraire. En conséquence, celles-ci ne seront interprétées que si toutes les missions d’un même itinéraire fournissent la même valeur pour l’ensemble de ces attributs. Dans le cas contraire, ces informations sont neutralisées avec un signalement lors de l’import. 

Objets permettant le lien vers les arrêts du Référentiel Arrêts

SCHEDULED STOP POINT (Point d'Arrêt Planifié) : Un POINT où les passagers peuvent monter à bord ou descendre des véhicules. Cet objet est partagé entre les différents SERVICE JOURNEY PATTERN (Missions) d’une même ROUTE (Itinéraire).

PASSENGER STOP ASSIGNMENT : Permet d'associer un point "horaire" : SCHEDULED STOP POINT (Point d'Arrêt Planifié), à un point "physique" : dans le cas de l'import dans le BO Offre Théorique seule l'association à un ZDEP connu du Référentiel Arrêts est acceptée.

Afin de simplifier la construction du fichier et de faciliter la lecture, si le producteur de la donnée ne dispose pas de ces différents concepts dans son SI source, il est possible de générer le même ID Interne pour les objets suivants : SCHEDULED STOP POINT et PASSENGER STOP ASSIGNMENT. 

Objets liés à la définition des ITL

ROUTING CONSTRAINT ZONE : ZONE au sein de laquelle une contrainte d'acheminement s'applique. La ZONE est définie par la liste des SCHEDULED STOP POINT (Points d'Arrêt Planifiés) qu'elle contient.

Note :Dans le BO Offre théorique, les ITL sont reliées aux itinéraires ; dans le cas où une RoutingConstraintZone contient des références à des ScheduledStopPoint utilisés par plusieurs itinéraires, celle-ci génèrera autant d’ITL que d’itinéraires concernés par au moins 2 ScheduledStopPoint de la RoutingConstraintZone tout en excluant les itinéraires entièrement couverts par celle-ci.

Objets ignorés dans le cadre de version 

La présence d’un objet de l’un de ces types ne perturbe pas l’import si la grammaire XML et XSD NeTEx est respectée ; toute erreur XML ou XSD provoque l’interruption de l’import de la ligne et son rejet :

• CONNECTION

• DEFAULT CONNECTION

• FLEXIBLE LINE 

• FLEXIBLE LINK PROPERTIES

• FLEXIBLE POINT PROPERTIES

• FLEXIBLE ROUTE

• GROUPE OF ENTITIES  

• GROUP OF LINE 

• LINE 

• NETWORK

• ROUTE LINK

• ROUTE POINT

• SCHEMATIC MAP

• SITE CONNECTION

• TARIF ZONE

• TIMING POINT

• TRANSFER RESTRICTION

Cadre de version ‘NETEX_HORAIRE’

Organisation  et hiérarchie du cadre de version :

Dans celui-ci ne seront traités que des objets relatifs à l’aspect horaires des objets d’un jeu de données.

L'objet principal est le SERVICE JOURNEY (Course) qui liste des horaires: TIMETABLED PASSING TIME. L'objet NOTICE ASSIGNMENT permet également d'affecter des notes contenues dans le fichier commun.xml à des Courses. 

Dans le cas ou au moins un PASSENGER STOP ASSIGNMENT pointent des StopPlace (ZDL) l’import peut utiliser l’objet VEHICLE JOURNEY STOP ASSIGNMENT. Celui-ci peut modifier le passage de la course associée pour définir si besoin des arrêts spécifiques de type ZDEP référencés par la balise QuayRef.

Si la course référencée par la balise VehicleJourneyRef n’est pas trouvée dans l’offre importée, une erreur est ajoutée à l’import.

Si l’arrêt référencé par la balise QuayRef n’est pas trouvé dans le référentiel d’arrêts, un warning est ajouté à l’import.

Il reprend l'exemple présenté dans le chapitre précédent et indique une façon de représenter deux SERVICE JOURNEY (courses) avec des calendriers différents, associées à un même SERVICE JOURNEY PATTERN (mission).

*Interdiction de trafic local au sein de CERGY

1 : Ne circule pas le 14 juillet
Description de la Frame NETEX_HORAIRE

Objets pris en compte par le BO Offre Théorique :
SERVICE JOURNEY (Course) : le mouvement planifié d'un véhicule de transport public effectué un DAY TYPE (Type de Jour) donné, depuis un point début à un point fin d'un SERVICE JOURNEY PATTERN (Mission) sur une ROUTE (Itinéraire). Le SERVICE JOURNEY (Course) est donc l'instanciation d'un SERVICE JOURNEY PATTERN (Mission) donné, auquel on va attribuer des heures de passage aux arrêts et des jours d'application.

NOTICE ASSIGNMENT - inclus dans SERVICE JOURNEY : affectation d'une NOTE à un objet (ici pour signaler une exception sur un SERVICE JOURNEY (Course)). 

TIMETABLED PASSING TIME - inclus dans SERVICE JOURNEY: Donnée temporelle théorique relative au passage d'un véhicule de transport public à un POINT IN SERVICE JOURNEY PATTERN (Point sur Mission) donné sur un SERVICE JOURNEY (Course) et pour un DAY TYPE (Type de Jour)

*Dans le cas du changement d'heure, si des courses débutent à l'ancienne heure et s'achèvent après le changement d'heure, tous les ArrivalTime et DepartureTime doivent être sur le système du premier horaire de la course (système pré-changement d'heure).

VEHICLE JOURNEY STOP ASSIGNMENT : Il permet de définir si besoin des arrêts spécifiques de type ZDEP référencés par la balise QuayRef pour une course.

Objets ignorés dans le cadre de version 

La présence d’un objet de l’un de ces types ne perturbe pas l’import si la grammaire XML et XSD NeTEx est respectée ; toute erreur XML ou XSD provoque l’interruption de l’import de la ligne et son rejet. :

• FLEXIBLE SERVICE PROPERTIES

• HEADWAY JOURNEY GROUP

• JOURNEY PART

• RHYTHMICAL JOURNEY GROUP

• SERVICE JOURNEY INTERCHANGE

• TEMPLATE SERVICE JOURNEY

• TRAIN

• VEHICLE TYPE

Interface d’import 

Règles de gestion relatives à l’import : 

• Pour le BO Offre Théorique :

• Les jeux de données importés seront restreints à une période calendaire maximale autorisée à compter du jour de l’import (actuellement fixée à 1 ans). Les calendriers sortants de cette période seront tronqués et s’ils se réduisent à aucun jour valide, ils ne seront pas importés, de même que les objets de l’offre qui leur sont strictement rattachées (courses, missions, itinéraires). 

• De même, un début de période inférieur à la date T du jour sera tronqué au-delà d’une limite d’un nombre de jours (ce seuil sera fixé par Ile-de-France Mobilités). Une alerte simplifiée précisera la réduction du jeu de donnée à l’import. 

• Si au final, aucune donnée n’est importée, le jeu de données sera rejeté.

• Les données importées sont regroupées dans un fichier ZIP, la taille de celui-ci ne devra pas excéder 80Mo. 

Import via l’IHM

Lors d’un import manuel par l’IHM, l’opérateur doit fournir un fichier contenant l’offre à importer sous la forme d’un fichier ZIP tel qu’il est défini dans le chapitre B 1 Organisation des imports. Dans le cas de l'import Offre Théorique, le ZIP ne pourra contenir qu’une seule offre.

API RESTful pour les SI Fournisseurs

Cette API permet en particulier d’alimenter les espaces de travail via des opérations d’imports automatisés (ces espaces de travail vont contenir les jeux de données).

Lorsqu’un utilisateur fait un appel à l’API il est automatiquement authentifié et relié naturellement à une Organisation. Les Organisations n’apparaissent donc pas dans les URL de l’API. 

Une Organisation va contenir un Espace de travail pour la gestion de l’offre de transport.

Les ‘endpoints’ de l’API utilisent l’identifiant de l’espace de travail à impacter. Cette information est disponible dans l’interface IHM du BO Information Voyageur dans le menu Paramétrages > Sécurité .

Cet identifiant est accessible en même temps que les clés d’accès API comme ci-dessous.

Protocole

Les requêtes utilisent les différentes méthodes HTTP : 

• GET pour les consultations (collection ou ressource) 

• POST pour la création de ressource

Toutes les requêtes retournent :

• un code HTTP 200 (OK) : en cas de succès

• un code HTTP 400 (Bad Request) : lorsque des paramètres sont inconnus.  

• un code HTTP 406 (Not Acceptable) : lorsque les données fournies ne permettent de traiter la demande

• un code HTTP 500 (Internal Server Error) : en cas d’erreur indéterminée

Les chapitres suivants ne détailleront que les requêtes avec un code de réponse HTTP 200 apportant une information supplémentaire.

Les URL des requêtes HTTP font apparaître différentes parties variables obligatoires pouvant avoir différents contenus. Ils peuvent ou non appartenir à une liste de valeurs autorisées et sont notées entre { }. 

Exemple : http://mon_domaine/{mes_ressources} : la partie {mes_ressources} nécessite de renseigner une chaîne non vide. 

Sécurité

L’authentification est réalisée en utilisant une “basic authentification” comme définit par la RFC2617. L’appelant doit utiliser :

• le code de son organisation comme utilisateur,

• une clé d’accès d’API associée à son organisation comme mot de passe. 

Tous les accès à l’API se font en HTTPS.

Le code de l’organisation est celui défini dans Sésame. Il se retrouve dans IBOO via le menu Paramétrages > Mon organisation. 

Les clés d’accès d’API sont paramétrables par Ile-de-France Mobilités et les transporteurs dans le BO Offre. Celles définis dans une organisation sont ensuite accessibles des utilisateurs de l’organisation pour qu’ils puissent accéder aux API d’import. Une clé d’accès d’API peut également être communiqué à des personnes tierces pour qu’elles puissent également accéder à ces API.

Exemple d’une requête curl : 

curl --basic --user organisation-code:bae26d4c1a358c7fdaf7b5e1277e5219

Import

Un import se caractérise par : 

Créer un import : 

Méthode http

POST

Url de la requête :

    URL BO Information Voyageur /workbenches/{id}/imports.json

• id : Identifiant de l’espace de travail

La requête POST allant être transmise est une requête « multipart ». 

Les attributs de cette requête sont les suivants : 

• name: nom de l’import [obligatoire]

• file: fichier à importer [obligatoire]

• options:

  • automatic_merge: booléen permettant de définir si la finalisation s’effectue automatiquement après un import réussi.

Pour soumettre des attributs dans form-data il faut utiliser la syntaxe workbench_import[attribute name], par exemple workbench_import[name].

Exemple d’une requête curl : 

curl -X POST --basic --user organisation-code:bae26d4c1a358c7fdaf7b5e1277e5219 \

• F "workbench_import[name]=Test" -F "workbench_import[options][automatic_merge]=true" -F "workbench_import[file]=@netex.zip;type=application/zip" \

  https://iboo.iledefrance-mobilites.fr/api/v1/workbenches/218/imports

Attention : Si un jeu de données existe avec le statut “Ready” sur les même lignes et périodes, l’import va échouer avec cette erreur : Le référentiel abc n'a pas pu être créé car un référentiel existe déjà sur les mêmes périodes et lignes:xyz

La solution la plus simple pour débloquer la situation est d’archiver le jeu de données en question sur l’interface d’IBOO

Réponse : 

HTTP 200 (OK) : la demande est acceptée et retourne notamment l’identifiant de l’import et son état

Exemple de réponse : 

{

  "id": 559,

  "status": "running",

  "workbench_id": 218,

  "referential_id": null,

  "name": "Test",

  "created_at": "2019-10-07T08:57:22.131+02:00",

  "updated_at": "2019-10-07T08:57:22.131+02:00",

  "started_at": "2019-10-07T08:57:22.146+02:00",

  "options": {"automatic_merge": true},

}

Obtenir la liste des imports d’un espace de travail d’une Organisation : 

Méthode http

GET

Url de la requête

    URL BO Information Voyageur /workbenches/{id}/imports.json

• id : Identifiant de l’espace de travail

Exemple d’une requête curl : 

curl -X GET --basic --user organisation-code:bae26d4c1a358c7fdaf7b5e1277e5219 https://iboo.iledefrance-mobilites.fr/api/v1/workbenches/218/imports.json

Réponse : 

    HTTP 200 (OK) : la demande est acceptée et retourne la liste des imports d’un espace de travail 

Exemple de réponse : 

  [ {

    "id": 12384984,

    "name": "import 1",

    "status": "running",       

    "referential_ids": [892428, 8256828], 

    },

  {

    "id": 3302929,

    "name": "import 2",

    "status": "running",   

    "referential_ids": [892728, 8223828], 

}]

Récupérer un import par son code : 

Méthode http

GET

Url de la requête

    URL BO Information Voyageur /workbenches/{id}/imports/{code_import}.json

• id : Identifiant de l’espace de travail

• code_import : clé permettant d’identifier l’import (id)

Exemple d’une requête curl : 

curl -X GET --basic --user organisation-code:bae26d4c1a358c7fdaf7b5e1277e5219 https://iboo.iledefrance-mobilites.fr/api/v1/workbenches/218/imports/12384984.json

Réponse : 

    HTTP 200 (OK) : la demande est acceptée et retourne le détail d’un import de l’espace de travail avec son identifiant et son état

Exemple : 

  {

    "id": 12384984,

    "name": "import 1",

    "status": "running",   

    "referential_ids": [8 {

    "id": 12384984,

    "name": "import 1",

    "status": "running",   

    "referential_ids": [892428, 8256828], 

    }92428, 8256828], 

    }