Jump to page content

Usablenet Assistive Administrator's Manual

Usablenet Inc.
101 Avenue of the Americas - Suite 1201, New York, NY 10013, USA
Ph: +1 (212) 965 5388
Fax: +1 (212) 965 5391
Email: tt.support@usablenet.com
www.usablenet.com

 

Table of Contents


 

1. Basics


Usablenet Assistive (or transcoder) is a web application that converts a web page into its text-only version on-the-fly by eliminating all page layout that is present in the original page and by hiding many accessibility defects.
The transcoder is useful for the website visitor, since it removes some accessibility issues and small defects like missing image ALTs or forms that are not properly linearized or flash objects. It also provides some navigation options that are not usually available on browsers and that enhance the user experience of disabled users or users of mobile technology.
Usablenet Assistive can be used also by the web developer to determine if the reading order of the information presented in the page makes sense when read in the order that would be followed by a screen reader or speech browser.

As a webmaster the main advantage of deploying Usablenet Assistive is that a "Text mode" link can be added to each page of the website and instantly web visitors can access a text-mode rendering of the content of the pages with no manual work (other than adding the link).

See the User's Manual for additional information on what Usablenet Assistive does.

Subsections:

 

1.1. Deploying Usablenet Assistive


While Usablenet Assistive is very efficient, to transcode a page it has to:

  1. receive a request from the visitor's browser,
  2. issue a request to the webserver hosting the site,
  3. wait for the webserver and the network to yield the data,
  4. transform the page, and finally
  5. send the transformed page to the user's browser.

Figure 1: Interaction between browser, transcoder and web server

Diagram showing the interaction among browser, transcoder and web server

This proxy-like behavior of Usablenet Assistive has repercussions on several aspects: performance, security and deployment of Usablenet Assistive. Let's start from the last of these aspects.

You can deploy Usablenet Assistive in two ways: either Usablenet Assistive can be installed on one of your machines within the local network where your web server runs (we call this solution local server) or it runs on machines managed by Usablenet (we call this solution managed service).

Both solutions have their own advantages and disadvantages. The one based on local server has the advantage that Usablenet Assistive runs within the same network and physical infrastructure where your web servers are located. And therefore it benefits also from a higher performance, since connections between Usablenet Assistive and web servers are very fast.
The solution based on a managed service has the advantage that you don't need to spend time installing and upgrading Usablenet Assistive.

Go through this document to learn how the two solutions affect performance and security.

 

1.2. The Administrator's role


For the managed service deployment mode of Usablenet Assistive the task of the administrator (who usually is the webmaster) is very simple. S/he has to decide which websites can be processed by Usablenet Assistive and to install proper "Text mode" links on pages that the Usablenet Assistive has to process.

For the local server solution the task of the administrator comprises more activities. The administrator is expected to:

In both cases the administrator should handle communication between web visitors and Usablenet support staff when it is believed that Usablenet Assistive does not work as it is expected to. The administrator should also allow (and perhaps come along with) Usablenet engineers to inspect Usablenet Assistive, diagnose a problem and implement a solution. Possibly also in a remote way via a network connection over a ssh terminal session or a telnet connection.

Usablenet Assistive comes along with Web Admin, that offers a web-based interface for the most frequent administrative functions. Point your browser to http://TRANSCODER_SERVER:8080/tt/admin.jsp (where TRANSCODER_SERVER is the name of the server that hosts Usablenet Assistive) to get access to such a functionality, if enabled. And read about it in section Web interface for the administrator.

 

2. How to deploy Usablenet Assistive managed by Usablenet


When purchasing this solution you need to decide how many web servers the Usablenet Assistive has to process (real and virtual servers are alike). If you need to apply Usablenet Assistive on pages hosted by www.mycompany.com then coverage of a single server suffices; if you need to use it for pages hosted by www.mycompany.com, www.products.mycompany.com and people.mycompany.com then three servers have to be covered.

Consider that while processing a page Usablenet Assistive rewrites the URLs contained in the page so that the actual browser request gets filtered by Usablenet Assistive. However this URL remapping occurs only for URLs that are based on servers on which Usablenet Assistive is allowed to work. I.e. whose pages Usablenet Assistive may transcode. If a URL is not remapped then the visitor browser will display the normal original page.

For this reason when purchasing this solution you need to tell to the Usablenet representative how many servers have to be covered by Usablenet Assistive and their names as well. Should you need to change the name of some server please contact Usablenet's staff (tt.support@usablenet.com).

The second step is to install text mode links within your pages. See the How to set up text-mode links section.

 

3. How to set up text-mode links


Subsections:

 

3.1. Adding text-mode links to pages


This is an easy step. To allow Usablenet Assistive to generate on the fly these text-only pages you only need to create a new link on your pages and have that link point to the Usablenet Assistive. It will work on static pages, dynamic pages (e.g. asp, jsp), on pages produced by a Content Management System or pages pulled out of a database; on pages with any sort of web content and even forms.
Visitors of your website will be able to follow such text-mode links, and then be able to navigate through your website (within the web server names limits described in sections How to deploy Usablenet Assistive and Installing the serial number) in text-mode. They will be able at any time to switch back to your real web pages (i.e. without using Usablenet Assistive at all).

The text-mode link should look like in this example: 

<a href="http://assistive.usablenet.com/tt/http://www.mycompany.com/some/page.html"
   title="text-only page produced automatically by Usablenet Assistive">
  Text only
</a>

where http://www.mycompany.com/some/page.html is the URL of the page containing the text-mode link (i.e. the one that you are editing) and assistive.usablenet.com is the server name where Usablenet Assistive is running.

If you need to code a text-mode link for a page that should be handed to the browser via an HTTPS connection then you only need to change both occurrences of HTTP with HTTPS, i.e. 

<a href="https://assistive.usablenet.com/tt/https://www.mycompany.com/some/page.html" 
   title="text-only page produced automatically by Usablenet Assistive">
  Text only
</a>

If you decide to put the "text-mode" link in more than one page, and having to specify each time the actual URL of the page to be transcoded is a hassle (like when you use templates for the page heading that are shared among a large number of pages) then you can adopt the following mechanism.

The "text-mode" link should look like this example: 

<a href="http://assistive.usablenet.com/tt/referrer" 
   title="text-only page produced automatically by Usablenet Assistive">
  Text only
</a>

Usablenet Assistive will use the Referer request-header field (as defined by the HTTP protocol) to get the URL to process.

The two mechanisms are quite equivalent; the difference is that "text-mode" links based on the latter (the one using the "referer" HTTP header) will not work if the user's browser does not process such a heading. This can happen if the user has disabled such a heading or for browsers that do not support it (for example some browsers on PDAs do not process it).
Notice that the HTTP protocol field name is "referer" whereas the URL we require to use ends with "referrer" with a double "r".

To speed-up even more the interaction with the user's browser, Usablenet Assistive does an automatic HTTP content compression of the data. This is an activity that is totally transparent to the user of the browser and the Usablenet Assistive administrator.

In addition to adding such a visible text only link (for the benefit of those that can see it when visually scanning the page), consider adding also a hidden text only link at the very beginning of the page. In this way web visitors using screen readers or small devices (PDAs, smart phones) not supporting images can get it early, before they have to sift it out from all the content of the page.

One simple way for achieving this is to add a hidden link based on a spacer image, as follows: 

<a href="http://assistive.usablenet.com/tt/http://www.mycompany.com/some/page.html">
  <img src="images/spacer.gif" style="border:none" width="0" height="0"
       alt="text-only page produced automatically by Usablenet Assistive"/>
</a>
 

3.2. Using bookmarklets


To further enhance the ability for your visitors to use the Usablenet Assistive that you deployed in your site, you can place in some introductory page a bookmarklet that can be added to their browsers. Whenever they visit a page and select/click such a bookmark, Usablenet Assistive is activated on the visited page (if the page is within the realm of pages that can be processed by Usablenet Assistive).

The following link can be bookmarked (i.e. put in your favorite links). Once it is there, and you browse any web page on which Usablenet Assistive can be applied to, if you click such a bookmark the browser will display the text-only page generated by Usablenet Assistive. Actually the bookmark works as a toggle button: click it once to view the text-only page, click it again and the browser will display the original page.

Text-only toggle

This link is implemented as follows: 

<a href="javascript:if
(window.location.href.indexOf('http://assistive.usablenet.com/tt/') == 0)
window.location = window.location.href.substring(35, window.location.href.length);
else window.location = 'http://assistive.usablenet.com/tt/' + window.location;">
  Text-only toggle
</a>

This bookmarklet works only on Javascript enabled browsers. And only if you have access to Usablenet Assistive. You might need to manually edit the code of the bookmarklet to change the server name that hosts Usablenet Assistive. Editing a bookmarklet is easy: simply save it as a link within an HTML page, edit its Javascript code and then bookmark the link again. What you need to do is to replace the occurrences of "assistive.usablenet.com" with the server name on which Usablenet Assistive is running within your organization. 35 is the number of characters included in "http://assistive.usablenet.com/tt".

Each bookmarklet (aka favelet) is a tiny program (a Javascript application) contained in a bookmark (the URL uses a "javascript:" protocol) which can be saved and used the same way you use normal bookmarks. Learn more about bookmarklets ...
This bookmarklet is easy to install, poses no security threats to your machine or browser, and is free.

 

4. How to install Usablenet Assistive locally


Subsections:

 

4.1. System requirements


The hardware used to run Usablenet Assistive should meet at least the following requirements:

Usablenet Assistive is based on the following underlying (open source) products:

These components are used in their original version and integrated within the Usablenet Assistive software architecture.
Components that are not standard are provided with the Usablenet Assistive package. When installing Usablenet Assistive package, the package management system will verify that all the required packages are installed.

 

4.2. Installing or upgrading the Usablenet Assistive software


If you are upgrading Usablenet Assistive from a previous version please read the Upgrading section in the Usablenet Assistive Release Notes page.

Usablenet Assistive is available as an RPM package. You need to log in as root and install the required Lift RPM packages with the following commands: 

rpm -ivh lift-common-1.0-1.i386.rpm
rpm -ivh lift-mozilla-1.7.12-1.i386.rpm
rpm -ivh lift-tomcat-5.5.20-1.i386.rpm

To install Usablenet Assistive you need to perform the following command: 

rpm -ivh lift-assistive-X.X-X.i386.rpm

At the end of installation process, the rpm command will restart of the Tomcat service with the following command:

service lift.tomcat restart

BEWARE: During the installation a new Linux user is automatically created, named "lift" whose default password is "lift". You should change its password (if you are not the Linux administrator, or don't know how to do it, ask him/her to do it for you; this is critical for security).

To make sure that Usablenet Assistive is running properly try to use it and then inspect the log files. You must complete the installation first, by following all the relevant steps specified in this section. Then, to make sure it runs properly, point your browser to a URL like http://TRANSCODER_SERVER:8080/tt (where TRANSCODER_SERVER is the server name of the machine where Usablenet Assistive has been installed) and see that the appropriate page can be seen. Try exploring the on-line documentation and finally type a URL to be transcoded in the appropriate field. Then look at the log files to see if there are any warning messages. See also section 7.1 on log files.

 

4.3. Installing the serial number


Usablenet Assistive cannot run without a valid, properly installed serial number.

The Usablenet Assistive serial number is delivered as a text file that must be copied in the directory /opt/lift/tomcat/webapps/tt/conf with the name serial-number.txt.

After you copied the file remember to restart the Tomcat service:

As root do: service lift.tomcat restart.

Make sure that the serial-number.txt file has a read permission for everyone. Do a chmod a+r serial-number.txt to allow everybody (that has access to the server) to read it.

 

4.4. Defining the text-mode realm


You need to tell Usablenet Assistive which are the web servers whose pages it can process. These hosts and pages define the "space" (or realm) where web visitor can navigate in text-mode.

Simply edit the file /opt/lift/tomcat/webapps/tt/conf/tt-config.xml and edit or add the section called accepted-hosts as in the following example: 

  <accepted-hosts>
    <organization>
      <name>My Company</name>
      <host>www.mycompany.com</host>
      <host>news.mycompany.com</host>
    </organization>
  </accepted-hosts>

Unless you purchased an "Unlimited" license, remember to check that the number of accepted hosts does not exceed the number stated in your license file. Should this happen Usablenet Assistive will refuse to process any page, regardless the server it is hosted on.

The "Unlimited" license allows to specify entire subdomains to be processed by Usablenet Assistive. Subdomains must be written starting with a dot, as the following example: 

  <accepted-hosts>
    <organization>
      <name>My Company</name>
      <host>.mycompany.com</host>
    </organization>
    <organization>
      <name>My Other Company</name>
      <host>.myothercompany.com</host>
    </organization>
  </accepted-hosts>

Remember also that only pages hosted on these hosts will be transcoded by Usablenet Assistive. If a page hosted by one of these hosts contains a link to a page hosted by a host that is not listed, Usablenet Assistive will not transcode the latter page.

 

4.5. Network configuration


By default Usablenet Assistive needs to be reachable on TCP port 8080. This means that if you use a firewall, that port has to accept incoming requests. In addition, to handle HTTPS connections, Usablenet Assistive has to be reachable on TCP port 8443. If you want Usablenet Assistive to be reachable on ports 80 and 443 too, please see the Running on default HTTP and HTTPS ports section.

Usablenet Assistive also needs to reach web servers. By default, it issues (outgoing) requests on TCP ports 80 or 443 (for HTTP and HTTPS requests, respectively).

 

4.6. Running on default http and https ports


If you want Usablenet Assistive to be reachable on ports 80 and 443, you must be sure that no other web server is running on the same ports. Then you can configure configure Tomcat to run on ports 80 and 443. The only necessary modification is to change the port parameter of Connector element in the file server.xml located in /opt/lift/tomcat/conf.

There are two lines starting with this code fragment <Connector port="8080" and <Connector port="8443".

Substitute port="8080" with port="80" and port="8443" with port="443".

Restart tomcat (as root) with the following command: 

service lift.tomcat restart
 

4.7. Installing new root certificates


As described in User's Manual: Security aspects at times Usablenet Assistive needs to manage locally-installed certificates in order to establish secure connections.

One possible problem that a Usablenet Assistive user may encounter is that the web server it connects to has a Root Certificate that is unknown to Usablenet Assistive. In such a case Usablenet Assistive produces an HTTPS error page. (A root certificate is a certificate that is issued by some Certification Authority to certify itself; if your web server handles secure connections via public certificates, there is already an appropriate root certificate stored somewhere within the configuration files of the web server.)

Solution of this problem is easy: you need to install such a root certificate on Tomcat, the web application server Usablenet Assistive is based upon. Follow these easy steps:

  1. Obtain the root certificate file (either get it from your web server configuration files or download it from the Certification Authority that released it; for example from Verisign.com).
  2. Stop the Tomcat service: 
    service lift.tomcat stop
  3. Install it so that Tomcat can see it. From the root account issue the following shell command (in a single line): 
    <java_home>/bin/keytool -keystore <java_home>/jre/lib/security/cacerts
   -import -alias <new_alias> -file <root_cacert_file>
    where java_home is the directory where the Java system used by Tomcat is installed (usually something like /usr/java/jdk1.5.0_07); new_alias is the local name you are giving to the certificate (this name can be used to retrieve the certificate; it is not used at all by Tomcat); and root_cacert_file is the file name containing the root certificate itself.
  4. Start the Tomcat service: 
    service lift.tomcat start

If you need to see which root certificates are already visible to Tomcat (and hence to Usablenet Assistive) you can issue the following command: 

<java_home>/bin/keytool -keystore <java_home>/jre/lib/security/cacerts -list

Note: when handling root certificates you usually need to enter a password. The default password used by the Java system is "changeit", unless it has been changed by a security-conscious administrator.

 

4.8. Installing public certificates


The previous section describes how to install root certificates, i.e. certificates issued by certification authorities to state that they are an authority. This section explains how to install on Usablenet Assistive public certificates, i.e. certificates that you created and installed on your web server to support HTTPS connections. You can locate these certificates within some configuration file of your web server.

NOTE: if your web server does not support HTTPS connections then you don't need to worry about these certificates. Usablenet Assistive will not use them either.

Solution of this problem is also easy: you need to install such a public certificate on Tomcat, the web application server Usablenet Assistive is based upon. Follow these easy steps (see the tomcat how-to tutorial for additional details):

  1. Stop the Tomcat service: 
    service lift.tomcat stop
  2. Create a keystore file by adding a new private certificate issuing the following shell command (in a single line): 
    <java_home>/bin/keytool -genkey -alias tomcat -keyalg RSA 
   -keystore /opt/lift/tomcat/.keystore
    where java_home is the directory where the Java system used by Tomcat is installed (usually something like /usr/java/jdk1.5.0_07). This command will create a file .keystore in Tomcat directory.
    (You need to enter a password required by the keytool command: the default password is changeit)
  3. Install the public certificate so that Tomcat can see it. From the root account issue the following shell command (in a single line): 
    <java_home>/bin/keytool -keystore /opt/lift/tomcat/.keystore
   -import -alias <new_alias> -file <cert_file>
    where new_alias is the local name you are giving to the certificate (this name can be used to retrieve the certificate; it is not used at all by Tomcat); and cert_file is the file name containing the certificate itself.
  4. Start the Tomcat service: 
    service lift.tomcat start

If you need to see which certificates are already visible to Tomcat (and hence to Usablenet Assistive) you can issue the following command: 

<java_home>/bin/keytool -keystore /opt/lift/tomcat/.keystore -list

Note: when handling root certificates you usually need to enter a password. The default password used by the Java system is "changeit", unless it has been changed by a security-conscious administrator.

 

5. Performance aspects of Usablenet Assistive


Consider again the diagram shown at the beginning of this document.

Figure 2: Interaction between browser, transcoder and web server and between browser and web server

Diagram showing the interaction among browser, transcoder and web server

The response time for getting a text-only page (i.e. the time the web visitor has to wait to see some results), compared to the time to get the original page, is affected by steps 2, 3 and 4.
Depending on whether the transcoder is installed in the same local network as the webserver or in a different network, the performance will differ (the latter case is the worst as steps 2 and 3 require more time).

The deployment modality of Usablenet Assistive is just one of the factors affecting performance. Other factors are:

  1. speed of the connection between browser and web server (arrows 6 and 7)
  2. speed of the connection between browser and Usablenet Assistive (arrows 1 and 5)
  3. speed of the connection between Usablenet Assistive and web server (arrows 2 and 3)
  4. complexity of the original page (in terms of how much processing Usablenet Assistive has to perform in order to hide or change elements)
  5. size of the original page (and therefore amount of data that needs to be transferred in connections 3 and 7, from web server to Usablenet Assistive and to browser respectively)
  6. size of the transcoded page (and therefore amount of data that needs to be transferred in connection 5, from Usablenet Assistive to the browser).

A local server deployment of Usablenet Assistive increases the speed of connections between Usablenet Assistive and web server (arrows 2 and 3). And depending on the other factors, the response time to access a web page through Usablenet Assistive (arrows 1, 2, 3 and 5) may actually be significantly less than the response time to access the normal page (arrows 6 and 7), because of the difference in size and rendering complexity between these two pages.

 

6. Security aspects of Usablenet Assistive


See the discussion of public and private HTTPS certificates in User's Manual: Security aspects.

Usablenet Assistive supports multipart/form-data content type when submitting a form. This means that users can upload files using forms.
You can easily disable this feature by editing the file web.xml located in /opt/lift/tomcat/webapps/tt/WEB-INF.
Set the parameter enable-uploads to false to disable file uploads or set the parameter upload-max-size to limit the size of uploaded files. Current max size is set to 500 Kbytes.

 

7. Day to day management of Usablenet Assistive


Subsections:

 

7.1. Enabling log files


If you need to monitor Usablenet Assistive activity, its log files are an important resource. From them you can determine the amount of traffic that goes through your Usablenet Assistive, demographic data about your visitors, and potential problems with your installation of Usablenet Assistive.

You can easily configure Tomcat to log all the accesses to Usablenet Assistive and all its error messages. All you need is to add the following XML fragment to the file server.xml located in /opt/lift/tomcat/conf.

The fragment must be placed inside the <Host> tag that handles the transcoder service (Tomcat can handle one or more virtual servers: the Host tag allows you to define them). Usually you can put the fragment inside the "localhost" <Host> element, i.e. the default host handled by Tomcat. But in other cases you might want to define another hostname for the Usablenet Assistive service.
See Tomcat's Server Configuration Reference for more information about configuring server.xml, handling virtual hosts and customizing the log files.

This is the fragment for enabling logs that needs to be included within the Host tag: 

<Context path="/tt" docBase="tt" debug="0" 
         reloadable="false" crossContext="false">
    
  <Valve className="org.apache.catalina.valves.AccessLogValve"
         directory="logs" prefix="tt_access." suffix=".log"
         pattern="combined" resolveHosts="false"/>

  <Logger className="org.apache.catalina.logger.FileLogger"
          directory="logs"  prefix="tt." suffix=".log"
          timestamp="true"/>

</Context>
 

7.2. Managing log files


If logs are enabled (see previous section) all Usablenet Assistive activity is logged on files under the directory /opt/lift/tomcat/logs:

The log file startup.log is located in /opt/lift/tomcat/webapps/tt/WEB-INF/logs. It contains data about the initialization of Usablenet Assistive showing license data, administration data, the list of accepted hosts to transcode and the number of hosts that can be still added to this list.
Use this file to make sure that the appropriate parameters and values have been correctly read by Usablenet Assistive.
The startup.log file is generated the first time Usablenet Assistive processes a page request after Tomcat has been restarted. Therefore, if you need to check the content of the log file after a Tomcat restart, point your browser to the Usablenet Assistive Main Page (i.e. /tt/index.html). After the page has been delivered to your browser inspect the startup.log file.

Old log files are automatically compressed and the oldest ones are automatically removed.

For Managed Usablenet Assistive users: upon request Usablenet staff will be happy to send you, at the beginning of each month, the log records for the web servers that you registered. This is a service already included in the subscription fee. Just send an email to tt.support@usablenet.com.

 

7.3. Monitoring Usablenet Assistive


Usablenet Assistive is a reliable application, if properly configured and managed. It means that it will keep working for long periods of time without requiring any attention.

However we suggest that you periodically monitor its behavior. In particular you should watch its response time (how long has a web visitor using your Usablenet Assistive to wait before getting the transcoded page) and if, for some reason, it might not be working any more.

To watch response times you can try it by hand or you can adopt a more systematic approach (using tools like JMeter) to set-up automatic measuring of response times. If you discover that response time of Usablenet Assistive hits too high limits there are several options you can adopt to resolve the issue, ranging from fine-tuning Usablenet Assistive to adding additional hardware. Please get in touch with tt.support@usablenet.com and we will be glad to help you solve the problem.

The most probable reason for crashing is due to improper configuration of Usablenet Assistive: see next section.

 

7.4. Fine tuning Usablenet Assistive


Depending on how frequently Usablenet Assistive is being used, how many simultaneous users are there, the characteristics of the pages to be transcoded, and the performance of underlying machine where Usablenet Assistive is running, appropriate configuration might be needed to improve throughput, response time and reliability.

By large, the most frequent problem is due to insufficient memory being allocated to Tomcat, the web application server used by Usablenet Assistive.

Depending on how much RAM and swap space is available on your machine, configure appropriately the following parameters. We suggest that you allocate at least 256 MByte to Tomcat.

Edit the file /opt/lift/tomcat/conf/java_opts.conf and make sure that it contains the following line: 

-Xmx256m -Xms256m

that specifies to start the JVM with a memory footprint of 256 Mbytes. If your machine has 1 GByte of RAM, then consider allocating to Tomcat 512 MByte or more.

If you would like to implement more specific tuning, please send an email at tt.support@usablenet.com. We'll be glad to assist you.

 

8. Customizing Usablenet Assistive


Subsections:

 

8.1. Server names


Usablenet Assistive needs to know the name of the server it runs on (for example assistive.usablenet.com). This is needed when Usablenet Assistive rewrites the URLs that it finds on pages that it processes. By default it will rewrite these URLs without adding any server name nor port number (in which case the server name and port number specified in the HTTP/HTTPS request will be sent to Usablenet Assistive by the browser). But if you want to specify a server name and possibly a port number (other than the default ones: 8080 for HTTP and 8443 for HTTPS), then edit both the parameters called http-server and https-server. We suggest that you define both these parameters or none of them.

Edit the Usablenet Assistive configuration file /opt/lift/tomcat/webapps/tt/conf/tt-config.xml and edit the sections called http-server and https-server as follows: 

<http-server>YOUR_SERVER_NAME:YOUR_PORT</http-server>

and similarly for HTTPS-SERVER.

If you set a port number different than the default one, make sure that the system is configured so that tomcat is actually listening to the port that you defined.

 

8.2. Email addresses


Usablenet Assistive offers in many of its pages the email address of the Usablenet Assistive administrator, so that Usablenet Assistive users can easily get in contact if help or clarification is needed. For this reason Usablenet Assistive needs to "know" to the email address of the administrator.

Open with a text-editor the file /opt/lift/tomcat/webapps/tt/conf/tt-config.xml and edit the section called admin-email by setting the proper email address.

Usablenet Assistive, if it encounters some weird situation, sends a warning to the administrator via email. To do so it needs to "know" which SMTP server to use (to deliver email) and what kind of "From" address to use when composing the message.

Open the /opt/lift/tomcat/webapps/tt/conf/tt-config.xml file and edit the sections called mail-host (by default the SMTP server is localhost) and mail-sender.

 

8.3. Connection parameters


When Usablenet Assistive processes web pages, it need to download them from the web server being transcoded. Some parameters can be changed to obtain the best behavior.

The http-connect-timeout defines the wait time limit to the HTTP Connection, expressed in seconds.

The http-read-timeout defines the time limit to the read operation, in seconds.

The html-max-size defines the maximum size of downloaded pages, in bytes.

Open the /opt/lift/tomcat/webapps/tt/conf/tt-config.xml file and edit as follow: 

  <http-connect-timeout>30</http-connect-timeout>
  <http-read-timeout>30</http-read-timeout>
  <html-max-size>2048000</html-max-size>
 

8.4. Alert user when leaving text mode


Among other things you can customize Usablenet Assistive so that when a web visitor navigating in text-mode hits the border of the text-mode realm (i.e. follows a link that goes outside the text-mode realm; - see section Defining the text-mode realm) the most appropriate behavior is performed.

You can configure Usablenet Assistive to behave in two different ways: either the web visitor, after clicking such an outgoing link, reaches the resulting page in graphic-mode (i.e. with no Usablenet Assistive processing whatsoever) or the user reaches that page transcoded through the demo Usablenet Assistive service managed by Usablenet.

In the former case, switching from a text-mode page to a graphic page is sudden, and the web visitor might not be aware that s/he has hit a border. This might lead to some confusion on his/her side.

In the latter case, Usablenet Assistive will display an alert page informing the user that the border has been hit and that there are two options: either continue in text-mode by using the demo service, or switch to graphic mode.
The web visitor has also the option to set, in an appropriate Usablenet Assistive preference, whether to hide or show these alert pages. So we suggest that by default you enable them.

If you want to alert the user, you need to edit the file /opt/lift/tomcat/webapps/tt/conf/tt-config.xml and edit the section called speedbumps as this example: 

<speedbumps>yes</speedbumps>

Use "no" if you don't the alert page.

 

8.5. Bad User Agents


You can block certain User Agents to process pages via Usablenet Assistive. If you want to block one or more User Agents add the User Agent string or a substring of it to the bad-user-agents section of the file /opt/lift/tomcat/webapps/tt/conf/tt-config.xml, as this example: 

  <bad-user-agents>
     <user-agent>DigExt; DTS Agent</user-agent>
     <user-agent>Fetch API</user-agent>
     <user-agent>Missigua</user-agent>
     <user-agent>Yeti</user-agent>
  </bad-user-agents>
 

8.6. Admin username and password


To be able to use the Web Admin extension of Usablenet Assistive you need to set up a username and password to use as credentials when logging in as administrator.

To manually change these credentials (rather than changing them through the Web Admin interface) open the file /opt/lift/tomcat/webapps/tt/conf/tt-config.xml and edit the sections admin-username and admin-password. Any sequence of printing characters is valid. Avoid using the "&" symbol.

 

8.7. Annotations


Usablenet Assistive can be customized, on a website basis, so that it can produce pages that are even more useful than those that are produced by the default behavior of Usablenet Assistive.

The kinds of customizations that can be implemented so far (but the list is being extended by Usablenet's engineers each day) concern addition or removal of elements included in pages, or the way in which elements can be rendered. The following list gives you an idea of a sample of what can be achieved:

Such a customization can overcome some of the limits of Usablenet Assistive, namely its inability to handle Javascript code that is used within a page, especially code for validating and submitting form values. (This problem is not due to technological limits of Usablenet Assistive, but rather it reflects a fundamental limit for any conceivable computerized processing of Javascript code.)

Customization of Usablenet Assistive is based on annotations, XML files that contain references to existing web pages and that supply additional information that is used by Usablenet Assistive when transcoding the page. Via annotations you, as a webmaster, can easily add more power to the transcoder and specify how features of your website (for example forms) should be transcoded into true accessible pages. The power of annotations is that you don't need to change anything in the original web pages. Usablenet Assistive will merge the original page and the annotations that refer to it and produce the resulting text-only accessible page.

If you'd like to customize the behavior of Usablenet Assistive please get in contact with tt.support@usablenet.com. Depending on the kind of customization you need, you might be required to produce some prototype example of web pages demonstrating it.

 

8.8. HTML fragments removal


One common requirement is to have Usablenet Assistive drop some part of the HTML page (for example unwanted text-only links, or poor ALTs). You can achieve this also without having to write a specific annotation, but by using a special (but valid) markup on your HTML code.

There is an easy way to identify the HTML fragments that Usablenet Assistive should remove while processing a web page.
You simply have to embed those fragments inside a DIV element with the attribute class set to un_jtt_hide. The following is an example: 

<p>Introduction ...</p>
<div class="un_jtt_hide">
  <p>Offending code</p>
</div>
<p>Conclusion ...</p>

Will be transcoded into:

<p>Introduction ...</p>
<p>Conclusion ...</p>

If the HTML fragment contains only inline elements instead of block-level elements, you can use the SPAN element to mark the fragment to remove: 

<a href="index.html">Home page</a>
<span class="un_jtt_hide"><a href="javascript:...">Javascript based link</a></span>
<a href="products.html">Products</a>

In general Usablenet Assistive will remove all the elements in your page that have class="un_jtt_hide".

 

9. Web-based interface for the administrator


The URL http://TRANSCODER_SERVER:8080/tt/admin.jsp (where TRANSCODER_SERVER is the name of the server that hosts Usablenet Assistive) supports a web-based interface to the most frequently used administrative functions of Usablenet Assistive. We suggest you use this functionality if you feel insecure about editing configuration files for Usablenet Assistive.

Subsections:

 

9.1. Enabling Web Admin


On new Usablenet Assistive installations the Web Admin interface is disabled. To elable Web Admin, you must edit the file /opt/lift/tomcat/webapps/tt/conf/tt-config.xml and fill the admin-username and admin-password sections.

IMPORTANT:

  1. Choose a secure password (i.e. a password with more than 8 characters, some digits and punctuation marks).
  2. Remember to change frequently the password.
  3. Monitor who attempts to connect to the Web Admin URL, and when the connection is attempted (You may do this by reviewing the webserver logs produced by Usablenet Assistive).
 

9.2. Logging in and out


Use the login form available at http://TRANSCODER_SERVER:8080/tt/admin.jsp (where TRANSCODER_SERVER is the name of the server that hosts Usablenet Assistive), the account and the password that you defined in the file /opt/lift/tomcat/webapps/tt/conf/tt-config.xml.

Although Usablenet Assistive will automatically log you out if it detects no activity within a period of time, we suggest that you activate the "Logout" button every time you are finished with the administrative functions.

 

9.3. Hosts page


The Hosts page allows you to add, change, remove or edit the names of the hosts allowed to be processed by Usablenet Assistive. More hosts can be grouped into Organizations. The page is split into two sections.

The Add Hosts section allows you add new hosts to an existing organization or to a new organization. Adding new hosts requires the following steps.

  1. Select an organization from Organization list or type a new organization in the New organization field.
  2. Type the host names in the New Hosts text area. The "Unlimited" license allows to specify entire subdomains to be processed by Usablenet Assistive. Subdomains must be written starting with a dot (example: ".nasa.gov", ".w3c.org").
  3. Press the Add button. If you press the Test & Add Usablenet Assistive will issue an HTTP GET request to every host to make sure that the name has been typed correctly.

The "Unlimited" license allows further options when defining the the list of hosts:

  1. You can specify entire subdomains to be processed by Usablenet Assistive. Subdomains must be written starting with a dot (example: ".nasa.gov", ".w3c.org").
  2. You can specify hosts not to be processed, even if they are part of a subdomain. These hosts must be written starting exclamation mark (example: "!specifichost.w3c.org").

The Edit Hosts section allows you to delete existing hosts, or to move them from an organization to another. The list of hosts can be narrowed by selecting an organization from the Organization list and typing a string on the Filter field, then pressing the Apply button.

If you want to delete one or more hosts, select them from the Hosts list and press the Delete button.

If you want to move one or more hosts, select them from the Hosts list, select the new organization from the Move selected hosts to list and press the Move button.

The functionality provided by the Hosts window implements the changes described in section Defining the text-mode realm.

 

9.4. Options page


The Options page allows you to define some options for the Usablenet Assistive. In particular:

 

9.5. Connections page


The Connections page allows you to modify the behavior of Usablenet Assistive when Usablenet Assistive connects to hosts to be processed. In particular:

 

9.6. Annotations page


The Annotations page allows you to see if and when updated annotations are available from the Usablenet Annotations Update Center.

 

9.7. Account page


The Account page allows you to change the username and password used by the administrator of Usablenet Assistive when using the web-based user interface (i.e. Web Admin).

See section Admin username and password.

 

10. Quick reference guide


As a quick reference these are the configuration and log files used or written by Usablenet Assistive and by Tomcat. Frequently used commands are also listed.