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



3.2
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.


Functionality


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.

Actors:  


Invitee
Person/Group who wants to be invited.
Inviter
Who is doing the inviting.
Approver
Says yes / no to the invitation.
Administrator
  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;
}

//invitations
/**
* 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);

//management
ListCriteria {
page
page size
resource
status
user
}
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.

webproject/invitations

site/invitations

invites/{inviteref}


Questions


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?


Configuration


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



3.2
Design Document

Outcomes