Organisations

Dans l’application Keyclic, une organisation est une entité telle que corporation, entreprise, département d’entreprise, association, école, institution, etc à laquelle peuvent être rattachées les observations faites par les utilisateurs.

Un ou plusieurs membres d’une organisation peuvent en être les Administrateur. Une organisation possède au minimum un administrateur.

Les Administrateur peuvent définir les champs d’intervention de leur organisation en créant des catégories (exemple : voirie, transports, etc) et des zones de responsabilité. Quand un utilisateur crée une nouvelle observation, les coordonnées géographiques de cette observation sont toujours automatiquement précisées. Ainsi, l’application est en mesure de lui retourner l’ensemble des organisations qui ont une zone de responsabilité sur cette position. L’utilisateur a alors accès à des informations lui permettant de l’aiguiller vers l’organisation la plus adéquate.

Création d’une organisation

Tout utilisateur peut créer une nouvelle organisation :

POST /organizations
{
    "name":"Nom de l'organisation",
    "billingEmailAddress":"[email protected]",
    "notificationEmailAddress":"[email protected]"
}

L’utilisateur devient automatiquement membre et administrateur de cette nouvelle organisation.

Pour récupérer toutes les organisations de l’application :

GET /organizations

Il est possible de filtrer la requête ci-dessus sur un point géographique (voir ci-dessous : Gestion des zones de responsabilité) :

GET /organizations?geo_coordinates=+44.851404209987386-0.5762618780136108

Gestion des membres

Pour ajouter un nouveau membre à une organisation :

POST /organizations/{organization}/members
{
    "person":"63d07fc5-f4e6-471c-a8cc-3c3f227c8c2d"
}

Ce endpoint est réservé à un utilisateur possédant le rôle Administrateur et membre de l’organisation {organization}.

Pour récupérer les membres d’une organisation :

GET /organizations/{organization}/members

Pour retirer un membre d’une organisation, un Administrateur de cette organisation exécutera la requête :

DELETE /organizations/{organization}/members/{member}

Gestion des zones de responsabilité

Un Administrateur peut créer des zones de responsabilité, correspondant aux lieux sur lesquels cette organisation intervient :

POST /organizations/{organization}/places
{
    "name": "Test",
    "polygon":
    {
        "rings":
        [
            {
                "points":
                [
                    {
                        "longitude": 2.373991012573242,
                        "latitude": 48.84088179130599
                    },
                    {
                        "longitude": 2.3763084411621094,
                        "latitude": 48.84205393836751
                    },
                    {
                        "longitude": 2.376694679260254,
                        "latitude": 48.84189859515306
                    },
                    {
                        "longitude": 2.3787975311279297,
                        "latitude": 48.84041574931067
                    },
                    {
                        "longitude": 2.376115322113037,
                        "latitude": 48.839031720249054
                    },
                    {
                        "longitude": 2.373991012573242,
                        "latitude": 48.84088179130599
                    }
                ]
            }
        ],
        "srid": 4326
    }
}

Pour récupérer toutes les zones de responsabilité de l’application :

GET /places

La requête ci-dessus peut-être filtrée sur une organisation donnée et/ou sur un point géographique donné :

GET /places?geo_coordinates=+44.851404209987386-0.5762618780136108&organization={organization}

Gestion des catégories

Les catégories sont les secteurs d’activité d’une organisation. Un Administrateur peut créer une nouvelle catégorie en lui donnant un nom, une couleur et une icône. L’icône sera choisie dans le jeu d’icônes de Font Awesome.

POST /organizations/{organization}/categories
{
    "name":"Nom de la catégorie",
    "color":"#ff0000",
    "icon":"fa-bug"
}

Les 3 propriétés name, color et icon peuvent être éditées par une requête PATCH (voir : Modification de ressources).

Pour récupérer l’ensemble des catégories de l’application :

GET /categories

La requête ci-dessus peut-être filtrée sur une organisation donnée et/ou sur un point géographique donné :

GET /categories?geo_coordinates=+44.851404209987386-0.5762618780136108&organization={organization}

Gestion des partenariats

Une organisation peut avoir des partenaires, c’est-à-dire des organisations qui lui sont rattachées et à qui l”Administrateur de l’organisation pourra déléguer des rapports. La relation de partenariat est unilatérale : si une organisation A est partenaire d’une organisation B, B n’est pas forcément partenaire de A.

Pour ajouter un nouveau partenaire à l’organisation, un administrateur de l’organisation requêtera sur le endpoint :

POST /organizations/{organization}/relationships
{
    "organization":"84d36093-b8bc-47ad-bc8a-a043b3e301a9"
}

Pour récupérer les partenaires d’une organisation :

GET /organizations/{organization}/relationships

Cette requête ne peut être exécutée que par un administrateur de l’organisation.