3.0 Activities Developer Guide

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Activities Service3.0
DRAFT/WIP

Table of Contents

• 1 Introduction


• 2 Summary


• 3 Configuration


• 4 Post an activity
  
  
  
  • 4.1 Post an activity - with activity data
  
  
  • 4.2 Post an activity - with nodeRef
  
  


• 5 Define activity template(s)
  
  
  
  • 5.1 Samples: pre-built Alfresco activity type templates
    
    
    
    • 5.1.1 Sample 1: Site Membership
    
    
    • 5.1.2 Sample 2: Calendar Events
    
    
    • 5.1.3 Sample 3: Wiki Page Changes
    
    
  
  


• 6 Retrieve activity feed
  
  
  
  • 6.1 Site activity feed
  
  
  • 6.2 User activity feed
  
  

Introduction

Alfresco Activities is part of Alfresco's open source social computing platform.  Alfresco v3.0 provides support for a news/activity feed in the context of an enterprise generating and acting upon content within a site.  The activities will be raised (i.e. posted) by certain components within the context of a site.  The activity service will then generate corresponding activity feeds for each member of that site. This document outlines the steps for a component developer to post a new activity type.

Summary

As a developer, you can post an activity (which in turn will generate a corresponding activity feed) by simply following three basic steps. 

1. Update your component to post one or more activity types with specific activity data. 
   
2. Define one or more activity type templates to display the activity data for your chosen feed formats. 
   
3. Test your activities by retrieving the generated activity feeds for each of the supported formats.
   

Configuration

• For 3.2+, refer to Activity Service Config
  
• For 3.0 or 3.1, refer to Activity Service Config for 3.0 and 3.1
  

Post an activity

Post an activity - with activity data

Typically, you will post (via JavaScript or Java) an instance of an activity type, with some activity data, as well as the site context and the app/tool/component type id.

• activity type name, in package format, eg. org.alfresco.x.y.z
  
• site context (ie. the shortName), eg. mysite1
  
• app/tool/component type id, eg. mytooltype
  
• activity data, in JSON format, eg. { 'item1' : 123 }
  

For example, using JavaScript call:

  activities.postActivity('org.alfresco.calendar.event-created', 'mysite1', 'calendarComponent', '{ 'item1' : 123 }');

See also:

• JavaScript API
  
• Java API
  

Post an activity - with nodeRef

In some cases, you can post an activity with a nodeRef to allow the activity service to lookup some generic data for the node. For details, refer to:

• JavaScript API
  
• Java API
  

Define activity template(s)

You should create corresponding activity templates (using FreeMarker format) for your new activity type, and drop them into the activity template store.  The templates could be running out-of-process (eg. if the activity service has been distributed to a grid) so you can only access activity data that is either supplied during the post (or looked-up based on supplied nodeRef).  The templates can access the activity data, since the activity service will auto-convert the JSON activity data to a FreeMarker data model.  A JSON object will be converted to a FreeMarker 'hash' (map) and a JSON array will be converted to a FreeMarker 'sequence' (list).  Also, date strings in the format ISO8601 format (YYYY-MM-DDThh:mm:ss.sssTZD) will be accessible as dates.  Additional data accessible to the template, includes:

1. userId (of posting user, eg. jsmith123)
   
2. firstName (of posting user, eg. John)
   
3. lastName (of posting user, eg. Smith)
   
4. name (name of item/node, eg. my spreadsheet.xls)
   
5. siteNetwork (site short name. eg. mysite1)
   
6. xmldate(date) (posting date in ISO8601 format, eg. )
   
7. activityType (activity type id, eg. org.alfresco.site.user-joined)
   
8. repoEndPoint (repository endpoint, eg. http://123.456.8.9:8080/alfresco)
   
9. nodeRef (if applicable, eg. workspace://SpacesStore/303e8e2c-1b81-11dd-8d14-97d3290659e2)
   

See also: [3.0_Activities_Design#Activity_Type_Templates Activity Type Templates]

The activity template store is configured to read from the classpath and/or repository, as per web-scripts-application-context.xml. The search path order is:

     alfresco/extension/templates/activities
     alfresco/templates/activities

For example, if your new activity type is 'org.mycompany.mycomponent.event-created' then you might create two templates for ATOM entry and RSS:

  .../org/mycompany/mycomponent/event-created.atomentry.fl
  .../org/mycompany/mycomponent/event-created.rss.fl

and put them on the classpath under:

  alfresco/templates/activities/...

In general, each activity type will have one or more activity type templates corresponding to each supported format. However, if an activity type template is missing then the activity service will attempt to fall-back to a ... TODO

Samples: pre-built Alfresco activity type templates

Alfresco pre-built activity type templates can also acts as samples. These will be included on the classpath under:

  alfresco/templates/activities/org/alfresco/...

Alfresco currently also includes pre-built generic templates under:

  .../org/alfresco/generic.atomentry.fl
  .../org/alfresco/generic.json.ftl

The JSON template can be used to pass through activity data straight back to an activity JSON feed.
The ATOM Entry template can be used for initial dev testing, but should be overridden.

Examples of current (work-in-progress) tool/component ids are:

• siteService (for site membership)
  
• calendar (for calendar events)
  
• wiki (for wiki page changes)
  

Sample 1: Site Membership

The Repository Site Service currently posts activities when users join a site, leave a site or have their role changed by an admin. The current activity types are:

• org.alfresco.site.user-joined
  
• org.alfresco.site.user-left
  
• org.alfresco.site.user-role-changed
  

These activities are posted by the Java-based service:

  repository/source/java/org/alfresco/repo/site/SiteServiceImpl.java

The basic templates for the three activity types are under:

  (in SVN) /projects/remote-api/config/alfresco/templates/activities
  (on server) alfresco/WEB-INF/classes/alfresco/templates/activities
          /org/alfresco/site/user-joined.atomentry.ftl
          /org/alfresco/site/user-left.atomentry.ftl
          /org/alfresco/site/user-role-changed.atomentry.ftl

Sample 2: Calendar Events

The Share Calendar Component currently posts activities when calendar events are created. The current activity types are:

• org.alfresco.calendar.event-created
  
• org.alfresco.calendar.event-deleted
  

which are posted by the Calendar Component:

  remote-api/config/alfresco/templates/webscripts/org/alfresco/slingshot/calendar/event.post.js
  remote-api/config/alfresco/templates/webscripts/org/alfresco/slingshot/calendar/event.delete.js

The basic templates for these activity type are:

  remote-api/config/alfresco/templates/activities/org/alfresco/calendar/event-created.atomentry.ftl
  remote-api/config/alfresco/templates/activities/org/alfresco/calendar/event-deleted.atomentry.ftl

Sample 3: Wiki Page Changes

The Share Wiki Component currently posts activities when wiki pages are created and edited. The current activity types are:

• org.alfresco.wiki.page-created
  
• org.alfresco.wiki.page-edited
  

which are posted by the Wiki Component:

  remote-api/config/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/page.get.js
  remote-api/config/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/page.put.js

The basic templates for these activity type are:

  remote-api/config/alfresco/templates/activities/org/alfresco/wiki/page-created.atomentry.ftl
  remote-api/config/alfresco/templates/activities/org/alfresco/wiki/page-edited.atomentry.ftl

Retrieve activity feed

In order to test your activity, you can retrieve the activity feed using your favourite app that has in-built support for reading ATOM/RSS feeds. In future versions of the 3.0 slingshot app, you will also be able to use the in-built activities dashlet (TBC).

Note: the activity service is asynchronous, hence it may take a few minutes for the posted activity to appear in the activity feed.

Site activity feed

To see the activity feed for site 'mysite1', you can access:

  http://localhost:8080/alfresco/service/api/activities/feed/site/mysite1

You should login as 'admin' when prompted to authenticate.

Alternatively, you can display site activities that have generated entries of a given type by explicitly specifying the format, eg:

•  ?format=atomfeed
  
•  ?format=json
  
•  ?format=rss
  

You can also refer to the webscript description and/or 3.0 REST API

User activity feed

To see the activity feed for user 'user1' as admin, you can access:

  http://localhost:8080/alfresco/service/api/activities/feed/user/user1

You should login as 'admin' when prompted to authenticate.

To see the activity feed for the logged-in user, you can access:

  http://localhost:8080/alfresco/service/api/activities/feed/user

Note: at time of writing, is not yet possible to see user activity feeds (outside of a system test) since it relies on the ability to setup site members.