Invitation Service

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

Obsolete Pages{{Obsolete}}

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



Design Document


Overview


The role of the Invitation Service is to manage the process of granting users access to a specified resource. At present the Invitation Service only manages access to Sites.  

The process of granting a user access to a resource is represented as an Invitation object. An Invitation stores information holds the following information:


  • A unique ID for the Invitation.
  • The invited user.
  • The type of Resource to which access is being granted (currently only Site).
  • The name of the Resource to which access is being granted.
  • The Role (access level) to be granted.

Invitations are implemented as workflow instances (using either the Activiti or JBPM engine). 
The various steps in the invitation process are represented as workflow tasks which are visible in the Share Workflow UI (My Tasks dashlet/page), mostly avoiding the need to develop a UI specifically for invitations.

There are two types of Invitation, *Moderated Invitation and Internal Nominated Invitation, which are discussed in more detail below.


Moderated Invitation


A moderated invitation is one where a user requests a certain level of access (a Role) to a Resource (Site). The request is reviewed by one of the Resource Managers and is either approved, in which case the user is granted the requested level of access or rejected, in which case the user is not granted access.

Since the user must be logged in as an Alfresco Authority in order to initiate a Moderated Invitation external users cannot request invitations in this way.

The diagram below outlines the process followed during a Moderated Invitation.

Moderated Invitation Flow.png

JBPM process definition: invitation-moderated_processdefinition.xml
Activiti process definition: invitation-moderated.bpmn20.xml


Nominated Invitation


A nominated invitation is one where a Resource Manager sends an invitation to another user, inviting them to gain access to the resource (Site) with a specified permission level (Role). When the invitation is sent by the Resource Manager an email is sent to the invited user, providing links for the user to accept or reject the invitation. If the invited user accepts the invitation he gains access to the Resource. If he rejects the invitation then the process ends. The Resource Manager who sent the invitation also has the option to cancel the invitation, ending the process.

The invited user is not required to be an existing Alfresco Authority. In this case a temporary Authority is created for the invited user and if the user chooses to accept the invitation the Authority is made permanent. If the invited user rejects the invitation then the temporary Authroity is deleted.

Nominated Invitation Flow.png

JBPM process definition: invitation-moderated_processdefinition.xml
Activiti process definition: invitation-moderated.bpmn20.xml


Java API


Invitation Service


REST bindings


Get Invitations


Returns a list of Invitations represented as JSON objects. The invitations returned can be filtered by invitee user name, invitation type, resource type and site short name (resource name).

Generic binding:



/api/invitations?inviteeUserName={inviteeUserName?}&invitationType={invitationType?}&resourceType={resourceType?}










Parameter
Mandatory
Description
inviteeUserName false The name of the invited user
invitationType false Is the invitation Nominated or Moderated
resourceType false Type of Resource (e.g. Site)



Site-specific binding:



/api/sites/{shortname}/invitations?inviteeUserName={inviteeUserName?}&invitationType={invitationType?}










Parameter
Mandatory
Description
shortname true The Site Short Name
inviteeUserName false The name of the invited user
invitationType false Is the invitation Nominated or Moderated

Get Invitation


Returns a JSON representation of a single Invitation, specified by site short name and Invitation Id.



Site-specific binding:



/api/sites/{shortname}/invitations/{inviteId}








Parameter
Mandatory
Description
shortname true The Site Short Name
inviteId true The Id of the Invitation

Post Invitation


Creates a new Invitation. A JSON object is used to specify the various parameters, including invitation type, invitee user name, role, etc.



Site-specific binding:



/api/sites/{shortname}/invitations

Delete Invitation


Deletes the Invitation as specified by Invitation Id.



Site-specific binding:



/api/sites/{shortname}/invitations/{invitationId}

Related Links


3.2 Invitation Service Design

Invite Service Design (Deprecated)

Outcomes