The document discusses the Surf API and remote scripting capabilities in Alfresco. It provides examples of using the Surf context, user, and remote objects to make requests to remote repositories and services. Specifically, it shows retrieving HTML from the repository using the remote API and retrieving CMIS XML content for the company home folder. Key objects covered include the context, user, remote, and how to configure endpoints, connectors, and authenticators for remote connections.

1. Alfresco Surf Code Camp
Remoting and Component API

2. Objectives
By the end of this module you should know
• Useful JavaScript objects
• Surf remoting concepts
• How & why you'd use Surf's proxy
• How to retrieve and work with XML and JSON returned by scripts
in the Repository tier
12/01/09 Optaros and Client confidential. All rights reserved. 2

3. Surf API
Objects and Methods available to Renderers
Renderer Types
• Web Script
• FreeMarker
• Java
• JSP
12/01/09 3

4. Surf API Brief Examples
JavaScript Example
var username = context.user.id;
FreeMarker Example
<#assign username = context.user.id>
${username}
JSP Example
<%
String username = RequestUtil.getRequestContext().getUser().getId();
%>
<%=username%>
12/01/09 4

5. Web Scripts and FreeMarker
Focus only on the Web Script and FreeMarker API
• http://wiki.alfresco.com/wiki/Surf_Platform_-_Freemarker_Template_and_Jav
Java API not yet documented online
12/01/09 5

6. Renderer Root Scoped Objects
context
• The request context
user
• The current user
content
• The content object being rendered
instance
• The renderer instance (equivalent of quot;thisquot;)‫‏‬
sitedata
• Site Construction helper
remote
• Connection management helper
12/01/09 6

7. Root-scoped: context ScriptRequestContext
The request context for the currently executing page
Useful variables:
• page The page being rendered
• template The template being used to render
• user The current user
• content The content object being dispatched (if available)‫‏‬
Examples:
var page = context.page;
model.pageName = page.title;
model.pageDescription = page.description;
model.templateId = context.template.id;
12/01/09 7

8. Root-scoped: user
ScriptUser
The current user
Useful variables:
• firstName The user’s first name
• lastName The user’s last name
• fullName A full name representation of the user
• properties An associative array of custom properties
Examples:
var user = context.user;
model.fullName = user.fullName;
model.email = user.companyEmail;
model.team = user.properties[“{http://www.alfresco.org/model/content/1.0}team”];
12/01/09 8

9. Root-scoped: remote
ScriptRemote
A remote connection helper
Access to Alfresco Web Framework remoting faciltiies
Stateless Connections
Stateful Connections (scoped to user)‫‏‬
Credential Management and Binding (stateful)‫‏‬
Credential Vault (persistent and non-persistent)‫‏‬
Customizable (XML config driven)‫‏‬
12/01/09 9

10. Remoting Configurations
Configurable definitions for:
• Endpoints
• Connectors
• Authenticators
These are entirely configurable
webscript-framework-config-remote.xml
• /WEB-INF/classes/alfresco
12/01/09 10

11. Remoting Configurations
Get a connector for a given endpoint
Endpoints
• any arbitrary id
• defines connection information to Endpoint
the remote location
Connector Connector
• knows how to “talk” with specific types
of back end servers
Authenticator
Authenticator
• knows how to “handshake” for authentication
with back end servers
• Alfresco Ticket, MediaWiki, WordPress, etc.
12/01/09 11

12. Remoting Configurations
www.wikipedia.org alfresco.com
Endpoint
HTTP RMI Alfresco
Connectors
Authenticators mediawiki alfresco wordpress
12/01/09 12

13. Remote Configuration Endpoints
Endpoints
<config evaluator=quot;string-comparequot; condition=quot;Remotequot;>
<remote>
<endpoint>
<id>alfresco</id>
<name>Alfresco - user access</name>
<connector-id>alfresco</connector-id>
<endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>
<identity>user</identity>
</endpoint>
</remote>
</config>
Properties
• id The endpoint ID
• connector-id The ID of the connector when connecting
• endpoint-url The base URL for the connection
• identity How to manage user connection state
12/01/09 13

14. Remote Configuration Connectors
Connectors
<config evaluator=quot;string-comparequot; condition=quot;Remotequot;>
<remote>
<connector>
<id>alfresco</id>
<name>Alfresco Connector</name>
<class>org.alfresco.connector.AlfrescoConnector</class>
<authenticator-id>alfresco-ticket</authenticator-id>
</connector>
</remote>
</config>
Properties
• id The connector ID
• class The Java implementation class name
• authenticator-id The ID of the authenticator to use
12/01/09 14

15. Remote Configuration Authenticators
Authenticator
<config evaluator=quot;string-comparequot; condition=quot;Remotequot;>
<remote>
<authenticator>
<id>alfresco-ticket</id>
<name>Alfresco Authenticator</name>
<class>org.alfresco.connector.AlfrescoAuthenticator</class>
</authenticator>
</remote>
</config>
Properties
• id The authenticator ID
• class The Java implementation class name
12/01/09 15

16. Root-scoped: remote
ScriptRemote
connect(endpointId)‫‏‬
• Retrieves a ScriptRemoteConnector instance for the given
endpoint
• Creates a new Connector
• Binds it to the given endpoint
• Binds it to the current user
ScriptRemoteConnector Methods
• get(uri)‫‏‬
• post(uri, body)‫‏‬
• post(uri, body, contentType)‫‏‬
• put(uri, body)‫‏‬
• put(uri, body, contentType)‫‏‬
• delete(uri)‫‏‬
12/01/09 16

17. Example #1: HTML
JavaScript
// get a connector to the Alfresco Endpoint
// this endpoint has a base URI of /alfresco/service
var connector = remote.connect(“alfresco”);
// retrieve the index of web scripts
var html = connector.get(“/index”);
// store html onto model
model.html = html;
FreeMarker
${html}
12/01/09 17

18. Example #2: CMIS XML
JavaScript
// get a connector to the Alfresco Endpoint
var connector = remote.connect(“alfresco”);
// retrieve the company home folder
var cmis = connector.get(“/api/path/workspace/SpacesStore”);
12/01/09 18

19. Example #2: CMIS XML
<?xml version=quot;1.0quot; encoding=quot;UTF-8quot;?>
<entry xmlns=quot;http://www.w3.org/2005/Atomquot; xmlns:app=quot;http://www.w3.org/2007/appquot; xmlns:cmis=quot;http://www.cmis.org/2008/05quot;
xmlns:alf=quot;http://www.alfresco.orgquot;>
<author><name>System</name></author>
<content>56923743-7436-482e-b1cf-eda326d11dc2</content>
<id>urn:uuid:56923743-7436-482e-b1cf-eda326d11dc2</id>
<link rel=quot;selfquot; href=quot;http://localhost:8080/alfresco/service/api/node/workspace/SpacesStore/56923743-7436-482e-b1cf-
eda326d11dc2quot;/>
<link rel=quot;editquot; href=quot;http://localhost:8080/alfresco/service/api/node/workspace/SpacesStore/56923743-7436-482e-b1cf-
eda326d11dc2quot;/>
<link rel=quot;cmis-allowableactionsquot; href=quot;http://localhost:8080/alfresco/service/api/node/workspace/SpacesStore/56923743-
7436-482e-b1cf-eda326d11dc2/permissionsquot;/>
<link rel=quot;cmis-relationshipsquot; href=quot;http://localhost:8080/alfresco/service/api/node/workspace/SpacesStore/56923743-7436-
482e-b1cf-eda326d11dc2/associationsquot;/>
<link rel=quot;cmis-childrenquot; href=quot;http://localhost:8080/alfresco/service/api/node/workspace/SpacesStore/56923743-7436-482e-
b1cf-eda326d11dc2/childrenquot;/>
<link rel=quot;cmis-descendantsquot; href=quot;http://localhost:8080/alfresco/service/api/node/workspace/SpacesStore/56923743-7436-
482e-b1cf-eda326d11dc2/descendantsquot;/>
<link rel=quot;cmis-typequot; href=quot;http://localhost:8080/alfresco/service/api/type/folderquot;/>
<link rel=quot;cmis-repositoryquot; href=quot;http://localhost:8080/alfresco/service/api/repositoryquot;/>
<published>2008-09-10T09:16:32.421-05:00</published>
<summary>The company root space</summary>
<title>Company Home</title>
<updated>2008-09-10T09:17:19.328-05:00</updated>
<cmis:object>
<cmis:properties>
<cmis:propertyId cmis:name=quot;ObjectIdquot;><cmis:value>workspace://SpacesStore/56923743-7436-482e-b1cf-
eda326d11dc2</cmis:value></cmis:propertyId>
<cmis:propertyString cmis:name=quot;BaseTypequot;><cmis:value>folder</cmis:value></cmis:propertyString>
<cmis:propertyString cmis:name=quot;ObjectTypeIdquot;><cmis:value>folder</cmis:value></cmis:propertyString>
<cmis:propertyString cmis:name=quot;CreatedByquot;><cmis:value>System</cmis:value></cmis:propertyString>
<cmis:propertyDateTime cmis:name=quot;CreationDatequot;><cmis:value>2008-09-10T09:16:32.421-
05:00</cmis:value></cmis:propertyDateTime>
<cmis:propertyString cmis:name=quot;LastModifiedByquot;><cmis:value>System</cmis:value></cmis:propertyString>
<cmis:propertyDateTime cmis:name=quot;LastModificationDatequot;><cmis:value>2008-09-10T09:17:19.328-
05:00</cmis:value></cmis:propertyDateTime>
<cmis:propertyString cmis:name=quot;Namequot;><cmis:value>Company Home</cmis:value></cmis:propertyString>
<cmis:propertyId cmis:name=quot;ParentIdquot;/>
</cmis:properties>
</cmis:object>
<cmis:terminator/>
<app:edited>2008-09-10T09:17:19.328-05:00</app:edited>
<alf:icon>http://localhost:8080/alfresco/images/icons/space-icon-default-16.gif</alf:icon>
</entry>
12/01/09 19

20. Example #2: CMIS XML
Essentially…
<?xml version=quot;1.0quot; encoding=quot;UTF-8quot;?>
<entry xmlns=quot;http://www.w3.org/2005/Atomquot; xmlns:app=quot;http://www.w3.org/2007/appquot;
xmlns:cmis=quot;http://www.cmis.org/2008/05quot;
xmlns:alf=quot;http://www.alfresco.orgquot;>
<cmis:object>
<cmis:properties>
<cmis:propertyId cmis:name=quot;ObjectIdquot;>
<cmis:value>
workspace://SpacesStore/56923743-7436-482e-b1cf-eda326d11dc2
</cmis:value>
</cmis:propertyId>
<cmis:propertyString cmis:name=quot;Namequot;>
<cmis:value>Company Home</cmis:value>
</cmis:propertyString>
</cmis:properties>
</cmis:object>
<cmis:terminator/>
</entry>
12/01/09 20

21. Example #2: CMIS XML
JavaScript
// get a connector to the Alfresco Endpoint
var connector = remote.connect(“alfresco”);
// retrieve the company home folder
var cmis = connector.get(“/api/path/workspace/SpacesStore”);
// load XML into E4X
var xml = new XML(cmis);
// populate the model
var properties = xml.*::object.*::properties;
model.id = properties.(@name=“ObjectId”).*::value;
model.name = properties.(@name=“Name”).*::value;
FreeMarker
Object id: ${id}
<br/>
Object name: ${name}
12/01/09 21

22. Example #3: JSON
JavaScript
// get a connector to the Alfresco Endpoint
var connector = remote.connect(“alfresco”);
// retrieve a content object
var nodeRef = “workspace://SpacesStore/56923743-7436-482e-b1cf-eda326d11dc2”;
var data = connector.get(“/api/metadata?nodeRef=” + nodeRef);
12/01/09 22

23. Example #3: JSON
{
quot;typequot;: quot;{http://www.alfresco.org/model/content/1.0}folderquot;,
quot;aspectsquot;: [
quot;{http://www.alfresco.org/model/content/1.0}auditablequot;,
quot;{http://www.alfresco.org/model/application/1.0}uifacetsquot;,
quot;{http://www.alfresco.org/model/system/1.0}referenceablequot;
],
quot;nodeRefquot;: quot;workspace://SpacesStore/56923743-7436-482e-b1cf-eda326d11dc2quot;,
quot;propertiesquot;: {
quot;{http://www.alfresco.org/model/application/1.0}iconquot;: quot;space-icon-defaultquot;,
quot;{http://www.alfresco.org/model/content/1.0}descriptionquot;: quot;The company root spacequot;,
quot;{http://www.alfresco.org/model/system/1.0}node-uuidquot;: quot;56923743-7436-482e-b1cf-eda326d11dc2
quot;{http://www.alfresco.org/model/system/1.0}node-dbidquot;: 15,
quot;{http://www.alfresco.org/model/content/1.0}titlequot;: quot;Company Homequot;,
quot;{http://www.alfresco.org/model/content/1.0}createdquot;: quot;Wed Sep 10 09:16:32 CDT 2008quot;,
quot;{http://www.alfresco.org/model/content/1.0}modifierquot;: quot;Systemquot;,
quot;{http://www.alfresco.org/model/content/1.0}modifiedquot;: quot;Wed Sep 10 09:17:19 CDT 2008quot;,
quot;{http://www.alfresco.org/model/content/1.0}creatorquot;: quot;Systemquot;,
quot;{http://www.alfresco.org/model/system/1.0}store-protocolquot;: quot;workspacequot;,
quot;{http://www.alfresco.org/model/content/1.0}namequot;: quot;Company Homequot;,
quot;{http://www.alfresco.org/model/system/1.0}store-identifierquot;: quot;SpacesStorequot;
},
quot;mimetypequot;: quot;application/octet-streamquot;
}
12/01/09 23

24. Example #3: JSON
JavaScript
// get a connector to the Alfresco Endpoint
var connector = remote.connect(“alfresco”);
// retrieve a content object
var nodeRef = “workspace://SpacesStore/56923743-7436-482e-b1cf-eda326d11dc2”;
var data = connector.get(“/api/metadata?nodeRef=” + nodeRef);
// create a javascript object from the json
var json = eval('(' + data + ')');
// populate the model
model.id = json.nodeRef;
model.name = json.properties[“{http://www.alfresco.org/model/content/1.0}name“];
FreeMarker
Object id: ${id}
<br/>
Object name: ${name}
12/01/09 24

25. Proxy Services
You can either use connectors directly or via a proxy
Alfresco Surf provides a proxy servlet that uses this
connector facility underneath the hood
http://labs3c:8580/sample/proxy/{endpointId}/{uri}
12/01/09 25

26. Proxy Services
http://labs3c:8580/sample/proxy/alfresco/index
• Identifies the “alfresco” endpoint
• The base URI on the endpoint is “/alfresco/service”
• This proxies through to:
http://labs3c:8080/alfresco/service/index
• User connector session state is stamped onto the proxied
connection
Optimizations
• No buffering
• Headers are captured and some retained if related to connector
sessions
• Input and output streams flow through
12/01/09 26

27. Wrap-up
In this module, you learned...
• Useful JavaScript objects
• Surf remoting concepts
• How & why you'd use Surf's proxy
• How to retrieve and work with XML and JSON returned by scripts
in the Repository tier
12/01/09 Optaros and Client confidential. All rights reserved. 27