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 engagement’s rules in the Snap4City Platform, it is needed
   
   1. to own a user’s 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”

 

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

 

3. Otherwise, if the user’s account is authorized, the main portal “Business Central” will be shown. Here it’s possible to manage the user engagement’s rules.

 

4. By clicking “Design” and by choosing the Project labelled “snap4city” it will be possible to show all the available Assets of the user engagement’s rules

   

 

5. It’s 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 engagement’s 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: the representation of an engagement that will be sent to the user’s terminal whenever an “user engagement’s 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: 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: 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: 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: 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: 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 sensor’s type (mapname) the user has been subscribed
• Username

6. It’s 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 engagement’s 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 engagement’s message to dispatch to the user as depicted in Appendix C. Example of Engagements are:

       

 

7. Appendix A:

Engagement -> Message

Engagement.Type==EVENT

Engagement.Type==SUBSCRIPTION

Engagement.Type==REWARD

8. APPENDIX B

Definition of timeslot:

MORNING: from 5am to 10am

LUNCH: from 10am to 2pm

AFTERNOON: from 2pm to 6.30pm

EVENING: from 6.30pm to 12pm

NIGHT: from 12pm to 5am

9. APPENDIX C

The platform every 60 seconds checks if any of the available “user engagement’s rule” has to be considered ACTIVE, (if the WHEN part is valid) and eventually insert in the queue of the messages to dispatch to the user the Engagement (available in the THEN part). The validity of the WHEN part is made analysing the following available information:

EVENT: an event is randomly chosen from the ones available in the Area of the user;

POIs: a list of POI in the nearby of the user is retrieved, if the location of the user has been updated in last 10 minutes…

PPOI: a list of MyPOI belonging to the user is retrieved. A special PPOI called “current-location” represent the last know position of the user is also added to the list

SENSOR: a list of Sensor’s value for any specific MyPOI location is retrieved

TIME: the representation of the current moment of the elaboration is retrieved

USER: the representation of the user is retrieved