WCM Services Layer Design

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

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



{{AVMWarning}}
AVM

This page describes work in progress on providing a WCM Services Layer.  It is made up of content that is highly speculative and undergoing rapid revision!  We would welcome your comments as this layer is being built.


WCM Services Design Notes


The following design notes are a work-in-progress. The detailed design, implementation, testing and delivery of WCM services will be scoped according to WCM requirements and priorities. The initial refactor of WCM services will be phased. The following list is indicative, and is subject to change:


Guiding Principles


The WCM Services Layer will, at its core, be a new Alfresco Services API, implemented in Java and following the same standards / conventions as the existing Alfresco Service APIs.  On top of this API will be layered new Javascript root scope object(s) (so that Javascript scripts, primarily Javascript based Web Scripts, are able to leverage this new API) as well as a set of Web Scripts that expose this API to remote callers (eg. Alfresco Web Studio).

Currently WCM assets are stored as a collection of different types of fundamental Alfresco asset types (DM spaces and nodes, AVM stores and nodes, aspects, etc.), which makes interacting with WCM assets time consuming and error prone.  The WCM Services Layer will instead surface these objects via a unified POJO domain model, with Java interfaces representing each of the major types of WCM asset.  Operations on that domain model (CRUD operations on Web Projects, sandbox-centric operations, etc.) will follow the same 'in-process SOA' architecture used elsewhere in the Alfresco APIs - ie. these operations will not be defined in the domain POJOs themselves, but will instead be defined in one or more stateless Services.

All of the new services defined as part of the WCM Services Layer will be implemented in a test friendly fashion - the code will be amenable not just to unit tests but also to benchmark / scalability tests.  For the first release, as much as possible of the code will be validated by unit tests, while a WCM test suite will be added incrementally over time, as a secondary goal.

Except where it makes sense, the new APIs will not duplicate methods that already exist in the AVM APIs, but if this becomes necessary, the methods in the WCM Services Layer will simply delegate to the underlying APIs.  Note that at this stage, the only place where duplication might make sense is for basic content operations (read file / write file) in the WebContentService.


Done


Web Project


The API set is defined in a WCM WebProject Service interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry (getWebProjectService).

This service will provide CRUD operations on web projects, and also associated web apps and web users.

Exposed by REST Binding

JavaDoc (on HEAD) WebProjectService package


Domain Model


The WebProjectInfo domain object will include:

 * nodeRef
* webProjectId
* name
* defaultWebApp
* title
* description
* isTemplate

Service Summary


JavaDoc (on HEAD) WebProjectService interface

Web Project operations:


  • Create web project (optionally from template)
    • creator (or admin) is by default a content manager
    • implicit creation of default (eg. ROOT) web app
    • implicit creation of staging sandbox
  • Get list of web projects
    • for current user (or given user, if current user is a content manager)
  • Get web project
  • Update web project (with some restrictions eg. no change to web project id / DNS name allowed)
  • Delete web project
    • cascade delete of web apps and web users / sandboxes

Web Project webapp operations:


  • Create web app within a web project
  • Get list of web apps within a web project
  • Delete web app from a web project (note: not currently implemented by JSF client)
    • cascade delete of assets beneath a web app

Web Project user operations:


  • Invite user or group (of users) to a web project
    • with a specified role per user/group (content manager, content publisher, content reviewer, content contributor)
    • implicit creation of user (and user preview) sandbox, for each invited user
  • Get role (if any) of a user within a web project
    • also 'helper' to check if current or given user is a content manager
  • Get list of users associated with a web project, eg. as [user id, role] pairs
  • Uninvite user from a web project (note: not currently implemented by JSF client)
    • cascade delete of web user sandbox
  • Delete web project
    • cascade delete of web project, web apps, invited users and staging/user sandboxes

Implementation


  • Add new foundation service under org.alfresco.wcm.webproject (WebProjectService, WebProjectServiceImpl, WebProjectInfo)
  • Re-factor code out of org.alfresco.web.bean.wcm.CreateWebsiteWizard
  • Re-factor code out of org.alfresco.web.bean.wcm.DeleteWebsiteDialog
  • Re-factor code out of org.alfresco.web.bean.wcm.InviteWebsiteUsersWizard
  • Re-factor code out of org.alfresco.web.bean.wcm.CreateWebappDialog
  • Re-factor code out of org.alfresco.web.bean.wcm.AVMUtil

Questions


  • do we need webapp at all.  Can we remove it?  What is the fallout in terms of backwards compatibility?

Future features


  • change a user's role within a Web Project (with possible undo of certain modified items, eg. if role is reduced ?) (note: recently changed in JSF client, for review JIRA ETWOTWO-73
  • find web project, with several variants (eg. find by exact name, wild-card search etc.)

Sandbox


The API set is defined in a WCM Sandbox Service Interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry (getSandboxService).

This service provides CRUD operations on sandboxes, and ability to list compare sandboxes (ie. get modified items) and submit modified items to other sandboxes, or revert (undo) modified items.

Exposed by REST Binding

JavaDoc (on HEAD) Sandbox package


Domain Model


Sandboxes are associated with a single web project

There are various 'types' of sandbox including: staging sandbox, author sandbox,  workflow sandbox, author workflow sandbox (and preview types of each)

The SandboxInfo domain object will include:

 * sandboxId
* webProjectId
* sandboxType
* creator
* createdDate
* sandboxRootPath

Service Summary


JavaDoc (on HEAD) SandboxService interface

Web Project sandbox operations:


  • Create (author) sandbox
  • Get list of sandboxes
    • within a web project, accessible to current user or given user
  • Get sandbox details
  • Delete sandbox
    • cascade delete of assets within a sandbox (any changed assets will be lost)
  • List changed assets (new, modified, deleted)
    • all, within webapp, or list
  • Submit changed assets
    • all, within webapp, or list (submit to staging will create a snapshot version)
  • Revert changed assets
    • all, within webapp, or list (any changed assets will be lost)
  • List snapshots (sandbox versions) - eg. for staging sandbox or author sandbox
    • all or within given date range, optionally include implicit (system generated) snapshots
  • Revert snapshot (sandbox version) - eg. for staging sandbox
    • create new snapshot based on selected sandbox version

Implementation


  • Add new foundation service under org.alfresco.wcm.sandbox (SandboxService, SandboxServiceImpl, SandboxInfo)
  • Re-factor code out of org.alfresco.web.bean.wcm.SandboxFactory
  • Re-factor code out of org.alfresco.web.bean.wcm.SandboxInfo
  • Re-factor code out of org.alfresco.web.bean.wcm.AVMUtil

Sandboxes currently follow an internal naming convention (in terms of the underlying AVM store name) for example:


  • Staging sandbox = <webproject store id> (eg. test123)
  • Staging preview sandbox = <webproject store id>--preview (eg. test123--preview)
  • Author sandbox = <webproject store id>--<user name> (eg. test123--jsmith)
  • Author preview sandbox = <webproject store id>--<user name>--preview (eg. test123--jsmith--preview)
  • Workflow sandbox = <webproject store id>--workflow-<GUID> (eg. test123--workflow-5031cab3-2fb0-4099-8dc2-911426c1bb67)
  • Workflow preview sandbox = <webproject store id>--workflow-<GUID>--preview (eg. test123--workflow-b49ac293-664f-4e13-a401-3ffa9a254894--preview)
  • Author workflow sandbox = <webproject store id>--<user name>--workflow-<GUID> (eg. test123--jsmith--workflow-5031cab3-2fb0-4099-8dc2-911426c1bb67)
  • Author workflow preview sandbox <webproject store id>--<user name>--workflow-<GUID--preview> (eg. test123--jsmith--workflow-5031cab3-2fb0-4099-8dc2-911426c1bb67--preview)

Questions


  • does the first iteration of WCM services need to expose preview sandboxes ?

Future Features


  • collaborative/shared Sandboxes will be 'named' and available to all users or associated with one or more users (possibly via store permissions)
  • compare sandboxes - general case for comparing two sandboxes
  • consider more than one staging sandbox (to enable use-cases like timed deployment)

Assets


JavaDoc (on HEAD) AssetService interface

The API set is defined in a WCM Asset Service interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry (getAssetService).

This service provides features for adding content to a WCM web project. It provides access to the AVM store in the context of a WCM web project and exposes methods which are friendly to web script/REST interfaces.

This service also provides bulk import to efficiently import large quantities of content.


Domain Model


The AssetInfo domain object will include:

 * name
* sandboxId
* sandboxVersion
* path
* isFile
* isFolder
* isDeleted
* fileSize
* lockOwner
* creator
* createdDate
* modifier
* modifiedDate

Service Summary


  • asset manipulation
    • create file
    • create folder
    • list assets in folder
    • update
    • rename
    • move, copy
    • delete
    • set / get properties
  • lock details
    • is locked / get lock owner (null if not locked)
    • has lock access (can write to locked asset)
  • bulk import
    • bulk import (add multiple folders and files, eg. via zip file)

Implementation


Questions


Is this service required at all?
For non-Web-Form-backed content I'm not sure that there's much value in providing a higher level API over and above what the AVM already provides.  That said, there is some value in having a single 'go to' API for all WCM content access and manipulation needs.  Thoughts anyone?
Do we need an abstraction layer over the AVM store?
Does this service take onboard the XForms stuff ?


Futures


WCM Deployment


The API set will be defined in a WCM Deployment Service interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry.  This interface will provide:

Provides CRUD operations on configuring the deployment targets for a web project.

Provides access to deployment reports.

Provides a facade to the existing repo deployment service, to reduce the complexity and make the interface amenable to web scripts.


Domain Model


WCM deployment targets, will include the following properties (note: this list is indicative, not definitive):

 * name
* display name
* hostname
* port number
* username
* password
* test server flag
* target (FSRs only)
* transport adapter

Interface inheritance will be used to differentiate ASRs and FSRs.


Service


  • Web Project deployment target operations:
    • enumerate deployment targets, with several variants (eg. findByTargetHostname, listASRs, listFSRs, etc.)
    • add deployment target
    • update deployment target
    • delete deployment target
    • acquire test servers (note: must address JIRA ENH-165)
    • release test servers
  • Web Project deployment operations:
    • deploy, with several variants (eg. deployCurrentSnapshotToLiveTargets, deploySnapshotNToTargetsXYZ, deployUserSandboxToTestTargetsXYZ, etc.)
  • Web Project deployment report operations:
    • enumerate deployment reports, with several variants (eg. findDeploymentReportsByDate, findDeploymentReportsByVersionNumber, findDeploymentReportsByDeploymentTarget, etc.)
  • Transport options
    • enumerate available transports.

Implementation


  • Add new service. WebDeploymentService and WebDeploymentServiceImpl
  • Keep existing DeploymentService
  • Re-factor code out of org.alfresco.web.ui.wcm.component.UIDeploymentServers
  • Re-factor code out of org.alfresco.web.bean.wcm.DeploymentUtil;
  • Re-factor code out of org.alfresco.web.bean.wcm.AVMUtil;

Questions


  • Deployment is async at the moment.  Is there any requirement for a blocking deployment?  
  • How do we identify deployments in progress, where do we store the equivalent of a deployment status which (on the JSF client) is a session scoped bean which is only persisted to the database AFTER deployment is complete?   Answer,   we can't have the equivalent of a session scoped bean so will have to store it on the action.   Will have to add API to poll the action service.   Will need to refactor the action service and deployment to expose the deployment report.
  • is a deployment report a html formatted document or a data transfer object ? - Answer the repository/api scripts provides a JSON representation.   Then if a futher web studio web script wishes to transform it to HTML so be it.   But that's not code in the repository that does that.
  • just to clarify the deployToNtargets functionailty won't be a single transaction.

Future features


The following features are not essential, but are worthy of consideration.


  • get formatted deployment report

Web Forms


TODO: is this necessary?  Will Web Studio require the ability to manipulate Web Forms from day one?

Gavin's work on forms


Domain Model


The 'WebForm' domain object will include all of the properties defined for Web Forms, including the following (note: this list is indicative, not definitive):


  • TODO

Service


The API set will be defined in a 'WebFormService' interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry.  This interface will provide:


  • TODO

Forms Definition operations (see also new Forms Service)


    • Form CRUD operations
    • enumerate all Forms available (to all Web Projects)
  • TODO
  • Web Form operations:
    • associate Form with Web Project
    • enumerate Web Forms associated with a Web Project
    • update Web Form (ie. with applicable overrides) within context of a Web Project
    • disassociate Web Form from Web Project
  • enumerate all content using the Web Form, across all Web Projects
  • regenerate all renditions for a given Web Form, across all Web Projects

Web Form (XML) Content


TODO: should this be extended to all WCM content, or just Web-Form-backed content?


Domain Model


The 'WebFormContent' domain object will include all of the properties defined for Web Form (XML) content, including the following (note: this list is indicative, not definitive):

 * StoreRef (for accessing the content and aspects / properties etc.)
* name
* author
* creation date
* modification date
* parent Web Project
* originating Web Form (represented as a NodeRef to the DM space containing the Web Form)

Service


The API set will be defined in a single 'WebFormContentService' interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry.  This interface will provide:


  • Web Form Content operations:
    • retrieve Web Form content, with several variants (eg. getByFilePath, getByStoreRef, etc.)
    • enumerate Web Form content, with several variants (eg. findByType, listByFolderPath, etc.)
    • query / search for Web Form content
    • add Web Form content
    • modify Web Form content
    • delete Web Form content
  • Web Form Content rendition operations:
    • enumerate renditions for Web Form content
    • regenerate renditions for Web Form content
  • Miscellaneous Web Form content operations:
    • 'guess' the most appropriate Web Form, given a raw XML document

Note that this API will be fully sandbox aware ie. all operations will require a sandbox context to operate in.  TODO: this poses issues for query / search, since that's currently only supported for staging sandboxes.


WCM Workflow


TODO: is this necessary?  Will Web Studio require the ability to manipulate WCM workflows from day one?


Domain Model


The 'WCMWorkflow' domain object will include all of the properties defined for WCM Workflows, including the following (note: this list is indicative, not definitive):


Service


The API set will be defined in a single 'WCMWorkflowService' interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry.  This interface will provide:


  • TODO
  • WCM Workflow operations:
    • WCM Workflow CRUD operations
    • enumerate configured workflows for a Web Project (represented as [workflow reference, selection rule] pairs)
    • retrieve active WCM workflow instances for a Web Project (TBD - is this necessary? - - redundant with new workflow querying capabilities in 3.0?)
    • associate workflow to Web Project (TBD)
    • disassociate workflow from Web Project (TBD)
    • manage workflow association precedence (ie. to allow workflows to be reordered) (TBD)

Attachments

    Outcomes