3.2 Invitation Service Design

Document created by resplin Employee on Jun 6, 2015Last modified by alfresco-archivist on Aug 31, 2016
Version 2Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

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

Design Document

This document is work in progress,  but any comments will be gladly received.

At the moment in Alfresco 3, the site invitation process and web project invitation are separate pieces of logic spread through several packages, although they clearly share some common requirements and should have a common solution.

The 'invitation' document should form the basis of a new service which is exposed by the new Java Service with script and REST bindings.   The existing REST bindings should be considered for deprecation.


version 3 requirements

The following page proposes a new 'Invite Service' to achieve the following goals.

  • To gather together the code involved in the Site Service and provide a public api and possibly public extension points.
  • To merge the separate code between the site invitation process and the web project invitation process.
  • To provide public or semi-public API and
  • To enable enhancement and modification of the invitation process.
  • To enable and support missing functionality from the existing APIs.


Person/Group who wants to be invited.
Who is doing the inviting.
Says yes / no to the invitation.
  Someone who overlooks the process,   how many requests outstanding?     Who hasn't been approved?   Why can't fred access this site?

Invite workflow definition diagram.png

Need to gather together an invite request, user identifier, resource identifier and role.   Pump the request through a workflow and then apply the result of the workflow to the resource.    The workflow may either be an approve and add   (existing Site).   Or add and inform (existing Web Project). 

Using the Invite functionality on a Site, if the Invite fails you get a fade in and fade out message saying '..... 1 failures' but no further information about why the failure occurred or what made it occur.

The invitations process will need to consider the combination of the following.

Request Type

  • invite (me)
  • invite (someone else)
  • uninvite
  • change role

User Identifier

  • email address
  • alfresco id
  • group id

Resource Identifier

  • Site Ref
  • Web Project Ref
  • Node ref??

Role Indetifier

  • Web Project Role
  • Site Role
  • Alfresco Role

Invitation engine

Kicks off correct workflow for each invitation.  

  • On a timed basis needs to send out reminder emails.
  • Expire, expired (too old) invitations.
  • Clean up accepted invitations.

Invitation workflow

Need separate workflows for Web Projects and Sites.   Web Projects are add and inform.   Sites are approve and accept.

The processing of Groups is different to users who are already Alfresco users to prople who need to be invited.

In addition to catering for the above How configurable does the workflow need to be?

Do we need to be able to configure different email messages for each resource?   Probably ?

Extra thoughs

  • approver/sponsor?  
  • Details of the request.  
  • Notes of the request to the approver.
  • Request expiry date.
  • Is the user identifier a string identified by pattern.   Or a more complex type?
  • Show complex/simple to make the workflow selection engine?
  • How sophisticated or inteligent does the process need to be.   For example if a user is added to a group half way through notification what happens ?    Or if a single user is uninvited who has membership through being a member of a group ?

Java API

public interface InvitationHistory
   Date when;
   String who;
   String what;

public interface Invitation
    // status created, approved, rejected, accepted, declined, error
    String status;

    // which web project or site
    String resourceId;

    // Request parameters
    String requestMessage;
    // basics
    Date createdOn;
    String createdBy;
    Date modifiedOn;
    String modifiedBy;

    // approval
    Date approvedOn;
    String approvedBy;
    // invitation history
    InvitationHistory[] history;

* crates an invitation and returns the invitation ref
* @param request
* @return the invitation request
* @throws some sort of unknown request exception
public String invite(InviteRequest request);

public String inviteSite(String userId, String siteRef,  request);

public String inviteWebProject(String webProject, String userId, String role);

* Accept an invitation
* @param invitationRef, unique reference for an invitation, returned by invite method

public void accept(String invitationRef);

  * reject an invitation
* @param invitationRef, unique reference for an invitation, returned by invite method
public void decline (Sting invitationRef);

  * getInvitation
  * @param invitationRef, unique reference for an invitation, returned by invite method
public Invitation getInvitation(String invitationRef);

ListCriteria {
page size
Set<Invitation> listInvitations(ListCriteria criteria);

// notification
public void remind(RemindCriteria reminders);

// expiry
public void expire(ExpireCriteria criteria);

REST bindings

site/invitations/GET/PUT/POST/DELETE invitation.





How configurable does the workflow process need to be?

Permissions.    Do we need some new permissions for inviter, approver etc?

Do we need InviteHistory or can we use standard Audit functionailty?


Start with the idea of a generic / abstract workflow.   Plug in specialist implementations.
Does this work ?    Is it useful ?

Design Document