Published on

Alfresco Web Scripts have become an important part of any Alfresco developer's tool kit and in this session we will take a deep dive into how Web Scripts can be used to provide public APIs for Alfresco extensions. After briefly reviewing the anatomy of a Web Script and discussing Alfresco's approach to Service development, we will work through an example that extends Alfresco with a simple service and creates a REST API using Web Scripts.

Published in: Technology, Education
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Where do we start? At the begining.Why do we have WebScripts?What are WebScripts used for?What is a WebScript?How do I use a WebScript?Where can I use a WebScript?
  • URL – unique resource locator.HTTP Methods – action to be performed on the resource (GET, PUT, POST and DELETE)HTTP Response Status – tells the client what’s happened (success, fail, event, action)Response types – the type of content being returned from the server (XML, HTML, JSON, ATOM)REST – Representational State TransferTODO – summarise the following into readable notes ...TODO – Diagram showing flow ... URL (method) -> Resource -> response (status) .. Transfer of representation .. Rest state .. REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of "representations" of "resources". A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.At any particular time, a client can either be in transition between application states or "at rest". A client in a rest state is able to interact with its user, but creates no load and consumes no per-client storage on the set of servers or on the network.The client begins sending requests when it is ready to make the transition to a new state. While one or more requests are outstanding, the client is considered to be in transition. The representation of each application state contains links that may be used next time the client chooses to initiate a new state transition.[4]REST was initially described in the context of HTTP, but is not limited to that protocol. RESTful architectures can be based on other Application Layer protocols if they already provide a rich and uniform vocabulary for applications based on the transfer of meaningful representational state. RESTful applications maximize the use of the pre-existing, well-defined interface and other built-in capabilities provided by the chosen network protocol, and minimize the addition of new application-specific features on top of it.
  • Web Script Runtime:A typical deployment includes an Alfresco Repository server hosting data Web Scripts with one or more Alfresco clients hosting presentation Web Scripts where communication between the two is over HTTP. The Alfresco Repository utilises the Servlet Run-time whereas a remote Web Client utilises the SURF Run-time for hosting Web Scripts. However, this is just one of many options given the following available Web Script Runtimes:Servlet Runtime (HTTP accessible)SURF Runtime (embed Web Script UI components in web-tier UI pages)JSR-168 Runtime (adapter between JSR-168 portlet API and Web Script)JSF Runtime (JSF tag to include Web Script)Facebook Runtime (access to Facebook API and Repository API within Web Script)We've already seen there are several types of Runtime available out-of-the-box. These Runtimes can be setup in conjunction with one the following out-of-the-box Containers:Presentation - a light-weight container for rendering User Interface components that can make service calls to remote data sources.Repository - a container for embedded use in the Alfresco Repository providing integration with transactions and direct access to content held in the Repository and services provided by the Repository.Flow:1. A request for a given URI arrives at the Web Script Runtime.2. The Runtime finds the appropriate Web Script for the URI. If one is found, the Runtime executes the Web Script but only after successfully authenticating first, if required. The first step of execution is to invoke the JavaScript bound into the Web Script.3. With JavaScript, you have access to a set of Alfresco services. When hosted within the Repository server you can search for information, navigate around the repository, modify information, create new documents, set properties on those documents, move data around, and delete data, plus access to all other Repository services. Outside of the Repository you can invoke remote services such as those by the Repository server.4. The results from the JavaScript are rendered using FreeMarker response templates. The response format may be one of HTML, ATOM, XML, RSS, JSON, CSV, or any combination of these. You must provide the appropriate templates.5. The Web Script Runtime sends the rendered results back via a response using the same protocol as the URI request.6. The Web Script client receives the response in the requested format.
  • Optional files – Controller, Configuration, Message Bundles, Response Status TemplateIn Alfresco repository or on JAVA classpath.4 predefined locations.Subfolders can be used to organise.Use refresh link on the /alfresco/service/ page to load new Web Scripts.
  • Webscripts

    1. 1. Webscripts<br />2<br />Roy Wetherall<br />Senior Software Engineer, Alfresco<br />twitter: @rwetherall<br />
    2. 2. Agenda<br />3<br /><ul><li>Where to start?
    3. 3. Nuts and Bolts
    4. 4. Building a Webscript Data API
    5. 5. Questions</li></li></ul><li>Where to start?<br />4<br />At the beginning ...<br />
    6. 6. What is a Webscript?<br />5<br />In no more than 140 characters ...<br />
    7. 7. What can Webscripts be used for?<br />6<br /><ul><li>Presentation
    8. 8. Data
    9. 9. Integration</li></ul>“Webscripts unlock content”<br />
    10. 10. Fundamental Concepts<br />7<br />GET<br />http://myserver/A/X<br />Wait<br />Request<br />Response<br />HTTP<br />Process<br />200<br /><x>My Content</x><br />A<br />X<br />Y<br />
    11. 11. Webscript Execution Flow<br />8<br />
    12. 12. Webscript Architecture<br />9<br />
    13. 13. Nuts and Bolts ...<br />10<br />... of a Webscript<br />
    14. 14. Webscript Files<br />11<br /><ul><li>Description document
    15. 15. Controller
    16. 16. Response template
    17. 17. Configuration
    18. 18. Message bundles
    19. 19. Response status template</li></ul>“Place files on the classpath or in the repository”<br />
    20. 20. Document Description<br />12<br />Documentation<br />URL templates (JSR-331)<br />Response format details<br />Authentication<br />Transaction<br />Lifecycle and family<br />“Webscripts are declarative”<br />
    21. 21. Controller<br />13<br />Optional<br />Access to model<br />Can read/write to repository<br />Removes complexity from response template<br />Implemented in JavaScript or Java<br />Root objects set based on container<br />“Controllers handle the request, gather information and populate the model.”<br />
    22. 22. Response Template<br />14<br />Build web script response<br />Implemented in Freemarker<br />Many response templates per Webscript<br />Access to model<br />Root objects set based on container<br />“Response templates format the response to a Webscript request.”<br />
    23. 23. Simple Webscript Example <br />15<br />
    24. 24. Building a Webscript Data API<br />16<br />
    25. 25. Alfresco Service API Architecture<br />17<br />Webscript API<br />Javascript API<br />Java Service API<br />
    26. 26. Java Service API<br />18<br />Stateless<br />Concise<br />Provides all functionality<br />Extendable<br />Adaptable<br />“The Java service layer is where all the ‘real’ code should go”<br />
    27. 27. Java Script API<br />19<br />Object based<br />Available in the repository<br />Developer friendly<br />Implemented in Java<br />“The Java Script API helps rapid adoption and development of Alfresco applications”<br />
    28. 28. Webscript Data API<br />20<br />REST(ful)<br />Resource based<br />Representations delivering data<br />HTTP methods mapped to API<br />Simple integration<br />Public and remote<br />“Webscript Data APIs unlock content.”<br />
    29. 29. Design Example – Candy Store<br />21<br />“I want to create a Share customisation that allows me to manage the stock in my Candy Store. <br />I should be able to see what stock is available, add/edit/remove the details of the stocked candy and review the stock levels.”<br />
    30. 30. Design Example – Candy Store<br />22<br />Content Model and Java API<br />
    31. 31. Design Considerations<br />23<br />Resources are referencable<br />They have state<br />The “things” in your API<br />Collections<br />Composite resources<br />“Identifying resources in your API is key.”<br />Resources<br />
    32. 32. Design Example – Candy Store<br />24<br />Candy<br />A candy bar that is currently stocked in the candy store.<br />Candies<br />A collection of all the candies currently stocked in the candy store.<br />Candy Store<br />The candy store it’s self.<br />Candy Manager<br />Manages the stock levels in the candy store.<br />Usually use /api/actionQueue and custom actions instead.<br />Resources<br />
    33. 33. Design Considerations<br />25<br />HTTP methods should map logically to the API<br />URLs should be composed of resources<br />Parameters should be parameters<br />Consistency is important<br />No hard and fast rules<br />“Simple always works best.”<br />Methods & URLs<br />
    34. 34. Case Study – Candy Store<br />26<br />CandyStore<br />/candystore<br />GET<br />Candies <br />/candystore/candies?restock={restock?}<br />GET, POST<br />Candy<br />/candystore/candies/{productcode}<br />GET, PUT, DELTE<br />CandyManager<br />/candystore/candymanager<br />POST<br />Methods and URLs<br />
    35. 35. Design Considerations<br />27<br />A snap-shot of the state of a resource<br />Sent to server in request<br />Returned to client in response<br />Multi-format XML/JSON/ATOM<br />“Representations hold data transferred between client and server”<br />Representations<br />
    36. 36. Design Exercise – Candy Store<br />28<br />{<br />“productcode” : “alf123”,<br />“title” : “Wham Bar”,<br />“description” : “Sticky, fizzy chew bar.”,<br />“wholesaleprice”: 0.25,<br />“saleprice” : 0.5,<br />“stockcount” : 14,<br />“restocklevel” :5<br />}<br />Representations<br />
    37. 37. Case Study – Candy Store<br />29<br />Webscript Definition Document<br />
    38. 38. Implementation Considerations<br />30<br />JS API vs Fundamental API<br />Repository vs Spring<br />Runtime vs Compile<br />Flexibility vs Concrete<br />“No right or wrong answer, only what works best for you.”<br />JavaScript vs Java Backed<br />
    39. 39. Implementation Considerations<br />31<br />Extend BaseWebScriptTest<br />Mock Webscript server<br />Local and remote testing with same test code<br />Test before you use<br />“Untested API slows down application development”<br />Unit testing<br />
    40. 40. Java Backed Webscripts<br />32<br />
    41. 41. Questions<br />33<br />
    42. 42. Learn More<br />34<br />wiki.alfresco.com<br />forums.alfresco.com<br />twitter: @AlfrescoECM<br />