Accessing Content Services (deprecated) using Web Scripts

Writing a web script consists of creating all components that a web script requires. You must create an XML description document, an execute script written in JavaScript, and a response template.

To create a web script, perform the following steps:

1. Write the web script. (See Writing the web script.)

2. Store the web script. (See Storing web scripts.)

3. Register the web script. (See Registering web scripts.)

4. Invoke the web script. (See Invoking web scripts.)

Before you write a web script, decide which URL and HTTP method to use. A web script URL must start with http://[host]:[port]/contentspace/service/sample. The remainder of the URL is flexible, but it must be unique. For example, consider this URL:

• http://[host]:[port]/contentspace/service/sample/folder/Company Home/Test Directory

  To demonstrate how to create a web script, this section creates a web script that lists the contents of a specified directory. To create this web script, create the following files:

• A description document named folder.get.desc.xml. (See Creating a description document.)

• An execution script named folder.get.js. (See Creating an execution script.)

• A response template named folder.get.html.ftl. (See Creating a response template.)

The first step is to create an XML description file that describes the URL used to invoke the web script. The postfix .desc.xml informs Content Services (deprecated) that this script is a web script description document. Consider the following folder and file name:

service/sample/folder.get.desc.xml

Part of this URL defines the package, the service identifier value of folder, and a binding to the HTTP Get method. That is, the get part of the URL specifies that the HTTP GET method is used to invoke the web script. Likewise, to invoke the web script by using the HTTP POST method, the name needs to be folder.post.desc.xml.

The folder.get.desc.xml file consists of the following XML code.

<webscript> 
      <shortname>Folder Listing Sample</shortname> 
    <description>Sample demonstrating the listing of folder contents</description> 
    <url>/sample/folder/{path}</url> 
    <format default="html">argument</format> 
    <authentication>guest</authentication> 
    <transaction>required</transaction> 
</webscript>

To invoke this web script, specify the following URL:

http://<host>:<port>/contentspace/service/sample/folder/Company Home/Test Directory

The following list describes the elements in this XML file:

• shortname: Represents human readable name for the web script.

• description: (Optional) Represents a description for the web script.

• url: Represents a URL that the web script is bound to. There can be more than one url element.

• format: Represents how the required response content type is declared. These values are valid:

• argument: specifies that the required content type is declared by using the format URL argument (for example, /search?q=tutorial&format=atom).

• extension: specifies that the required content type is declared by using the URL extension (for example, /search.atom?q=tutorial).

• any: specifies that either of the above is supported (this is the default).

  Note: If the URL does not specify a required content type, the default content type is taken from the (optional) default attribute of the format element. By default, if not set, the “html” format is assumed. In some cases, a URL may decide on a response content type at run time. For these URLs, specify an empty format (for example, format="").

• authentication: Represents the required level of authentication. These values are valid:

  • none: Specifies that no authentication is required (this the default value).

  • guest: Specifies that at least guest authentication is required.

  • user: Specifies that at least named user authentication is required.

  • admin: Specifies that at least a named admin authentication is required.

• transaction: Represents the required level transaction. These values are valid:

  • none: Specifies that no transaction is required.

  • required: Specifies that a transaction is required (and will inherit an existing transaction, if open).

  • requiresnew: Specifies that a new transaction is required.

  Note: If not specified, the default value is none if authentication is also none; otherwise, the value is required.

    /content/a/b/c/d.txt /blog/search?q={searchTerm} 
    /blog/search?q={searchTerm}&n={numResults} 
    /blog/category/{category}?n={itemsperpage?} 
    /user/{userid}

    /content/a/b/c/d.txt (exact match) 
    /blog/search (starts with match) 
    /blog/category (starts with match) 
    /user/ (starts with match)

    /content/a/b/c/d.txt 
    /blog/search 
    /blog/search?q=tutorial 
    /blog/category 
    /blog/category/web20 
    /user/fred 

    /content/a/b/c/d.txt.plain 
    /blog 
    /usr/fred

An execution script is written in JavaScript and performs tasks such as querying or updating content. An execution script has access to objects such as these:

• argsM: An array of URL parameters (where each key is a parameter name and each value is an array that contains the parameter values, even if only one is supplied.

• url: Provides access to the URL (or parts of the URL) that invoked the web script.

• formdata: Provides access to multipart/form-data requests that allow the upload of files using by using web scripts.

• model: An empty array that may be populated by the web script. Values placed into this array are available as root objects in web script response templates.

• roothome: Repository root node.

• guest: Boolean indicating whether the web script is executing as Guest.

• server: An array of metadata properties that describe the repository server hosting the web script.

The following JavaScript code displays all content within a specified directory. The following script represents the code located in the folder.get.js file. (See Creating your first web script.)

// locate folder by path 
// NOTE: only supports path beneath company home, not from root 
var folder = roothome.childByNamePath(url.extension); 
if (folder == undefined || !folder.isContainer) 
{ 
    status.code = 404; 
      status.message = "Folder " + url.extension + " not found."; 
      status.redirect = true; 
    } 
    model.folder = folder;

Execution script file names have the following structure:

• [serviceId].[httpMethod].js

  The folder.get.js file specifies that the name of the web script is folder and the http method is GET.

var folder = roothome.childByNamePath(url.extension); 
if (folder == undefined || !folder.isContainer) 
{ 
    status.code = 404; 
      status.message = "Folder " + url.extension + " not found."; 
      status.redirect = true; 
    }

Create a response template that renders a response for the request. That is, a response template creates a response in a format such as HTML that is returned when a web script is invoked. Multiple response formats may be provided and each response is rendered as a FreeMarker template. This illustration shows the results of the response template that was created in this section and that displays content located in a specific folder (the Company Home folder is used in this example).

View full size graphic

The following code represents the folder.get.html.ftl file. (See Creating your first web script.)

<html> 
     <head> 
       <title>${folder.displayPath}/${folder.name}</title> 
     </head> 
     <body> 
       Folder: ${folder.displayPath}/${folder.name} 
       <br> 
       <table> 
        <#if folder.parent.parent?exists> 
        <tr> 
          <td><td><a href="${url.serviceContext}/sample/folder<@encodepath node=folder.parent/>">..</a> 
        </tr> 
        </#if> 
<#list folder.children as child> 
        <tr> 
          <#if child.isContainer> 
            <td>&gt;<td><a href="${url.serviceContext}/sample/folder<@encodepath node=child/>">${child.name}</a> 
          <#else> 
            <td><td><a href="${url.serviceContext}/api/node/content/${child.nodeRef.storeRef.protocol}/${child.nodeRef.storeRef.identifier}/${child.nodeRef.id}/${child.name?url}">${child.name}</a> 
          </#if> 
        </tr> 
</#list> 
       </table> 
     </body> 
</html> 
 
<#macro encodepath node><#if node.parent?exists><@encodepath node=node.parent/>/${node.name?url}</#if></#macro>

Response template file names have the following structure, where format specifies the format of the response template:

    <serviceId>.<httpMethod>.<format>.ftl

For example, folder.get.html.ftl specifies that the response format is in HTML.

The response template file has access to the following objects:

• argsM: Associative array of URL parameters, where each key is a parameter name and each value is an array that contains the parameter values (even if only one is supplied), complements the root object args.

• guest: Boolean indicating that indicates whether the web script is executing as Guest.

• date: Date representing that represents the date and time of the web script request.

• server: Associative array of metadata properties that describe the server hosting LiveCycle.

• roothome: Repository root node.

• url: Provides access to the URL (or parts of the URL) that invoked the web script.

• webscript: Associative array of metadata properties that describe this web script.

Response template files also have access to the following methods:

• absurl(url): Returns an absolute URL representation of the passed URL. Useful when rendering links within ATOM (and similar formats).

• xmldate(date): Returns an ISO8601 formatted result of the passed date. Useful when rendering dates as XML.

• scripturl(queryString): Returns a URL that references this web script. The passed queryString is added to the URL. System arguments such as guest and format are automatically added.

After you create the description document, the execution script, and the response template file, you must store these three files. You can store them in either of the following Content Services (deprecated) folders:

• /Company Home/Data Dictionary/Web Scripts Extensions

• /Company Home/Data Dictionary/Web Scripts

Within either of these folders, you can use subfolders to store web scripts.

The third step in creating a web script is to register it. If you do not register a web script, you cannot invoke it. New and updated web scripts can be registered without restarting LiveCycle.

You can invoke a web script after it is registered by using its URL, which is defined in the description XML file. For example, the following URL is defined in the folder.get.desc.xml:

• [url]/sample/folder/{path}[/url]

  This is only part of the invocation URL that is required to invoke the web script. You must combine this part with http://[host]:[port]/contentspace/service/. The entire invocation URL that is used to invoke the web script that is created in this section is as follows:

• http://localhost:8080/contentspace/service/sample/folder/Company Home/Test Directory

  This URL returns a list of all content that is located in the Company Home/Test Directory folder. For example, assume that this folder contains two PDF files named AssemblerResultBatesPDF.pdf and Loan.pdf. This illustration shows the results of the web script that displays all content in a specified folder.

  View full size graphic

  Web scripts are executed as the currently authenticated user at the time the web script is invoked. Some web scripts do not require authentication, in which case, they either do not access the Content Services (deprecated) repository, or they execute as a predefined user. If a web script requires authenticated access and the request is unauthenticated, a login dialog box appears, as shown in this illustration.

  View full size graphic

This section discusses how to create the following web scripts:

• Creating a web script that uploads files

• Creating a web script that deletes files

• Creating a web script that performs a blog search

Before you read this section, it is recommended that you be familiar with creating web scripts. (See Creating your first web script.)

This section discusses how to create a web script that uploads content to Content Services (deprecated). This web script is divided into two web scripts and shows how to create a file upload URL service. The first web script creates a basic HTML form that has three form fields, one that is of type file, as shown in this illustration.

View full size graphic

The HTML form invokes the second web script that parses the posted data request and then uploads a new file.

This section describes root objects that can used within web scripts. Most of these objects are used in the script examples located in this section. (See Creating your first web script.) The following list describes web script root objects:

• cache: An array of cache control properties that enable control over how the web script response is cached. This object contains the following fields:

  • neverCache: A Boolean value that specifies whether the web script response needs to be cached. The value true means never cache. If not set, the default value is specified by the cache control section of the web script definition.

  • isPublic: A Boolean value that specifies whether the web script response needs to be cached by public caches. If not set, the default value is specified by the cache control section of the web script definition file.

  • mustRevalidate: A Boolean value that controls whether the cache must revalidate its version of the web script response to ensure an updated version. If not set, the default value is specified by the cache control section of the web script definition file.

  • maxAge: A long value that specifies the maximum amount of time (in seconds, relative to the time of request) that the response will be considered fresh. If not set, the default value is null.

  • lastModified: A date value that specifies the time that the content of the response last changed. If not set, the default value is null.

  • ETag: A string value that specifies a unique identifier that changes each time the content of the response changes. If not set, the default value is null.

• companyhome: A script node that represents Company Home.

• document: A script node that represents the current document.

• formdata: A host object that provides access to multipart/form-data requests that allow file upload from a web script. This object contains the following fields:

  • hasField: A Boolean value that specifies the existence of a named form field in the multipart request.

  • fields: An array of formfield values where each element represents a field within the multipart request.

• formfield: A host object that provides access to a form field within a multipart/form-data request. This object contains the following fields:

  • name: The name of the field.

  • isFile: A Boolean value that specifies whether this field represents a file.

  • value: A string value that represents the field value.

  • content: Script content that represents the content of the field.

  • mimetype: The MIME type of the content (null if isFile is false).

  • filename: The file name of the source file used to provide the content (or null if isFile is false or a filename was not specified).

• person: A script node that represents the current user Person object.

• server: An array of metadata properties that describe the server hosting Content Services (deprecated). This object contains the following fields:

  • versionMajor: A string value that specifies the major version number.

  • versionMinor: A string value that specifies the minor version number.

  • versionRevision: A string value that specifies the server revision number.

  • versionLabel: A string value that specifies the server version label.

  • versionBuild: A string value that specfies the server build number.

  • version: A string value that specifies the server version.

  • edition: A string value that specifies the server edition.

  • schema: A string value that specifies the server schema.

• space: A script node that represents the current space.

• status: An array of response status properties that enable control over the status and content of the web script response. This object contains the following fields:

  • code: The status code (primarily a HTTP status code but can be any number).

  • codeName: Represents the status code name.

  • codeDescription: Represents a description of the status code.

  • message: Represents a message that is associated with the status code.

  • redirect: A Boolean value that specifies whether to redirect the status reponse template.

  • exception: Represents an exeption that caused this status.

• userhome: A script node that represents the current users home space.

• url: A host object that provides access to the URL (or parts of the URL) that invoked the web script. This object contains the following fields:

  • context: The context path (for example, /contentspace).

  • serviceContext: The service context path (for example, /contentspace/service).

  • service: A web script path (for example, /contentspace/service/sample/blog/search).

  • full: The complete URL used to invoke the web script (for example, /contentspace/service/sample/blog/search?q=company/home).

  • args: The arguments passed to the web script (for example, q =company/home).

  • match: The part of the web script URL that matched the web script URL template.

  • extension: The part of the web script URL that extends beyond the match path (if there is no extension, an empty string is returned).

• webscript: An array of metadata properties that describe the web script. This object contains the following fields:

  • Id: A string value that specifies the web script identifier value.

  • shortName: A string value that specifies the short name of the web script.

  • description: A string value that specifies the description of the web script.

  • defaultFormat: The default response format.

  • formatStyle: The accepted ways of specifying the format in the web script URL.

  • URIs: A string array of URL templates.

  • method: A HTTP method used in the request.

  • requiredAuthentication: The required level of authentication.

  • requiredTransaction: The required level of transaction.

  • storePath : The path of the persistent store where the web script is stored.

  • scriptPath: The path (within storePath) of the web script implementation files.

  • descPath : The path (within storePath) of the web script description document.