Functional overview
AWPr is a JSR-168 portlet that exposes a configurable Alfresco Web script that can be hosted on a server that is remote to the portal in which the portlet is running. The following is a list of AWPr's features:
- JSR-168 portlet (different portals will require minor code changes)
- Configurable Web script information
- Alfresco host (the server running the Alfresco instance of choice)
- Web script URL (one of the URLs that can be used to access the Web script)
- HTTP method (the HTTP method that the Web script expects - usually GET)
- Web script parameters (an array of name/value pairs defining the URL parameters needed by the Web script and their default values)
- and more...(we add features as the user community demands them)
- Authenticate with Alfresco as the currently logged in portal user and use the resulting Alfresco ticket for all requests from the portlet to the Web script (the ticket is portlet session scoped).
- Proxy all script URLs coming back from the Web script so that when the user clicks on a Web script link inside AWPr the request would go to the portal rather than direcly to the Alfresco instance
 | Note Starting with AWPr version 1.4.0 AWPr has now become a JSR-286 portlet since it makes use of the Portlet 2.0 resource phase for document downloads. |
Authentication
To pass authentication through from the portal to Alfresco we wrote a custom Alfresco authentication component (aka STAr which stands for Secure Token Authentication rivet) that expects:
- Username
- AES encrypted password
The authentication component should be configured (via Spring) with a password string; it could also be chained using the Alfresco authentication chaining feature. When an authentication attempt is made, STAr will decrypt the password using a Base64 key. If the resulting string matches the configured string, authentication is considered to be successful.
When an AWPr instance's portlet session is created, the portlet (which is aware of the STAr configured password and the Base64 key) will encrypt the password, figure out the currently logged in user's username, and call a login Web script with the username/password combination sent as URL parameters. If the username exists in that Alfresco instance a ticket will be returned. For the duration of the portlet session the AWPr instance will use that ticket for all communication with the Web script. The following diagram illustrates what a typical deployment that makes use of AWPr would look like:
Note: Starting with AWPr version 1.4.0 two new <init-param>'s were added to portlet.xml to externalize the STAr key and password. The init params are:
<init-param>
<name>star-key</name>
<value>QVdQclJvY2tzQmFieSEhIQ==</value>
</init-param>
<init-param>
<name>star-password</name>
<value>portal</value>
</init-param>
Script URL proxy
This feature is what makes it possible for the Web script developer to create webscripts that can run both inside an AWPr instance and outside of the portal as a standalone Alfresco Web script. The way this is done is best explained through an example. If you are trying to write a weather HTML Web script with the URL '/ui/weather' and you want to make this an interactive script that allows the user to switch between rendering styles for the Web script, this would most probably mean that when someone visits this Web script and enters their zip-code the resulting HTML will include links similar to the following:
<a href="/ui/myscript?zip=22101&style=simple" >Simple</a> |
<a href="/ui/myscript?zip=22101&style=summary" >Summary</a> |
<a href="/ui/myscript?zip=22101&style=detailed" >Detailed</a>
If you access this Web script directly the URLs above will remain unchanged, but if this same Web script is exposed through an AWPr instance called AWPrWeatherWindow running in JBoss Portal on a page called Weather in the default portlet, the portlet's code will find those URLs and replace them with the following before sending the markup over to the end-user's browser:
<a href="/portal/auth/portal/default/Weather/AWPrWeatherWindow?action=1&zip=22101&style=simple" >Simple</a> |
<a href="/portal/auth/portal/default/Weather/AWPrWeatherWindow?action=1&zip=22101&style=summary" >Summary</a> |
<a href="/portal/auth/portal/default/Weather/AWPrWeatherWindow?action=1&zip=22101&style=detailed" >Detailed</a>
So when the user clicks on one of those links, the HTTP request will end up going to that portlet instance, the request parameters will be picked up by the portlet and another RESTful call made to the target Web script. Therefore the portal user will continue to interact with the Web script within the confines of the portlet window.
This allows developers to maximize the reusability of their code.
Versions >= 1.1.0:
Starting version 1.1.0 a new portlet preference was added to allow users to specify what Web script URLs should be proxied. This allows developers to create Web scripts applications with navigation where each page could be a different Web script. The value for this portlet preference is composed of one or more Web script URLs enclosed in curly braces '{ }'. The format of the portlet preference is explained in the Portlet Preferences section.
The portlet preference is named proxyUrl and works as follows:
Note: If no flag is specified then both parameterized and non-parameterized URLs will be proxied.
| Value |
URL |
Proxied? |
|---|---|---|
| {/ui/page1} |
href="/alfresco/wcservice/ui/page1?a=1&b=2" |
YES |
| {/ui/page1} |
href="/alfresco/wcservice/ui/page1" |
YES |
| {/ui/page1,P} | href="/alfresco/wcservice/ui/page1?a=1&b=2" |
YES |
| {/ui/page1,P} | href="/alfresco/wcservice/ui/page1" |
NO |
| {/ui/page1,N} |
href="/alfresco/wcservice/ui/page1" |
YES |
| {/ui/page1,N} |
href="/alfresco/wcservice/ui/page1?a=1&b=2" |
NO |
Versions >= 1.2.0:
Starting version 1.2.0 a new portlet preference called proxyAllUrls was added to instruct the portlet to proxy all Web script URLs. This setting defaults to "true" and will make AWPr ignore the value of proxyUrls.
AJAX calls
If your Web script needs to make AJAX calls (like the My Spaces Web script does), AWPr provides a javascript object that contains a method that will change a URL to make sense within a portlet. The resulting URL would look much like the proxied URLs that you get back from AWPr.
For instance, if your Web script is being called using a direct connection to Alfresco via an AJAX call, the resulting markup will probably contain URLs that will reference the script URL directly like so:
<a href="/alfresco/wcservice/myscript?arg1=1&arg2=2" >Click Here</a>
Your javascript code could then utilize a method with the following signature:
AWPr.encodeUrl(url)
to convert a URL to the portal's action URL so that when that URL is clicked the request would go to the AWPr instance running the Web script.
An example of your javascript code could look like this:
var navLinks = $$('#divID .linkCSSClass');
navLinks.each(
function(navLink, i) {
navLink.setHTML('<a href="' + AWPr.encodeUrl(navLink.innerHTML.replace(/&/, "&")) + '">Click Here</a>');
}
);
Versions >= 1.1.0:
Starting with version 1.1.0 a new portlet preference was added to allow for the AWPr javascript variable name to be configured per AWPr portlet instance. This allows more than one AWPr instance to exist on one portal page. The Web script developer will have to know the name of the javascript variable and write the Web script AJAX calls accordingly.
The portlet preference is named jsVariable and works as follows:
| jsVariable value | Javascript variable in browser |
|---|---|
| ABC |
var AWPr_ABC.encodeUrl() |
| Not set |
var AWPr.encodeUrl() |
Portlet preferences
The following is the list of portlet preferences expected by AWPr:
| Preference |
Format |
Description |
Example |
|---|---|---|---|
| alfrescoHost | URL | The host where the Alfresco instance hosting the Web script lives |
http://alfresco.rivetlogic.com |
| alfrescoContextPath | URI | The context path of the Alfresco instance |
/alfresco |
| httpMethod | GET/POST/... | The HTTP method of choice for the Web script |
GET (default) |
| webscriptParams | {name}[value],{name}[value],... | A list of name/value pairs representing the Web script arguments and possible default values. If no default value is required it could be left blank. |
{zip}[22101],{style}[detailed],{timezone}[GMT] |
| webscriptUrl | URI | The Web script URL pattern as defined in the Web script definition |
/ui/weather |
Versions >= 1.1.0:
Starting version 1.1.0 we added three new portlet preferences:
| Preference |
Format |
Description |
Example |
|---|---|---|---|
| jsVariable |
String |
What string should be added to the end of the AWPr javascript variable used for encoding URLs on the client side |
A value of ABC causes the creation of javascript var AWPr_ABC |
| proxyUrls |
{url,flag} or {url}... |
A list of Web script URLs that will be proxied. An optional flag can be set to select whether Parametrized (P) or Non-parameterized (N) only Web script URLs are to be proxied. If a flag is not set then both parameterized and non-parameterized Web script URLs will be proxied. The value of the webscriptUrl portlet preference must be among the proxyUrls. |
{/ui/script/page1},{/ui/script/page2,P},{/ui/script/page3,N} |
| charEncodingType |
UTF-8 or ISO-8859-1 |
The character encoding type to use when encoding request parameter values |
UTF-8 (default) |
Versions >= 1.5.0
Starting AWPr version 1.5.0 we have introduced a new portlet preference and redefined an already existing portlet preference. The following table details this:
| Preference |
Format |
Description |
Example |
|---|---|---|---|
| constantScriptParams |
{name}[value],{name}[value],... | The name/value pairs listed here will will be sent as URL parameters on every request that goes from the AWPr instance to the Web script defined in the webscriptUrl preference. | {alfUrl}[http://acmeportal.com/alfresco] |
| webscriptParams | {name}[value],{name}[value],... | The name/value pairs listed here will be used as default URL parameters only the first time the Web script is called during a portlet session. The only other time these URLs will be sent during a portlet session is when the portlet preferences are changed. Note: The behavior mentioned above will be applied in portals that follow the portlet spec's definition of Render Request Parameters. In Liferay Portal this behavior is not the default but can be modified by adding the following to portal-ext.properties: # # Set the default value for the "p_l_reset" parameter. If set to true, then # render parameters are cleared when different pages are hit. This is not # the behavior promoted by the portlet specification, but is the one that # most end users seem to prefer. # layout.default.p_l_reset=false |
{f}[1],{p}[Company Home] |
HTML Forms
Versions >= 1.5.0
Starting AWPr version 1.5.0 HTML forms are fully supported. The appropriate way to do this would be to create two Web scripts:
- A GET Web script that contains the HTML form. All form field names (including hidden fields) must be prepended with "awprform."
- A POST Web script that receives the HTTP POST request and does the processing for the form. This Web script will get the URL parameter names without the "awprform." prefix.
Document downloads
Versions >= 1.4.0
AWPr supports safe document downloads from Alfresco through AWPr without the need for exposing Alfresco to public internet. This is achieved by making use of Portlet 2.0's resource phase. Right now we're only proxying the following Web script API call:
GET /alfresco/service/api/node/content/{store_type}/{store_id}/{id}/{file-name}?a={attach?}
You must have this Web script call in the markup of your Web scripts for all document download URLs. AWPr will proxy these URLs and translate them to Portlet 2.0 resource URLs. This way the Alfresco ticket does not need to be exposed to the browser.
Things you ought to know
Versions <= 1.2.0
It is important to note that AWPr will only send the parameters specified in the webscriptParams portlet preference over to the Web script so make sure that you define all the paramters that your Web script uses in the portlet preferences even if they are not needed initially. For instance if you have three parameter a, b and c, but only a is needed initially with a default value of 1, then the value of the webscriptParams preference should be:
webscriptParams = {a}[1],{b}[],{c}[]
Notice that b and c have been specified with blank values which is OK. Just make sure all your parameters are explicitly specified.
Version 1.3.0 and above don't have this restriction and will proxy any request parameter.