Chapter 1. Getting Familiar with Web Scripts

In this chapter, we will cover the following topics:

Understanding web scripts
Reasons to use web scripts
Understanding when to use a web script
Understanding where web scripts can be used
Understanding how web scripts work
Types of web scripts

Consider a scenario where you have to work on a project to develop a customized business solution with a backend repository such as an Alfresco content management system. It is going to be an integration project with the Alfresco content repository. The end goal is to build up a business implementation that has a custom frontend application interacting with the Alfresco repository in a secure way in order to allow the end users to access the content on demand and to provide access to features of the Alfresco repository. Basically, you want to create, update, and delete content in the Alfresco repository and are interested in retrieving the required content on demand from the Alfresco repository from the custom frontend application in a secure way.

Now, you might have a lot of questions on your mind. You must be curious to find out how it is possible to access the Alfresco repository from the custom frontend application. What are the possible alternatives to access the content residing in the Alfresco repository from the custom frontend application? Is it going to be a complex implementation to build up an API accessing the Alfresco repository? Is it going to be a secure communication from the frontend application to the backend repository? How is it going to maintain the client state during the communication with the Alfresco repository in order to access, update, or delete content from the repository based on the user's access? And the list of questions still goes on…

Whenever there is a question, there is an answer. Also, the answer to all of your previous questions is Alfresco web scripts. Using web scripts, you can build up a customized integration solution using Alfresco as the backend content repository.

It is always a good idea when we start learning about any new topic to always start with the "5Ws and 1H". It's basically the who, what, when, why, where, and how questions. This helps us to understand the topic in a better way. In this chapter, we are going to find out the useful information about web scripts by discovering the answers to some of the basic questions such as what, why, when, where, and how. Let's start and find out the answers to them and understand web scripts in a better way.

Understanding web scripts

In order to understand web scripts in Alfresco, let's begin with finding out the answer to the question "What is a web script?" from multiple perspectives.

In simple words, web scripts can be explained as follows:

Web scripts are powerful and extremely useful services supported by Alfresco
They are a way to interact with the Alfresco repository securely
They are reusable across different platforms
Web scripts provide uniform access of the content to a wide range of client applications

In technical terms, web scripts can be defined as follows:

They are RESTful web services
Note
What is RESTful?
REST stands for REpresentational State Transfer, which is basically an architectural style. Well-defined and uniform access to the resources through HTTP request methods, uniquely identified resources through the URI, and representation of these resources are the key principles of REST. Any implementation following this architectural style is known as RESTful.
They are bound to a specific Uniform Resource Identifier (URI)
They respond to HTTP methods such as GET, POST, PUT, and DELETE
They are a lightweight implementation

From a developer's point of view, web scripts have the following properties:

They are easy to understand and learn
They are easy to develop
They are easy to debug
They are easy to maintain
They are easy to deploy
They are faster to implement
They would be the first choice when it comes to accessing the Alfresco repository securely from external applications

From a business user's point of view, web scripts are useful as follows:

They bridge the gap between the business requirement and technical implementation for building up business solutions with Alfresco
They empower Alfresco in its integration capabilities to develop useful Alfresco integration solutions with external systems
They are a unique way to implement the integration solutions on top of the Alfresco repository
They are the backbone of the integration solution implementation with the Alfresco repository

In essence, web scripts can be talked about as follows:

Web scripts are built on the idea of URL addressability
Web scripts are simply a service, mapped to a human-readable form, and developed using a piece of code as their backend implementation
For example, in a contract management system built using Alfresco as the backend repository, you can have a web script to retrieve all the draft agreements from the repository and then display them on the custom frontend application. This repository web script to get all the draft agreements will simply be accessed through its URL. This web script will also have a piece of code in the backend to retrieve the data from the Alfresco repository to produce the results in the formats as required. The URL for this web script might look like the following:
```
/alfresco/service/contract/get_draft_agreements
```

Reasons to use web scripts

It's now time to discover the answer to the next question—why web scripts? There are various alternate approaches available to interact with the Alfresco repository, such as CMIS, SOAP-based web services, and web scripts. Generally, web scripts are always chosen as a preferred option among developers and architects when it comes to interacting with the Alfresco repository from an external application. Let's take a look at the various reasons behind choosing a web script as an option instead of CMIS and SOAP-based web services.

In comparison with CMIS, web scripts are explained as follows:

In general, CMIS is a generic implementation, and it basically provides a common set of services to interact with any content repository. It does not attempt to incorporate the services that expose all features of each and every content repository. It basically tries to cover a basic common set of functionalities for interacting with any content repository and provide the services to access such functionalities.
Alfresco provides an implementation of CMIS for interacting with the Alfresco repository. Having a common set of repository functionalities exposed using CMIS implementation, it may be possible that sometimes CMIS will not do everything that you are aiming to do when working with the Alfresco repository. While with web scripts, it will be possible to do the things you are planning to implement and access the Alfresco repository as required. Hence, one of the best alternatives is to use Alfresco web scripts in this case and develop custom APIs as required, using the Alfresco web scripts.
Another important thing to note is, with the transaction support of web scripts, it is possible to perform a set of operations together in a web script, whereas in CMIS, there is a limitation for the transaction usage. It is possible to execute each operation individually, but it is not possible to execute a set of operations together in a single transaction as possible in web scripts.

SOAP-based web services are not preferable for the following reasons:

It takes a long time to develop them
They depend on SOAP
Heavier client-side requirements
They need to maintain the resource directory
Scalability is a challenge
They only support XML

In comparison, web scripts have the following properties:

There are no complex specifications
There is no dependency on SOAP
There is no need to maintain the resource directory
They are more scalable as there is no need to maintain session state
They are a lightweight implementation
They are simple and easy to develop
They support multiple formats

In a developer's opinion:

They can be easily developed using any text editor
No compilations required when using scripting language
No need for server restarts when using scripting language
No complex installations required

In essence:

Web scripts are a REST-based and powerful option to interact with the Alfresco repository in comparison to the traditional SOAP-based web services and CMIS alternatives
They provide RESTful access to the content residing in the Alfresco repository and provide uniform access to a wide range of client applications
They are easy to develop and provide some of the most useful features such as no server restart, no compilations, no complex installations, and no need of a specific tool to develop them
All these points make web scripts the most preferred choice among developers and architects when it comes to interacting with the Alfresco repository

Understanding when to use a web script

Having understood what a web script is and the reasons for using web scripts, let's now understand when to use web scripts. When working with Alfresco, it is important to know in which scenarios web scripts can be used. Web scripts allow you to build custom URI-identified and HTTP-accessible Content Management Web services to access the Alfresco content repository, and hence they can be used in various kinds of implementations to build useful business solutions with Alfresco content management systems.

In development projects:

You can use web scripts to develop business implementations integrating Alfresco with external applications
You can develop customized web scripts as per your business requirement
You can leverage on the out-of-the-box web scripts available in Alfresco wherever they fit in your custom implementation

In support projects:

Web scripts could be your savior when you are working on a support or maintenance project to maintain the live system for your customers that is built on Alfresco and has millions of records.
You might come across a range of issues, for example, updating existing content to fix some data issues, deleting some unneeded content, getting the required content matching with the criteria specified by the business team, and so on. Web scripts can be used in such scenarios to serve these purposes.
On a live production system, it is not possible to restart the server, and restarting a server could impact the business of a customer. Consider a scenario where you need to fix some critical issues on a production system and you are looking for an option to have the issue fixed without restarting the server. The powerful feature of web scripts to interact with the Alfresco repository without restarting the server will help you in this case, and you can fix some critical issues using web scripts to provide a good content management experience to the business users.

In general, web scripts can be used in all kinds of solutions, such as:

Integrating Alfresco with external applications that can communicate with Alfresco using HTTP
Developing JSR-168 portlets to build up UI services
Developing data services
Providing feeds for repository content
Alfresco integration with Office
Developing Facebook applications
Building UI components in Alfresco SURF

Understanding where web scripts can be used

Now, it's time to understand where web scripts can be used. There are a number of different environments from where a web script can be accessed and used.

In different environments:

They can be used from an HTTP client such as a web browser and HTTP client APIs
It is also possible to access web scripts in JSF pages
They can be used in JSR-168 portals
They can be used from Facebook applications
Web scripts can be used in the Alfresco SURF platform as well

Understanding how web scripts work

Web scripts in Alfresco mostly use the model-view-controller pattern. However, it isn't mandatory to follow this pattern all the time. The way MVC pattern works in web scripts is as follows:

The controller is responsible for performing the required business logic as per the business requirement. After processing the business logic, controller populates the model object with the required data. Once this is done, controller will then forward the request to the view.

MVC in web scripts

The model-view-controller pattern in web scripts is explained as follows:

The controller is a server-side JavaScript or Java class or it could be both as well
The model is a data structure object passed between the controller and view
The view is a FreeMarker template that is responsible for generating the response in the required format

The mapping of the web script URI to the controller is done through a descriptor file. It is mainly an XML file that will have the required details for a web script such as URL, description, arguments, transaction, authentication, and response formats.

Response formats are mapped to FreeMarker templates through naming conventions. For example, a FreeMarker template that returns an HTML response will have the extension html.ftl.

Web scripts are registered and executed by the web script engine in Alfresco.

Note

A descriptor, optional controller, and one or more FreeMarker response templates collectively make a web script in general scenarios.

All these components are tied together through a specific document naming convention.

Making web scripts work

To make web scripts work, it is important to deploy the web script files at an appropriate location.

The descriptor file and the FreeMarker template as per the response format for a web script can be either placed on a filesystem or put into the Alfresco repository.

If a JavaScript-based controller is used for a web script, then it could be placed along with the descriptor and FreeMarker template on a filesystem or in the Alfresco repository.

If a Java-based controller is used for a web script, then the class file for the controller must be available on the class path.

Note

There are two types of controllers available for web scripts: JavaScript-based controllers and Java-based controllers. It is possible to have none of them, either of them, or even both of them for a web script.

Types of web scripts

There are two types of web script in Alfresco: Data web scripts and Presentation web scripts.

Data web script

Data web scripts provide an interface to the repository for the client applications to create, retrieve, update, and delete content/data in the repository. These web scripts typically send the response in formats such as XML and JSON, and client applications will have to parse it in order to use it further.

Data web scripts encapsulate access and modification of content/data residing in the repository. These web scripts are provided and exposed by the Alfresco repository server only.

Presentation web script

Presentation web scripts can be used to build user interfaces such as dashlets for Alfresco explorer, dashlets for Alfresco share, portlets for a JSR-168 portal, a UI component within Alfresco SURF, or a custom application.

These kinds of web scripts generally render HTML responses.

It is possible to host these web scripts on a separate presentation server or they can also be exposed by the Alfresco repository server.

Presentation web scripts generally make a call to Data web scripts in order to get the required data from the repository.

Note

Out-of-the-box web scripts available in an Alfresco installation can be found at ALFRESCO_HOME\tomcat\webapps\alfresco\WEB-INF\classes\alfresco\templates\webscripts\org\alfresco, where ALFRESCO_HOME is the base directory where Alfresco is installed.

If you are using Alfresco Community 5, you can find out-of-the-box web scripts under the alfresco package inside alfresco-remote-api-*.jar, which is available at ALFRESCO_HOME\tomcat\webapps\alfresco\WEB-INF\lib.

Summary

In this chapter, we gained a better understanding of web scripts through some of the basic questions about web scripts. We learned what web scripts in Alfresco are, why they are the preferred choice of developers, when and where we can use web scripts, how web scripts work, and also the different types of web scripts available in Alfresco.

In the next chapter, we are going to do a hands-on exercise to learn how to implement our first web script in Alfresco.