Version française

logo Keyclic

Service Keyclic Documentation

Keyclic is a rise and process feedback app. It allows its users to signal malfunctions, technical problems or every other type of problem to the right organizations.

Content

Overview

General purpose

The Keyclic app is free and open to registration. Once registered, a user can create feedbacks. A feedback is always linked to a geographic point and may contain one or more pictures.

Users can join or create an organization. This a group of users from the same company, school, association, etc.

Administrators define places where their organization can act and categories (example: road network, lost animal, cleaning, etc). Thus, when a user creates a feedback, the app will display organizations able to deal with the problem and their category and let him choose which organization corresponds the most.

When a user created a feedback, he may choose to make it public or private. If public, the feedback will be visible by the entire community and they can comment it or support it.

Furthermore, the moment the feedback is send, a report is created and transmitted to the chosen organization.

A report corresponds to one and only one feedback. An admin has access to all the reports sent to its organization. For each reports, he can create has many operations as necessary and assign them to members of his organization. Another way is to delegate the report to a partner organization that will deal with it Once every operation resolved, the admin will then close the report and consider the problem resolved.

Vocabulary

Feedback

Observation made by a user. It may be a technical problem, a malfunction, a nuisance, etc. Every feedback is made with coordinates from the geolocation. It may contain pictures, be commented and/or be supported.

See Feedbacks.

Report

Each feedback can create a report. A report contains the informations from the feedback and can only be seen and modified by the organization it was sent to. The report is the “professional” side of the observation. The organization works from this report: creation of operations, state, delegation, etc.

See Reports

Organization

Group of users. It may be a company, a school, an association, a group of worker on a construction site, etc.

See Organizations.

Places

Geographic area where an organization can take action.

See Manage places.

Category

Business sector of an organization.

See Manage categories.

Contribution

A feedback may be supported by other users of the community, to give it more value.

See Contributions.

Operation

Task created by an admin on a report. This task is assigned to a member of the organization.

See Operations.

Relationship

An admin can choose partner organizations (with mutual consent), which are other organizations he will be able to delegate reports.

See Manage partnership.

Technical considerations

The Keyclic API is RESTful. Every operation is sent through HTTPS and is secured with JSON Web Tokens. The data is sent only in JSON format.

The Keyclic API’s domain name is :

api.keyclic.com

Applications and Application’s key

Every client of the API must send a key identifying his application in the request header

If you are developing a client to work with an existing Keyclic application, you have to know the application’s key. Else if you wish to develop a client for a new application, please contact Keyclic. They will create the new application, configure it and send you the corresponding key.

Examples of an application’s key :

  • com.keyclic.app
  • com.keyclic.city
  • com.keyclic.highway

Then every request header has to contain a X-Keyclic-App field with a value like the examples above. Refer to this paragraph Requests for the “implementation”.

However, users accounts are shared to all Keyclic applications. Therefore, login and register endpoints do not require to provide an application key (cf : Authentication and connection).

Requests

In this documentation, each API’s endpoint will be described by an HTTP verb and the path to access the resource.

Example :

GET /feedbacks

This endpoint returns every feedback. Its actual URL is

https://api.keyclic.com/feedbacks

but to avoid redundancy, in the following examples, we will show neither the protocol nor the domain name.

URL’s parameters

In this documentation, URIs variables, such as a resource identifier, a page number, etc, will be between curly brackets. For example, to retrieve a single feedback :

GET /feedbacks/{feedback}

In the Keyclic API, in accordance with REST principles, the filtering parameters will always be in the query string. Example :

GET /feedbacks?page={page}

Moreover, for a better visibility, URI’s parameters will be written as such and not in their encoded URL form :

GET /feedbacks?before=2018-04-22T01:00:00+05:00
Headers

Besides conventional HTTP/1.1 headers, Keyclic API accepts and in most cases requires, the header X-Keyclic-App, corresponding to the application used (see above : Applications and Application’s key). For example, to get all feedbacks from the com.keyclic.app application, the request will have to contain the following header :

X-Keyclic-App : com.keyclic.app

Every endpoint requires this header, except for login and password modification. (refer : Authentication and connection)

Also, every request (except login, register and password modification) must contain the Authorization header (see : Authentication and connection).

Request and response format

The only type of content accepted by the Keyclic API is JSON. Requests must contain the header :

Content-type: application/json

and the body will always have to in JSON format. The responses are returned to the JSON format too.

Send files

Files are sent in base 64 to the API. Here is an example of adding an image to a feedback :

POST /feedbacks/{feedback}/images
{
    "image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAIAAAACDbGyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIVDRUfvq7u+AAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAUSURBVAjXY3wrIcGABJgYUAGpfABZiwEnbOeFrwAAAABJRU5ErkJggg=="
}

Resource modification

In the Keyclic API, resource modification is made with the PATCH method. Unlike the PUT method, PATCH allows to modify a single or some properties of a resource without sending every property of the modified resource.

Here is an example to change the property billingEmailAddress of an organization :

PATCH /organizations/{organization}
{
                "billingEmailAddress": "test@test.com"
    }

Errors

Every error send a code 4xx representing the type of error.

When an code 400 (Bad Request) is returned, the reasons are sent.

Errors follow the format vdn.error.

The following example displays a validation error.

{
   "@context":"https://github.com/blongden/vnd.error",
   "@type":"ValidationError",
   "message":"Validation failed.",
   "total":1,
   "_embedded":{
      "errors":[
         {
            "@context":"https://github.com/blongden/vnd.error",
            "@type":"Error",
            "message":"Cette valeur ne doit pas \u00eatre vide.",
            "path":"reporter"
         }
      ]
   }
}

The field path indicates which property triggered the error (here: reporter), and the field message explains the error.

State change

Several resources of the API possess a life cycle and a state for a given moment. Those resources are feedbacks, reports and operations.

For these resources, the state is always indicated in the response with the field state, and the next possible actions to change this state are displayed in the parameter stateTransitions. Example :

GET reports/{report}

Response (partial) :

{
  "type": "Report",
  "id": "cb7118b5-a821-4cf2-9475-0c0d0efdb8d0",
  "state": "NEW",
  "_embedded": {
    "stateTransitions": [
      "accept",
      "refuse"
    ]
  }
}

In the example above, the report has a state NEW and the possible actions on its state are accept and refuse.

Actions on the state of a resource is made through the POST method, with the path and the new value.

For example, to accept a report :

POST /reports/{report}/workflow/transition
{
                "transition": "accept"
}

This request will send the following response :

{
  "type": "Report",
  "id": "32219286-528a-4f97-b81e-fe7a8cb85707",
  "state": "ACCEPTED",
  "_embedded": {
    "stateTransitions": [
      "refuse",
      "hold",
      "progress"
    ]
  }
}

The report’s state is now ACCEPTED, and the next actions are refuse, hold and progress.

Actions and states for each kind of resource are described in the appropriate sections of the documentation.

Authentication and connection

The Keyclic API uses the JSON Web Tokens to secure data transfer. Every request to the API is made with an access token allowing the server to verify the user’s identity. When logging in, the user “receives” the token. This page goes through the process of creating an account, modifying an account, getting and using an accessToken.

For more informations on JWT standard, see : JSON Web Tokens official website.

Create a user account

A new user account is created with this request :

POST /security/register
{
    "email":"test@test.com",
    "password":"test"
}

This user gets a unique id and the role ROLE_USER, allowing him to use the API’s basic functionalities.

Log in

Log in consists in sending one’s credentials to the server to get an accessToken which will be used in future requests.

The connection is done with this request:

POST /security/login
{
    "login":"test@test.com",
    "password":"test"
}

If the credentials are known to the server, it returns an accessToken.

Use the token

Almost every single request to the API needs the user to be authenticated. The token is sent with the Authorization header with the prefix Bearer.

For example, to get the list of all feedbacks of the com.keyclic.app application, a user uses the endpoint :

GET /feedbacks
Request headers :
    X-Keyclic-App : com.keyclic.app
    Authorization : Bearer eyJhbGciOiJSUzI1NiJ9.eyJyb2xlcyI6WyJPUkdBTklaQVRJT046QURNSU4iLCJST0xFX1VTRVIiXSwidXNlcm5hbWUiOiJ0ZXN0MjJAdGVzdC5jb20iLCJpcCI6Ijc3LjIwMy40NS40NCIsImV4cCI6MTQ4OTI0MTQ0NCwiaWF0IjoxNDg5MTU1MDQ0fQ.ZIqbBVSgJaXKj73IPYbFeEfie6FUIflv-ausUO-AAzVjPg8-jdhFv3nqsdOVJvE_AB4bXjME1CRVFI7xD2SYCA8V6E6H2-y0XZE8SN_XTpHGMxDvOP27C2VUNQfPwgeWxjXzlDopo_U9ybAEX4QdFhW14aeRgb9YWMDlzSD6VLgJO-LuprxX668Ajq5X9c8YND4D_p4WRDSQr8pqb3rTY9NQ6O34F-OpDJlAUYj0pwMehYWpywVKJHRMv9xCRRoI8HrU6H3J3wo-K2OtQVJi9XFZ8g8sohw_ZaasG7dohxrO-NtYSrOPXIXPI6kCDRuMi7sce06wfno1bC3jBoc83EhiBSBpDbWL98DSjPbF1SaCeE05aATfM5cMEXbnp8Iwh-QLxglE4M-ZISJ8VooxzJxa7cWLlFW-iu0XWVFWrMbYgmSoU0PKRQB47w_IOPxjWzDeMUTSA3esDwkxsYlNdS9SZe201EvI6zur5Ayot0PEGfAgex6Ew-eKOHAfnuDiqeLQLbWs4Y69FO2DooWUhkfVGdl-IGglDPgk2AOs3w19e7mx-Gmm8DlUUr-bK61NPPQ8dy7HPjXnU63-jbA17MAjHaRTO4eKopcZMWbpL-jgQjJltV3R5_0qNODaHCS_auZs2cyqFN0HL9Rred5g7t6Fxyk-8MyyX0GiTyHsp3c

All requests to the Keyclic API need an accessToken in the headers, except for the following endpoints :

  • create an account (POST /security/register)
  • log in (POST /security/login)
  • password change request (POST /security/password/change-request)
  • password change (POST /security/password/change/{changePasswordToken})

Password change

A user who wishes to modify his password performs the next steps.

First, he sends a request to change his password :

POST /security/password/change-request
{
    "email":"test@test.com"
}

This request sends an email to the user with a link ending with a verification token. Example :

https://domain.com/#/password-reset/jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA

In the link above, jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA is the token to be sent in the next request. This part of the URL https://domain.com/#/password-reset/ depends on the application used.

Then the user can change his password with :

POST /security/password/change/jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA
{
    "password":"newPassword"
}

Editing user data

For data other than the password, the user will request on this endpoint :

PATCH /people/{user}

For more information on PATCH request, see Resource modification.

For example, to change its last name :

{
    "familyName": "Family name"
}

A user can change the following data : his familyName, his givenName, his image, his job and his email.

Organization members and roles

When a user is part of an organization, he may receive from none to five roles, which define a set of permissions and possibles actions.

These are five roles :

  • Administrator
  • Agent
  • Operator
  • Analytic
  • Export

A user may be part of several organizations, therefore his roles among the organizations may differ and are completely independent. A user who gets affiliated with an organization becomes a member. A member possesses the same basic functionalities as a simple user.

Administrator

Every user can create his own organization.

The user who created the organization becomes member and admin of that organization, his role is Admin.

The admin has the following permissions and privileges :

  • Add new members,
  • Change members’ roles,
  • Manage the organization’s categories,
  • Manage the organization’s places,
  • Manage the organization’s partners,
  • Consult and manage reports received and operations linked to these reports.

See : Organizations

See : Reports

Note : A user can be ORGANIZATION:ADMIN of several organizations and an organization can have several ORGANIZATION:ADMIN.

Agent

« Agent » is a special role suitable to members who only make feedbacks for their organization.

An agent has the possibility to :

Note : A user can only be an ORGANIZATION:AGENT of one organization but an organization can have several ORGANIZATION:AGENT.

Operator

This role adds the following possibilities :

  • Receive an assignment to an operation,
  • Edit an operation (if assigned to that member) : change name, add pictures, change state, etc.

All members share those rights and other may stack if the member has more roles.

Note : An ORGANIZATION:OPERATOR can be member of several organizations and an organization can have several ORGANIZATION:OPERATOR.

Analytics

The role Analytics allows the member to access the organization statistics.

Note : A user can have the role ORGANIZATION:ANALYTICS for several organizations and an organization can have several members with the role ORGANIZATION:ANALYTICS.

Export

The role Export allows the member to export his organization’s reports to the Excel format.

Note : A user can have the role ORGANIZATION:EXPORT for several organizations and an organization can have several members with the role ORGANIZATION:EXPORT.

Retrieving users

To get all of the application’s users :

GET /people

To get a specific user :

GET /people/{user}

To filter users by pattern in email :

GET /people?search[email]=martin

To get members of an organization :

GET /organizations/{organization}/members

Example

Retrieving a user resource will display information about his membership(s), like the organization he is a part of, what roles he has and other miscellaneous details.

GET /people/5020c6ea-ca07-42d1-994f-d90b86703b1a/memberships
{
    "page": 1,
    "limit": 10,
    "pages": 1,
    "total": 1,
    "_links": {
        "self": {
            "href": "/people/5020c6ea-ca07-42d1-994f-d90b86703b1a/memberships?page=1&limit=10"
        },
        "first": {
            "href": "/people/5020c6ea-ca07-42d1-994f-d90b86703b1a/memberships?page=1&limit=10"
        },
        "last": {
            "href": "/people/5020c6ea-ca07-42d1-994f-d90b86703b1a/memberships?page=1&limit=10"
        }
    },
    "_embedded": {
        "items": [
            {
                "id": "b0e7e28f-5b91-4c73-875e-8f34aa03553a",
                "roles": [
                    "ORGANIZATION:AGENT"
                ],
                "createdAt": "2018-02-27T10:00:00+02:00",
                "_links": {
                    "self": {
                        "href": "/organizations/84d36093-b8bc-47ad-bc8a-a043b3e301a9/members/b0e7e28f-5b91-4c73-875e-8f34aa03553a",
                        "iriTemplate": {
                            "mapping": {
                                "organization": "84d36093-b8bc-47ad-bc8a-a043b3e301a9",
                                "member": "b0e7e28f-5b91-4c73-875e-8f34aa03553a"
                            }
                        }
                    },
                    "person": {
                        "href": "/people/5020c6ea-ca07-42d1-994f-d90b86703b1a",
                        "iriTemplate": {
                            "mapping": {
                                "person": "5020c6ea-ca07-42d1-994f-d90b86703b1a"
                            }
                        }
                    },
                    "organization": {
                        "href": "/organizations/84d36093-b8bc-47ad-bc8a-a043b3e301a9",
                        "iriTemplate": {
                            "mapping": {
                                "organization": "84d36093-b8bc-47ad-bc8a-a043b3e301a9"
                            }
                        }
                    }
                },
                "_embedded": {
                    "availableRoles": [
                        "ORGANIZATION:ADMIN",
                        "ORGANIZATION:ANALYTICS",
                        "ORGANIZATION:EXPORT",
                        "ORGANIZATION:READ_ONLY"
                    ]
                }
            }
        ]
    }
}

This json shows the user :

  • is a member of an organization whose id is 84d36093-b8bc-47ad-bc8a-a043b3e301a9
  • has the role ORGANIZATION:ADMIN : he is an admin of the organization 84d36093-b8bc-47ad-bc8a-a043b3e301a9
  • has the role ORGANIZATION:AGENT : he is an agent of the organization 84d36093-b8bc-47ad-bc8a-a043b3e301a9
  • is part of only one organization
  • joined the organization February 27, 2018

CAUTION: The user id (5020c6ea-ca07-42d1-994f-d90b86703b1a) is not the same as the member id (b0e7e28f-5b91-4c73-875e-8f34aa03553a). The API identifies a member and a user as two differents entities.

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":"test@test.com",
    "notificationEmailAddress":"test@test.com"
}

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.

Feedbacks

A feedback is always made in a given geographic point. This point is the most important and only mandatory component of a feedback. Optional parameters are the description, category, visibility and picture(s).

All users can make feedbacks.

Creation

POST /feedbacks/issues

Minimal example of a feedback:

{
    "businessActivity": "4bff7cb9-0fd2-4b44-9b0e-f6d17bb4ef36",
    "geo": {
        "elevation": 1,
        "point": {
            "latitude": 44.851343,
            "longitude": -0.576326
        }
    }
}

Complete example:

{
    "businessActivity": "4bff7cb9-0fd2-4b44-9b0e-f6d17bb4ef36",
    "category": "b0d007d5-e6ad-4113-b2b5-d8a1858a2fb1",
    "description": "Mon feedback 5",
    "geo": {
        "elevation":1,
        "point": {
            "latitude":44.851343,
            "longitude":-0.576326
        }
    },
    "visibility": "VISIBILITY_PUBLIC"
}

The default visibility of the observation is VISIBILITY_PRIVATE if this one is not provided in the payload.

Then the user can add one or more pictures to his feedback:

POST /feedbacks/{feedback}/images
{
    "image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAIAAAACDbGyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIVDRUfvq7u+AAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAUSURBVAjXY3wrIcGABJgYUAGpfABZiwEnbOeFrwAAAABJRU5ErkJggg=="
}

For more informations on adding images, see Send files.

Match with an organization

The Keyclic service doesn’t just collect feedbacks, it sends them if possible, as Reports, to organizations capable of treating the feedback. Three cases are possible when transmitting a feedback :

  • If the feedback’s coordinates aren’t in a place, then no organization will receive a report on this feedback.
  • If the feedback’s coordinates are in a place, then the report is sent the the organization in charge of the place.
  • If the feedback’s coordinates are in a place where two or more organizations can take action, and the user didn’t specify a specific business activity, then several reports are generated and sent to all organizations in the place. The first one to accept will treat the problem.

For more informations about places, see Manage places.

Feedbacks by an agent

An Agent can post feedbacks the same way as every user. What’s more, an agent can enter in “pro mode”. To do so, just put in the body of the request, the “proMode” field with the value “true”. Thus, his feedback will be treated differently:

  • If his feedback is within a place of his organization, a report is created.
  • If his feedback is outside a place of his organization, then the feedback is refused.

Normal mode vs “Pro mode”

On the figure below, square A represents a place belonging to organization A, and square B to organization B.

Each dot is a feedback made by a member of organization B.

  • In blue: feedbacks made in normal mode.
  • In red: feedbacks made in pro mode (pro mode set to true in the request).
_images/feedback_by_place.png

Life cycle overview

_images/feedback_workflow.png

Get feedbacks

To get feedbacks, request the following endpoint:

GET /feedbacks

This request only returns feedbacks whose state is DELIVERED.

Some criteria may help filter feedbacks.

By state: state parameter

For example, to filter delivered feedbacks, a user will send the request:

GET /feedbacks?state=DELIVERED

Around a point: geo_near parameter

Example:

GET /feedbacks?geo_near[radius]=1000&geo_near[geo_coordinates]=+44.8-0.5

will return feedbacks within a 1000 meters radius from a point at latitude +44.8 and longitude 0.5.

Within a GeoHash: geo_hash parameter

Geohash is a public domain geocoding system […] which encodes a geographic location into a short string of letters and digits. (Source: Wikipedia)

For more informations on Geohash, see:

Feedbacks may be filtered with Geohash like this:

GET /feedbacks?geo_hash[]=ezzx&geo_hash[]=ezzz

This will return feedbacks between geohashes ezzx and ezzz.

By time period: before and after parameters

Example:

GET /feedbacks?after=2017-01-10T00:00:00+05:00&before=2017-02-22T23:59:59+05:00

will return feedbacks made between January 10 and February 22

Dates are written in the format: ISO 8601.

By organization

GET /feedbacks?organization={organization}

Comments

Users may comment feedbacks:

POST /feedbacks/{feedback}/comments
{
    "text": "My comment"
}

To get comments on a feedback:

GET /feedbacks/{feedback}/comments

Contributions

A user can also support a feedback this the following request, without body:

POST /feedbacks/{feedback}/contributions

To get all supports to a feedback:

GET /feedbacks/{feedback}/contributions

Reports

When a feedback is delivered (see : Life cycle overview), a report is created.

An Administrator gets all his organization’s reports with :

GET /organizations/{organization}/reports

And a specific report with :

GET /reports/{report}

Life cycle

When a new report is generated by a feedback, its state is NEW.

Below is a representation of each possible state for a report and the actions on that report leading to this state.

_images/report_workflow.png

There is a unique endpoint to change a report’s state :

PATCH /reports/{report}/state

For example, to change the report’s state from NEW to ACCEPTED, the admin will send the previous request with the following body :

{
    "transition": "accept"
}

A report can only be closed (state CLOSED), if every operation linked to this report has been either resolved or refused (see paragraph below Operations).

Operations

An operation is an action assigned to a member of the organization in relation with a report.

This endpoint sends back all operations resulting from a report :

GET /reports/{report}/operations

Creation and modification of an operation

An admin creates an operation on a report with this request :

POST /operations
{
    "description":"operation's description",
    "name":"operation's name",
    "report":"cb7118b5-a821-4cf2-9475-0c0d0efdb8d0"
}

A newly created operation has the state NEW.

One or more images can be added to an operation :

POST /operations/{operation}/images
{
    "image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAIAAAACDbGyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIVDRUfvq7u+AAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAUSURBVAjXY3wrIcGABJgYUAGpfABZiwEnbOeFrwAAAABJRU5ErkJggg=="
}

The description of an operation can be modified with the request :

PATCH /operations/{operation}
{
    "description": "New description"
}

Assignment

To assign an operation to a member, the admin sends the following request :

POST /operations/{operation}/assign
{
    "member": "{member}",
}

where {member} is the member’s id the operation is assigned to.

In progress and resolved operation

After being assigned, the operation will be changed to “in progress” then “resolved”, either by the assigned member or the admin.

Life cycle of an operation

_images/operation_workflow.png

Comments

It’s possible to comment an operation :

POST /operations/{operation}/comments
{
    "text":"My comment"
}

To get all comments on an operation :

GET /operations/{operation}/comments

Logs of an operation

An admin can see the history of an operation :

GET /operations/{operation}/logs

Delegation

An admin can delegate a report to a partner organization.

See : Manage partnership

To delegate a report, an admin sends the following request :

POST /organizations/{organization}/delegates
{
    "report":"cb7118b5-a821-4cf2-9475-0c0d0efdb8d0",
    "organization":"a31d9ab7-9476-45f2-8cc7-033bf40bbcfa"
}

where {organization} is the organization’s id delegating the report. And a31d9ab7-9476-45f2-8cc7-033bf40bbcfa is the receiving organization’s id.

This report is shared between the delegating organization and the receiving organization. The latter will treat this report the same has every other report.

The partner organization may itself delegate this report to one of its partners and so on.

Export

An admin can export every report from his organization to the Excel format:

POST /organizations/{organization}/reports/exports

An archive containing the Excel file listing all reports and the associated images will be emailed to the authenticated admin.

Applications

An application in the Keyclic service limits the resources to a single domain. It means the use of specific clients app or website. For the eponymous client of the service, the application is “com.keyclic.app”. Every client app and website using the key will share the same partition. (Here: the iPhone app Keyclic, the Android app Keyclic and the website https://app.keyclic.com)

Other applications exist in the Keyclic service with different keys, it’s the case of “Vinci Mon Autoroute” available on iPhone and Android.

For example, from “Vinci Mon Autoroute”:

  • it is impossible to “send” a feedback sent to this application with the key “com.keyclic.app” and vice-versa,
  • it is impossible to list feedbacks sent to the application with the key “com.keyclic.app” and vice-versa.

Notifications

The Keyclic service can notify users when some actions are made.

Notifications sent by action

Action Target Push Wall Mail
User register The user    
Password change request The user    
Feedback is commented

The user who made the feedback

Users who commented or supported to the feedback

 
Report is created Administrators
Report is accepted

The user who made the feedback

Users who commented or supported to the feedback

 
Report is closed

The user who made the feedback

Users who commented or supported to the feedback

 
Report is refused

The user who made the feedback

Users who commented or supported to the feedback

 
Report is delegated Administrators
Add document to report Administrators  
Operation assigned Member assigned to the operation
Operation resolved Administrator who created the operation  
Operation remind

Opertors

The user who made the feedback

 
Operation is commented

Member assigned to the operation Administrator who created the operation

Members who commented the operation

 
Feedback to review Reviewer  

When a user makes an action which triggers a notification where it would be targeted. This user doesn’t receive a notification. For example, if a member assigned to an operation leaves a comment on the operation, it doesn’t receive a notification saying it commented the operation.

Integration

Webhooks

Unlike an API that requires continuous requests, the Keyclic service offers webhooks when certain events occur (see list below).

It is an easy and efficient way to call a service or application to get notifications and break free from the constant check.

Webhooks have various uses, such as :

  • collect reports created for your data warehouse,
  • sync reports and operations with your IS (ex: CMMIS, …),
  • send notifications

Webhook creation and configuration

Webhooks can be created upon request from our service.

A webhook consists of the event for which you wish to be notified and a URL to where the notification should be sent.

Several webhooks can be created unlimitedly for each event type.

Event types

Event Description
reportCreated New report created
reportStateChanged Report’s state changed
operationCreated New operation created
operationStateChanged Operation’s state changed
operationRemoved Operation removed

Receipt of webhook notification

A webhook notification is sent in JSON format in the HTTP request body to the configured URL for that webhook. It contains the event name and a payload consisting of the resource details of the event. The resource varies according to the event.

note : The resource has the same serialization when requested to the API and in a webhook notification, it is possible to run through resources linked or embedded thanks to the HAL representation of our API.

{
    "event": "reportCreated",
    "payload": {
        "type": "Report",
        "id": "b0e7e28f-5b91-4c73-875e-8f34aa03553a",
        "state": "NEW",
        "createdAt": "2018-02-27T10:00:00+02:00",
        "updatedAt": "2018-02-27T10:00:00+02:00",
        "_links": {
            "feedback": "...",
            "operations": "...",
            "organization": "...",
            "tracking": "...",
        },
        "_embedded": {
            "stateTransitions": "...",
            "tracking": "..",
        }
    }
}

Partial example of a webhook notification received after the a new report is created.