Crowd-Sourcing Client Library

The crowd-sourcing module is part of enclosing csc-client library and provides communication with crowd-sourcing server. The basic functionality provides submition of an event, event listing, retrieving of server configuration, etc.

API

Commented source codes can be found on GitHub at src/cs/cs.js.

Dependencies

This library depends on jQuery and OpenLayers. Running instance of CrowdSourcing server side must be available.

Examples

Example 1

Before crowd-sourcing client can be used, a reference to corresponding server side must be defined. It can be achieved using the following code.

gsc.cs.csUrl("https://...");

Example 2

Crowd-sourcing server can be configured according to needs of its provider. It is good idea to get the server configuration before submitting other requests.

gsc.cs.getConfig().done(function(result) {
   ...

Server configuration is returned as an object with several properties, see next listing. Note, that one of the returned properties indicates whether user login is required or an anonymous access is allowed.

{
   "priorities": ["normal","low","high"],
   "statuses": ["submitted","assigned","solved","closed"],
   "mime_types": ["image/jpeg"],
   "tags": ["water rupture","sewage obstruction"],
   "login-required":true
}

Example 3

Logs in crowdsourcing server. Only some servers require the login. Use gsc.cs.getConfig() to determine if login is required. If login is omitted, user is treated as an anonymous. Value passed to the function is expected in the flowing form:

var data = {
   "user": {
      "id": "mole",
      "password": "molehill"
   }
};

gsc.cs.login(JSON.stringify(data)).done(function(result) {
   ...
}).fail(function(error) {
   ...

On successful login user details are returned. It contains user id, e-mail, organization name and list of user’s roles.

{
   "id": "mole",
   "email": "[email protected]",
   "organization": "Earth Moving",
   "role": ["admin"]
}

Example 4

Creation of an event consists of two parts: event meta-data and data. Meta-data contains information such as event identifier, description, media type, location, priority, creation time and status. If login is required, user name and password is also provided. The data contains image data. Both are put together by and passed to eventCreate() method.

var metadata = {
   "id": "8E6AC096-CA10-4295-AB64-1B48BAC9E4CD",
   "description": "An event with 1 attachment",
   "media": [{"mime-type": "image/jpeg", "uri": "part://1"}],
   "location": {
      "lat": 23.43,
      "lon": 33.1,
      "crs": "epsg:4326"
   },
   "priority": "normal",
   "datetime": "2016-08-16T10:48:23Z",
   "status": "submitted",
   "user": {
      "id": "mole",
      "password": "molehill"
   }
};    

var request = new FormData();
request.append('event', JSON.stringify(metadata));
request.append('part://1', IMAGE_DATA);
    
gsc.cs.eventCreate(request)

Example 5

Other users can comment submitted events. Note, that this method accepts event identifier as a separate parameter; it is not part of data object.

var data = {
   "text": "A new comment",
   "datetime": "2016-03-07T20:46:05Z"
};    

gsc.cs.eventComment(JSON.stringify(data), "88c828ad-b245-471e-91c2-30e7cafcd4ed")

Example 6

Event items can be modified. Attributes status and priority can be modified. Only administrator, i.e. user with “admin” role, may use the method.

var data = {
   "id": "88c828ad-b245-471e-91c2-30e7cafcd4ed",
   "user": {
      "id": "mole",
      "password": "molehill"
   },
   "priority": "high",
   "status": "solved"
};

gsc.cs.eventUpdate(JSON.stringify(data));

Example 7

Sometimes it is necessary list events available on the server. It can be done using the following code.

gsc.cs.eventListFilter().done(function(result) {
   ...

Result has a form of an array of objects of the following structure:

[
   {
       "datetime":"2015-12-07T00:00:00",
       "description":"An event with 2 attachments",
       "location":{"crs":"epsg:4326", "lon":33.099998474121094, "lat":23.43000030517578},
       "id":"7ecf5387-9af7-4f8a-a663-a08a8fab16b3",
       "priority":"normal",
       "user":"mole",
       "status":"submitted",
       "media":["http://..."]
   },
   ...

Huge quantum of events can be stored on the server. For this reason it is possible to filter returned event by various criteria. They can be combined together. If doing so the sub-conditions are logically ANDed.

####BBOX Limits number of events to those with location inside bounding box.

var data = {
    "bbox": {
        "lat-min": 23,
        "lon-min": 33.1,
        "lat-max": 24,
        "lon-max": 33.1,
        "crs": "epsg:4326"
    }
};

gsc.cs.eventListFilter(data)

Datetime

Number of listed events can be limited by datetime attribute. Time can be specified by attributes from and to. Either one of the attributes or both can be used. For example, the following filter limits events to those created in the given period of time.

var data = {
    "datetime": {
        "from": "2014-12-03T00:00:00",
        "to": "2015-12-03T00:00:00"
    }
};

gsc.cs.eventListFilter(data)

User

Events can be also filtered by creator.

var data = {
    "user": "mole"
};

gsc.cs.eventListFilter(data)

Priority

Priority can be used as a filter parameter, too. In this case list of priorities can be specified.

var data = {
    "priority": ["normal", "high"]
};

gsc.cs.eventListFilter(data)