# 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:

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

        <datefinalisationinscription>10/07/24</datefinalisationinscription>
        <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.

### Champs spécifiques à Apogée

Les champs suivant sont optionnels et donnent des informations spécifiques à
Apogée:

```xml
        <cod_stu>01</cod_stu>
        <cod_rgi>1</cod_rgi>
        <tem_brs_iaa>O</tem_brs_iaa>
        <eta_edt_crt>E</eta_edt_crt>
        <dat_edt_crt>10/07/24</dat_edt_crt>
        <cod_pru>NO</cod_pru>
        <cod_dip>VBTCYB</cod_dip>
        <cod_etp>V2CYB</cod_etp>
        <tem_rgl_sit_mil>O</tem_rgl_sit_mil>
```

Notes :

- `dat_edt_crt` est en principe la même chose que `datefinalisationinscription`:
  ce champ est vide si l'étudiant n'a pas finalisé son incription.


## 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
<?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é.