TC8.10 - How to manage the user engagement’s rules in the Snap4City platform

Test Case Title

TC8.10 - How to manage the user engagement’s rules in the Snap4City platform

Goal

I can define rules of engagement for stimulating users of the Mobile Apps according to certain firing conditions

I can monitor the results of the engagement performed

I can reward and motivate them in some manner

Prerequisites

Access to the snap4city.org as authorised users.

The following functionalities are available only for specific Snap4city users with specific privileges, typically at level of ToolAdmin and each of them has to be authorized to reach that role in Snap4City platform. Please ask to snap4city@disit.org

Expected successful result

Users of the Mobile App are engaged to perform certain actions. The monitoring of the action can be performed on Dashboard. Actions can be informative, operative. In the operative action, we can ask to the user to perform specific actions: take a photo, drop a comment, raking, perform an experience on the Mobile App, etc.

Steps

 

The main concept in this case consists in defining some rules having the following structure:

IF <CONDITION> THEN <ACTION>

Where:

The CONDITION is typically composed by a set of element that are assessed at a given time, and may depend on the single users, on context of the user and the city, on date and time, on language, on mobile app, on GPS, etc.

The ACTIONs are typically performed by the platform, for example: by sending an alert, by sending an email, by sending a survey, by requesting some action to the user, send a notification, send a prize, etc.

The rules are executed according to the changes of user conditions. 

In the following terminology, Decision is described using a Rule paradigm: WHEN something happen -> THEN do something.
The WHEN CONDITION part is composed using the main Data Models described in the following (without considering the Engagement Data Models) and the THEN ACTION part is created using the Engagement Data Model.

Now see the step by step demo:

  1. To manage the user engagements rules in the Snap4City Platform, it is needed
    1. to own a users account with role at least ToolAdmin
    2. to log in the Snap4city website (https://www.snap4city.org)
    3. to press from the left main menu the buttons called User Management and Auditing -> User Engagement

 

  1. If on the main window a message Login failed: Not Authorized appears, it means the users account is not enabled. Please request the authorisation for User Engagement filling the form available at https://www.snap4city.org/drupal/contact

 

  1. Otherwise, if the users account is authorized, the main portal Business Central will be shown. Here its possible to manage the user engagements rules.

 

  1. By clicking Design and by choosing the Project labelled snap4city it will be possible to show all the available Assets of the user engagements rules

   

 

Data Models (main element to define the CONDITIONS)

  1. Its possible to filter the list of the Assets by clicking All -> Model. It will retrieve all the Data Models available (on the Project Explorer view they are also called Data Objects). The Data Models are the main building blocks on top of which is possible to define the user engagements rules

 

At the moment, (but continuously in evolution) the list of the main Data Models available is:

  • ENGAGEMENT and ENGAGEMENTType
  • EVENT
  • POI
  • PPOI (MYKPI)
  • SENSOR and SENSORType
  • TIME and TIMEType
  • USER and USERType

ENGAGEMENT

  • ENGAGEMENT: the representation of an engagement that will be sent to the users terminal whenever an user engagements rule is ACTIVATED. It is described by:
  • Elapse time, expressed in minutes (default is zero, means never elapsing)
  • Message text, strongly depending on the type of the Engagement
    • SURVEY: a conformant json generated using the https://surveyjs.io/ library v1.0.63
    • ALERT: a simple message text to be shown
    • REWARD: not used yet, a conformant json as depicted in Appendix A
    • SUBSCRIPTION: a conformant json as depicted in Appendix A
    • EVENT: a conformant json as depicted in Appendix A
  • Points, not used yet
  • Rulename, represent the name of the rule that generated the Engagement
  • Sendrate, expressed in minutes (default is zero, means never send again)
    • Note: if elapse==0, sendrate is considered just if there are not any other ACTIVE Engagement with the same rulename
  • Subtitle and Title
  • Type, can be
    • SURVEY
    • ALERT
    • REWARD, not used yet
    • SUBSCRIPTION
    • EVENT

EVENT

  • EVENT: the representation of a city event. It is described by:
  • startDate and endDate, expressed in textual format as YYYY-MM-DD
  • latitude and longitude, location of the event
  • name and place, textual description of the event
  • serviceType, usual Event
  • serviceUri, unique URI representation of the event
  • typeLabel, detailed description of the serviceType

POI

 

  • POI: the representation of a POI (Point-Of-Interest). It is described by:
  • latitude and longitude, location of the POI
  • name, textual description of the POI
  • serviceType, classification on the POI
  • serviceUri, unique URI representation of the POI
  • type and typeLabel, detailed description of the serviceType

PPOI/MyPOI

  • PPOI/MyPOI: the representation of a MyPOI created by the user. It is described by:
  • latitude and longitude, location of the PPOI
  • latitudeAprox and longitudeAprox, cluster version of the location of the PPOI in a 100 meters box
  • name, textual description of the MyPOI

  • SENSOR: the representation of a sensor. It is described by:
  • latitude and longitude, location of the Sensor
  • insertdate, date when the last observation has been considered
  • mapname/sensortype, type of the Sensor
  • valuename, observed value of the sensor

 

TIME

  • TIME: the representation of the time. It is described by:
  • dayOfMonth, numeric representation of the day of the month, from 1 to 31
  • dayOfWeek, numeric representation of the day of the week, from 1 (Sunday) to 7 (Saturday)
  • daySlot, can be NIGHT, MORNING, LUNCH, AFTERNOON, EVENING as depicted in Appendix B
  • hours, minutes
  • month, numeric representation of the month from 1 to 12

USER

  • USER: the representation of the user. It is described by:
  • Age, not used yet
  • Executeds, not used yet, list of the rulename that has been executed
  • Gender, not used yet
  • Groups, list of the group an user belong to
  • Id, not used yet
  • Language, ISO 639-2 Code
  • Organization
  • Registrationdate
  • Role
  • Subscriptions, list of the sensors type (mapname) the user has been subscribed
  • Username

Decisions are the rules

  1. Its possible to filter the list of the Assets by clicking All à Decision. It will retrieve all the Decision available (on the Project Explorer view they are also called Guided Rule). The Decisions describes the user engagements rules

A Decision is described using a Rule paradigm: WHEN something happen à THEN do something. The WHEN part is composed using the main Data Models described above (without considering the Engagement Data Models) and the THEN part is created using the Engagement Data Model. To speed up the definition of the Decision, a Guide Rule Template can be used. Example of Decisions are:

Subscription type: notify, every two hours, the users with a specific $language, from the organization Antwerp, that has been subscribed to AirHumidity if that sensor has been observed in a PPOI of the user with value higher than 67.8:

Event type: notify, once a day, the users with a specific $language, with a city event:

Survey type: notify, after one hour from the registration, the users, with a specific $language, from the organization Helsinki with a survey about Feedback in the Helsinki experimentation:

Once a new rule is created and authorized by the Snap4City admins, it will be made available to the Snap4City Platform that will use it to create the user engagements message to dispatch to the user as depicted in Appendix C. Example of Engagements are: