DocScoDoc/docs/InterrogationPortail.md

#  Interface avec un "portail" externe 
ScoDoc peut interagir avec un "portail" donnant des informations sur les étudiants.
Ceci permet de synchroniser les données ScoDoc avec celles des applications
externes comme Apogée. Pour simplifier l'administration, nous avons fait le choix
d'intercaler entre ScoDoc et les applications type Apogée un "portail"
(centralisation des autorisations, etc).

Le portail interroge aussi ScoDoc (en particulier pour la publication des bulletins et pour
effectuer l'export des décisions de jury vers Apogée). Voir les services offerts par ScoDoc 
sur la page [ServicesXml](ServicesXml.md).

L'adresse du portail est indiquée dans la préférence ```portal_url``` (voir [PreferencesScoDoc](PreferencesScoDoc.md)).

Le code d'interface est dans le fichier source `sco_portal_apogee.py`.

Les trois appels suivants sont utilisés:

 * `getEtud` : information sur un étudiant

 * `getEtapes` : liste des étapes Apogée

 * `getPhoto` : image de l'étudiant

Ces appels sont détaillés dans les sections suivantes.


###  Information sur un étudiant 
Le portail doit fournir une méthode web `getEtud.php` qui accepte les paramètres suivants:

 - `nip` : code NIP

 - `ine` : code INE
 
 - `mail` : adresse e-mail

 - `nom` : nom de l'étudiant

 - `prenom` : prénom de l'étudiant

 - `etape` : code étape Apogée

On peut spécifier un nombre quelconque de paramètres; `getEtud.php` recherche les étudiants
correspondant aux critères indiqués, et renvoie du code XML:
```
<etudiants>
    <etudiant>
        <nip>20600577</nip>
        <etape>V2TR</etape>
        <inscription>2008</inscription>
        <nom>BOURTON</nom>
        <prenom>MELANIE</prenom>
        <gender>F</gender>

        <naissance>08/01/1990</naissance>
        <ville_naissance>Brest</ville_naissance>
	<code_dep_naissance>29</code_dep_naissance>
	<libelle_dep_naissance>Finisterre</libelle_dep_naissance>

        <mail>melanie.bourton@xxx.univ-yyy.fr</mail>
        <address>11 Pierre Dupont</address>
        <postalcode>93400</postalcode>
        <city>Tokyo</city>
        <country>France</country>
        <phone>01 02 03 04 05</phone>
        
        <lycee>0951722F</lycee>
        <bac>S-Scientifique</bac>
        <mention></mention>
        <anneebac>2007</anneebac>

        <nom_lycee>nom du lycée</nom_lycee>
	<ville_lycee>ville lycée</ville_lycee>
	<codepostal_lycee>code postal lycée</codepostal_lycee>

        <paiementinscription>true</paiementinscription>
	<bourse>N</bourse>

    </etudiant>
    <etudiant>
       ...
    </etudiant>
  ...
</etudiants>
```

Les champs `<lycee>` (code du lycée), `<bac>` (intitulé du bac), `<mention>`, `<anneebac>` et `<paiementinscription>` sont optionnels.

Le champ `<bac>` est un libellé, en général de la forme "ES-Economique et social". ScoDoc considère la première partie du libellé, jusqu'au caractère '-' comme la série du bac (uniquement si elle fait moins de 8 caractères). Le reste est alors considéré comme la "spécialité" du bac. Voir [DonneesAdmissions](DonneesAdmissions.md).

Le champ `<paiementinscription>` (optionnel) vaut "true" ou "false" pour indiquer si l'étudiant a réglé ses frais d'inscription ou non.


###  Liste des étapes Apogée 
`getEtapes.php` (pas de paramètres) renvoie un doc XML décrivant les étapes Apogée en cours. L'URL est paramétrable dans les préférences de ScoDoc. 
La structure est la suivante:
```
<?xml version="1.0" encoding="UTF-8"?>
<etapes>
        <cj>
                <etape code="V1XY">DUT CJ - Première Année</etape>
                <etape code="V2XY">DUT CJ - Seconde Année</etape>
                ...
	</cj>
        <rt>
                <etape code="V1RT">DUT RT - Première Année</etape>
                <etape code="V2RT">DUT RT - Seconde Année</etape>
                ...
        </rt>
        ...
</etapes>
```
Le code département (cj ou rt dans l'exemple ci-dessous) est arbitraire et utilisé par ScoDoc pour ne présenter à l'utilisateur que les étapes de son département (voir la propriété *code du département sur le portail* dans les paramètres). 

On peut aussi présenter une liste sans section par département, comme ceci: (cocher la préférence indiquant le format dans ScoDoc)
```
<?xml version="1.0" encoding="UTF-8"?>
<etapes>
         <etape code="V1XY">DUT CJ - Première Année</etape>
         <etape code="V2XY">DUT CJ - Seconde Année</etape>
          ...
</etapes>
```

###  Image de l'étudiant 
`getPhoto.php` accepte le paramètre suivant:

 - `nip` : code NIP

et renvoie une image de l'étudiant (dans l'un des formats supportés par les navigateurs web).
Si l'image ou l'étudiant n'existe pas, un code HTTP 404 peut être renvoyé.