Social Annotation Service

Introduction

Social Annotation Service takes care of all actions related to the social media (authorization, content posting and retrieval, etc), which remain transparent to the user of the application. The aim is to create an innovative and practical application for automating the process of video annotation with information coming from multiple individuals using the social media.

Functionality

A lot of features are supported in Social Annotation Service. The information, is stored in a PostgreSQL database, and is synchronised with the posts on Facebook at runtime to prevent errors when a photo is deleted from Facebook. The database contains information for each photo about:

  • user’s name,
  • photo’s description
  • the link to the video in Drupal
  • whether a photo was deleted from Facebook or not.
  • number of likes
  • the comment of the photo with the most likes
  • the user who posted the top comment
  • the number of likes of the top comment
  • the total time to upload the photo to Facebook

Use Cases

Social Annotation Service was initially designed for and deployed at the Foundation of the Hellenic World. It has also been deployed in the context of two additional experimental applications: CARVIREN (CAR Virtual Environment) and iCaCoT (interactive Camera-based Coaching and Training).

Requirements & Installation

Requirements

The software required for deploying and running Social Annotation Service:

  • PostgreSQL 9.3
  • Apache Tomcat 7.x
  • Java JDK 1.7
  • Eclipse integrated development environment (IDE)

Installation

Installing PostgreSQL

The Social Annotation Service uses PostgreSQL as a database solution. Please follow installation instructions from the PostgreSQL official website PostgreSQL.

  • Download: http://www.postgresql.org/download/

    *PostgreSQL Download image*
  • After installing PostgeSQL create the following database and tables:

    Create a database with UTF-8 encoding:

    CREATE DATABASE "fb-publication-service"
            WITH ENCODING='UTF8'
            CONNECTION LIMIT=-1;
    

    Create the table “photo” in the database:

    CREATE TABLE photo(
            photo_uuid text NOT NULL,
            number_of_likes text DEFAULT 0,
            top_question_message text,
            top_question_user text,
            top_question_like_count text DEFAULT 0,
            top_answer_message text,
            top_answer_like_count text DEFAULT 0,
            top_answer_user text,
            top_comment_message text,
            top_comment_user text,
            top_comment_like_count text DEFAULT 0,
            fb_id text, photo_description text,
            user_name text,
            deleted boolean DEFAULT false,
            upload_time integer DEFAULT 0,
            CONSTRAINT photo_uuid PRIMARY KEY (photo_uuid))
            WITH(
                    OIDS=FALSE);
            ALTER TABLE photo
                    OWNER TO postgres;
    

    Create the table “timera” in the database:

    CREATE TABLE timera
    (
            id integer NOT NULL,
            "number" integer,
            average_time integer,
            CONSTRAINT timera_pkey PRIMARY KEY (id))
            WITH(
                    OIDS=FALSE);
            ALTER TABLE timera
                    OWNER TO postgres;
            INSERT INTO timera (id,number,average_time) VALUES (1,0,0);
    

Installing Apache Tomcat 7.x

For the deployment of the Social Annotation Service, Tomcat v7 is recommended.

In order to install Tomcat please follow the instructions in the official website: http://tomcat.apache.org/download-70.cgi

*Tomcat Download image*

The deployment can be done manually by copying the social-annotation-service.war to Tomcat’s ‘webapps’ directory or through its Manager GUI.

JDK

Installing JDK: For more information visit the official Oracle website

Eclipse IDE

The usage of Eclipse is recommended to those that want to build the Social Annotation Service project.

More information about Eclipse IDE could be found in the official Eclipse website https://www.eclipse.org

*Tomcat Download image*

Log4j

Log4j is used for logging in Social Annotation Service. All logs are directed by default to the console. For changing the location of the created logs, their names, the used pattern etc, please edit log4j.properties.

Configuration

Social Annotation Service is a RESTful web service that uses Jersey distribution packaged in ‘social-annotation-service.war’. All required Java libraries are included inside the WAR. The WAR also includes the following properties files for configuration:

  • oauth_consumer.properties & social.properties: for Facebook authentication
  • database.properties: for configuring database connectivity
  • log4j.properties: for logging configuration
  • resetDatabase.properties : for choosing whether to erase or not database’s records upon the contextualization of the service

The usage of Eclipse is recommended to those that want to build the Social Annotation Service project and generate a new WAR. For simply running it, open the distributed WAR using a file archiver program for zip format, edit the properties files mentioned above using the instructions that follow and directly save changes in the WAR file.

Note: When Social Annotation Service is first initialized, a daemon monitoring thread for collecting info from FB for the existing photos in the database is created. This time interval is set by default to 20 secs. For changing it, edit property ‘interval’ in social.properties. Note that this time interval is specified in milliseconds.

  • You can configure Social Annotation Service to connect to the database in its database.properties file by editing the following line:

    connectionURL=jdbc:postgresql://<PostgreSQL server IP>:<PostgreSQL server Port>/<name of database>
    username=<the owner of the database>
    pwd=<the owner's password>
    
  • Prior to the photo being uploaded to FB, this software downloads and stores the image in a given location. This location can be edited in the social.properties file:

    image_directory=<the path to the directory where the images will be stored>
    
  • Social Annotation Service exchanges data with a given Facebook target location (e.g. an event, a page, a group, etc). This location must be configured by providing the Facebook id of the target event/page/group. The following instructions explain how to create a Facebook User Event or a Facebook Page Event.

    • Create Facebook User Event:

      1. Click Events on the left side of your Facebook homepage.

        *Facebook event image*
      2. Click Create in the center or on the left side under My Events.

        *Facebook event image*
      3. Fill in the event name, details, location and time, and then choose your privacy settings. Keep in mind that you must include an event name and time.

        *Facebook event image*
      4. Click Invite Friends to add friends to the guest list. Check the names of the people you want to invite and then click Save.

      5. Click Create. More information about how to create and edit events in the Facebook-Help-Page.

      6. Copy the url the event. For example: “https://www.facebook.com/events/1234...”

    • Create Facebook Page Event:

      To create an event from your Page, go to your Page’s Timeline

      1. Click Event, Milestone +
      *Facebook event image*
      1. Click Event

      1. Fill in the event name, details, location and time, privacy settings
      *Facebook event image*
      1. Click Create
  • A Facebook user or page access token is required. Comprehensive instructions for obtaining such a token can be found here. It is recommended to obtain an extended access user or page token using your own app ID and app secret.

API

List of functions

Four operations are exposed:

  • uploadFrame (String UUID, String URL, String description, String userName , String videoURL): The Social Annotation Service uploads the photo to a given Facebook event via the SocialIntegrator API using the values of the parameters ‘description’ , ‘user name’ and ‘the link to the video in Drupal’ as its title. Upon success, all related information is stored in a PostgreSQL database and the Facebook URL of the uploaded photo is returned to the AVCC component for confirmation.
  • retrieveAnnotation (String UUID): The Social Annotation Service runs a daemon thread that automatically retrieves information from the Facebook event related to the frames that have been uploaded previously. The time interval that is used to retrieve this information is configurable. The social information is then used to calculate useful metrics such as the number of likes for each frame, top comments, top answers, etc, which are stored in the underlying database.
  • getQoSMetrics (): Social Annotation Service sends QoS metrics using a predefined XML format according to experiment’s requirements. These metrics include average time to upload a photo to a Facebook event using uploadFrame method as well as the average time for the execution of retrieveAnnotation method.
  • retrieveQoSMetrics (): The functionality of this method is similar to getQoSMetrics method’s with the significant difference that this is a POST method whereas the previous one is a GET method.

Contact & Support Information

Contact

NATIONAL TECHNICAL UNIVERSITY OF ATHENS (NTUA)
INSTITUTE OF COMMUNICATION AND COMPUTER SYSTEMS (ICCS)
Kleopatra Konstanteli
ICCS/NTUA, Greece
Georgios Palaiokrassas
ICCS/NTUA, Greece

Licensing

Copyright (c) 2013-2014 National Technical University of Athens
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sub-license, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.