Organizations

In the Keyclic app, an organization is an entity such as a company, a corporation, an association, a school, etc. to which feedbacks can be sent to be treated.

One or more members can be Administrator of that organization. An organization has at least one administrator.

An Administrator can manage the scope of operation of the organization by creating categories and places. When a user creates a feedback, geographic coordinates of that feedback are always automatically transmitted. Thus, the app can display all organizations in that place. Then the user has acces to information helping it choose the most fitting organization.

Creation

All users can create an organization :

POST /organizations
{
    "name":"organization name",
    "billingEmailAddress":"[email protected]",
    "notificationEmailAddress":"[email protected]"
}

The user becomes member and admin of this new organization.

To get all organizations of an application :

GET /organizations

It’s possible to filter results by geographic point (see below : Manage places) :

GET /organizations?geo_coordinates=+44.851404209987386-0.5762618780136108

Manage members

To add a new member to the organization :

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

This endpoint is reserved to a user who is Administrator and member of the organization {organization}.

To get organization’s members :

GET /organizations/{organization}/members

To remove a member from the organization, an admin will request :

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

Manage places

An Administrator can create places, corresponding to areas where the organization can take actions :

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

To get all places of the application :

GET /places

This request may be filtered by organization and/or geographic points :

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

Manage categories

Categories are the business sectors of an organization. An Administrator can create a new category with a name, a color and an icon. The icon is chosen from Font Awesome.

POST /organizations/{organization}/categories
{
    "name":"Category's name",
    "color":"#ff0000",
    "icon":"fa-bug"
}

Those 3 properties can be edited with a PATCH request (see : Resource modification).

To get all categories of the application :

GET /categories

This request may be filtered by organization and/or geographic points :

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

Manage partnership

An organization can have partners, i.e organizations affiliated with it. This relationship is one-sided : an organization A is a partner of organization B, but B is not necessarily one of B.

The partnership means that an Administrator can delegate a report to a partner organization. In the previous example, A can delegate a report to B, but B cannot delegate to A.

To add a new partner to the organization, an admin will send the request :

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

To get an organization’s partners :

GET /organizations/{organization}/relationships

The request is only available for admins.