Testing the hosted version

Disclaimer: I’m currently hosting the application on the server I use to host this blog (basic PHP and Tomcat hosting plan). I don’t know much about the characteristics of my server, but I’m probably sharing it with a few dozens of other domains and the resources allocated to me are obviously limited in that shared environment. This is clearly not the ideal environment to host a potentially large scale real time application and I’m investigating other hosting solutions. In the meantime, if you experience difficulties running the app, you can install it locally using the instructions provided below (in “Local installation instructions”). The hosted version tries to connect using RTMP by default (available only as part of LCDS) and falls back to “long AMF polling” or regular AMF polling if the RTMP connection fails.

1. Access http://coenraets.org/apps/gmaprooms/gmaprooms.html on two different machines or in two browser windows on the same machine.
2. Make sure you logon with two different user names and the same room name.
3. Move the map in one browser and notice that the position of the map is synchronized in the other browser.
4. You can also search an address in one browser and the resulting map position will appear in the two browsers.
5. The zoom level and the map type are also synchronized between users.
6. Click the “Whiteboard” button in one browser, pick a color to draw on the map (upper left corner), and start drawing.

Note: you can right-click the application and select View Source or click here to see the source code of the application.

Local installation instructions:

1. Install BlazeDS. You can download the BlazeDS turnkey server (a version of Tomcat with BlazeDS preinstalled) here.
2. Open {blazeds-install-dir}/tomcat/webapps/samples/WEB-INF/flex/services-config.xml and add an AMF long polling channel defined as follows:

   <channel-definition id="my-longpolling-amf" class="mx.messaging.channels.AMFChannel">
   	<endpoint url="http://{server.name}:{server.port}/{context.root}/messagebroker/amflongpolling" class="flex.messaging.endpoints.AMFEndpoint"/>
   	<properties>
   		<polling-enabled>true</polling-enabled>
   		<polling-interval-seconds>5</polling-interval-seconds>
   		<wait-interval-millis>60000</wait-interval-millis>
   		<client-wait-interval-millis>1</client-wait-interval-millis>
   		<max-waiting-poll-requests>200</max-waiting-poll-requests>
   	</properties>
   </channel-definition>

3. Open WEB-INF/messaging-config.xml and add the following destination:

   <destination id="gmaprooms">
   	<properties>
   		<server>
   			<allow-subtopics>true</allow-subtopics>
   			<subtopic-separator>.</subtopic-separator>
   		</server>
   	</properties>
   	<channels>
   		<channel ref="my-longpolling-amf"/>
   		<channel ref="my-polling-amf"/>
   	</channels>
   </destination>

4. (Re)start the BlazeDS turnkey server.
5. Download the source code of the Google Maps Application here.
6. Create a Flex Builder project for the Flex application (gmaprooms). Make sure you configure your Flex Builder project to work with BlazeDS. To read instructions on how to set up a Flex Builder project that works with BlazeDS, make sure your BlazeDS turnkey server is started, and click here.
7. Download the Google Maps ActionScript 3 API here, and add the swc file in the libs folder of your project.
8. Get a Google Maps API key and assign it to map.key in the initMap() function in MapArea.mxml.
9. Compile the application.
10. Open the Flex application in two browser windows (to simulate two users in different locations) and test the application as described above (in “Testing the hosted version”).

LCDS 2.6 allows you to build AIR applications with automatic offline data synchronization. This feature leverages the SQLite relational database system embedded in the AIR runtime, but the advantage is that the data synchronization process is entirely automatic: you don’t have to write SQL statements or synchronization logic to keep your local database in sync with your central database.

I have been getting a number of questions related to this feature, so I decided to build a sample application that demonstrates how it works.

In this application the synchronization process is implicit. When you are online, the cache (a SQLite database) is automatically updated along with the server database to make sure the user can go offline with the latest data without explicitly triggering a synchronization process. When you are offline, the changes are saved in the local cache. If the network becomes available while working in the application, the application will detect the network status change and automatically synchronize data (send your offline changes to the server, and get changes made by other users while you were offline).

Installation Instructions

1. If you haven’t already done so, install LCDS 2.6.
2. Unzip insync.zip
3. Copy the content of the sampledb folder in the sampledb folder of your existing LCDS directory
4. Copy the content of the tomcat folder in the tomcat folder of your existing LCDS directory
5. Add the following destination to data-management-config.xml

   <destination id="insync">
       <adapter ref="java-dao" />
       <properties>
           <source>lcds.samples.contact.ContactAssembler</source>
           <scope>application</scope>
           <metadata>
               <identity property="contactId" undefined-value="0"/>
           </metadata>
       </properties>
   </destination>

6. Restart the sample database: run sampledb.bat (Windows) or sampledb.sh (Unix) in the sampledb directory
7. Restart your application server

Quick Tour

1. Install and run the AIR application. Notice the green light in the status bar indicating that the application is in online mode.
   Please upgrade your Flash Player This is the content that would be shown if the user does not have Flash Player 9.0.115 or higher installed.

2. Double click a contact to view the contact details.
3. Modify the data in a few fields and click Save. Your server console indicates that the contact has been updated.
4. Click the + button in the application title bar. Enter a first name, last name, etc and click Save. Your server console indicates that the contact has been updated.
5. Shut down the server
6. Notice that the green light turns grey to indicate that the application is now working in offline mode.
7. Repeat steps 2 to 4 above: changes are saved locally. Notice that the offline status (not modified, created, or updated is displayed in the contact form (bottom left corner)
8. Restart the server.
9. The green light appears in that status bar as soon as the server is up and running. Notice that LCDS automatically detects the offline changes and sends them to the server.

Installation instructions

1. Install BlazeDS or LCDS.
2. Download the client-side of the application. The end-user application is mortgageapp.mxml, and the support representative application is callcenter.mxml.
3. Download and deploy the server-side of the application.
4. Add the following destination in WEB-INF/flex/remoting-config.xml.

   <destination id="ticket-service">
       <properties>
           <source>flex.samples.livehelp.TicketService</source>
           <scope>application</scope>
       </properties>
       <channels>
           <channel ref="my-rtmp"/>
           <channel ref="my-amf"/>
       </channels>
   </destination>

   NOTE: If you are using BlazeDS, remove the line that defines the “my-rtmp” channel.

5. Add the following destination in WEB-INF/flex/messaging-config.xml.

   <destination id="callcenter">
       <properties>
           <server>
               <allow-subtopics>true</allow-subtopics>
               <subtopic-separator>.</subtopic-separator>
           </server>
       </properties>
       <channels>
           <channel ref="my-rtmp"/>
           <channel ref="my-longpolling-amf"/>
       </channels>
   </destination>

   NOTE: If you are using BlazeDS, remove the line that defines the “my-rtmp” channel in the above destination, and add the following channel definition in WEB-INF/flex/services-config.xml:

   <channel-definition id="my-longpolling-amf" class="mx.messaging.channels.AMFChannel">
   	<endpoint url="http://{server.name}:{server.port}/{context.root}/messagebroker/amflongpolling" class="flex.messaging.endpoints.AMFEndpoint"/>
   	<properties>
   		<polling-enabled>true</polling-enabled>
   		<polling-interval-seconds>3</polling-interval-seconds>
   		<wait-interval-millis>60000</wait-interval-millis>
   		<client-wait-interval-millis>1</client-wait-interval-millis>
   		<max-waiting-poll-requests>200</max-waiting-poll-requests>
   	</properties>
   </channel-definition>

6. Follow the instructions in my original post to experience the application.

I recently posted a number of examples (Yahoo Maps Collaboration and Collaborative Data Entry) showing how to use the BlazeDS / LCDS Message Service to build collaborative applications. In this post, I’m extending the Collaborative Forms application to provide an example of a more complete and real life “Live Help / Call Center” application.

The use case goes like this: a customer tries to complete a task (in this case: apply for a mortgage) on a web site, gets in trouble, and starts a “Live Help” session with a support representative. Among other things, the support representative can remotely drive the customer’s application, enter data collaboratively with the customer, chat with the customer using a text-based and/or a video-chat session, close the support ticket, etc.

To make it easier for you to experience the application, I’m hosting it on my server. You can test it using the instructions below.

Testing the application:

1. Open a browser and access http://coenraets.org/apps/livehelp/customer.html. Enter your email address and click Start.

   Note: Your email address is used as a unique identifier to allow you to test the application in your own sandbox: your experiments are isolated from the experiments of other users testing the application.

2. Open another browser window (on the same computer or on a different computer) and access http://coenraets.org/apps/livehelp/callcenter.html. Enter your email address and click “Start”. Make sure you use the same email address you used in the customer application.

3. In the customer application, enter some data in different tabs.

4. Click “Start session” to initiate a Live Help session with a support rep.

5. Notice that a new ticket appears in the call center application.

6. In the call center application select the new ticket, and click “Handle Ticket” (upper right corner). A message should appear in the chat window of the customer application. Notice that the data you typed in the customer application automatically appears in the support rep application.

7. Type a chat message in the support rep app: the message appears in the customer app.

8. The support rep can remotely drive the customer application: in the support rep application, change the selected Accordion tab, and notice that the customer application’s user interface is automatically synchronized. This works in both directions: you can change the Accordion tab in the customer app and the support rep’s user interface will be automatically synchronized as well.

9. The application supports collaborative data entry (collaborative form filling): Enter some data in the support rep application: notice that the data automatically appears in the customer application. This works in both directions as well.

10. On the Employment History tab, add a few companies (including start date, end date, and salary) and notice that the employment history list is automatically synchronized in the other browser.

11. If you have a webcam attached to your system, click the “Start webcam” button in one of the applications.

    Note: Live video streaming is powered by Flash Media Server. Since I don’t have access to a hosted instance of Flash Media Server, live video streaming is not enabled in this hosted version.

I will post the source code in the coming days.

After Yahoo Maps collaboration, here is another example of enabling collaboration in a Flex application using the publish/subscribe messaging infrastructure of BlazeDS.

This example demonstrates “collaborative forms” (or “collaborative data entry”). Users in different locations can fill in forms “together” in a real-time and in-context collaboration session: changes made by one user are automatically reflected in the other users application.

Testing the hosted version

1. Access http://coenraets.org/collabforms/collabforms.html on two different machines or in two browser windows on the same machine.
2. Click “Create Session” (bottom left) in one browser: a collaboration session is created with a unique collaboration session id.
3. Enter this collaboration session id in the other browser and click “Join Session”.
4. Change the selected Accordion tab in one browser, and notice that the Accordion in the other browser is automatically synchronized.
5. Enter data in one browser and notice that the information is automatically synchronized in the other browser.
6. On the Employment History tab, add a few companies (including start date, end date, and salary) and notice that the employment history list is automatically synchronized in the other browser.

You can right-click the application and select View Source or click here to see the source code of the application.

Notes:

1. The way a collaboration session is actually started may vary depending on the application. In this example, one user creates a collaboration session, and shares the collaboration session id (via email, IM, etc…) with people he/she wants to collaborate with. In other use cases, the collaboration session could start automatically. For example, in a call center scenario, a user might click a “Live Help” button which would result in the creation of a support ticket appearing in the Support Reps application. A support rep could then take ownership of the ticket and enter a collaboration session using, for example, the ticket id as the collaboration session id. I will post a call center version of this example in the coming days.
2. In this example, the synchronization is performed using pub/sub messaging. You could also use the Data Management Service available with LiveCycle Data Services to automatically keep data in sync between multiple clients.
3. The hosted version of the application first tries to connect to the server using RTMP (available only as part of LCDS), and falls back to “long AMF polling” or regular AMF polling if the RTMP connection fails.

Local installation instructions:

1. Install BlazeDS. You can download the BlazeDS turnkey server (a version of Tomcat with BlazeDS preinstalled) here.
2. If you don’t already have a channel called “my-longpolling-amf”, open {blazeds-install-dir}/tomcat/webapps/samples/WEB-INF/flex/services-config.xml and add an AMF long polling channel defined as follows:

   <channel-definition id="my-longpolling-amf" class="mx.messaging.channels.AMFChannel">
   	<endpoint url="http://{server.name}:{server.port}/{context.root}/messagebroker/amflongpolling" class="flex.messaging.endpoints.AMFEndpoint"/>
   	<properties>
   		<polling-enabled>true</polling-enabled>
   		<polling-interval-seconds>5</polling-interval-seconds>
   		<wait-interval-millis>60000</wait-interval-millis>
   		<client-wait-interval-millis>1</client-wait-interval-millis>
   		<max-waiting-poll-requests>200</max-waiting-poll-requests>
   	</properties>
   </channel-definition>

3. Open WEB-INF/messaging-config.xml and add the following destination:

   <destination id="mortgage">
   	<channels>
   		<channel ref="my-longpolling-amf"/>
   		<channel ref="my-polling-amf"/>
   	</channels>
   </destination>

4. (Re)start the BlazeDS turnkey server.
5. Download the source code of the Mortgage Application here.
6. Create a Flex Builder project for the Flex application (collabforms). Make sure you configure your Flex Builder project to work with BlazeDS. To read instructions on how to set up a Flex Builder project that works with BlazeDS, make sure your BlazeDS turnkey server is started, and click here.
7. Compile the application.
8. Open the Flex application in two browser windows (to simulate two users in different locations) and test the application as described above (in “Testing the hosted version”).

Two years ago, I wrote a simple Google Maps collaboration example. The Flex application listened to Google Maps events to synchronize maps between different users. It also added nice collaboration features such as videoconferencing and a collaborative whiteboard overlaid on top of the map. In addition to demonstrating the real-time messaging capabilities of Flex, this application also illustrated Flex/Ajax integration using External Interface.

Two recent events prompted me to revisit this sample:

1. Yahoo recently released an ActionScript 3 API for Yahoo Maps.
2. Adobe recently released the Remoting and Messaging features of LiveCycle Data Services as an Open Source project named BlazeDS.

So, I updated the sample to work with the Yahoo Maps ActionScript API and BlazeDS (or LCDS). No need to communicate between Ajax and Flex in this version since the rendering of the map is entirely done within the Flex application.

Testing the hosted version

Disclaimer: I’m currently hosting the application on the server I use to host this blog (basic PHP and Tomcat hosting plan). I don’t know much about the characteristics of my server, but I’m probably sharing it with a few dozens of other domains and the resources allocated to me are obviously limited in that shared environment. This is clearly not the ideal environment to host a potentially large scale real time application and I’m investigating other hosting solutions. In the meantime, if you experience difficulties running the app, you can install it locally using the instructions provided below (in “Local installation instructions”). The hosted version tries to connect using RTMP by default (available only as part of LCDS) and falls back to “long AMF polling” or regular AMF polling if the RTMP connection fails.

1. Access http://coenraets.org/maprooms/maprooms.html on two different machines or in two browser windows on the same machine.
2. Make sure you logon with two different user names and the same room name.
3. Move the map in one browser and notice that the position of the map is synchronized in the other browser.
4. You can also search an address in one browser and the resulting map position will appear in the two browsers.
5. The zoom level and the map type are also synchronized between users.
6. Click the Map Sharing button in one browser, pick a color to draw on the map (upper left corner), and start drawing.

Note: you can right-click the application and select View Source or click here to see the source code of the application.

Local installation instructions:

1. Install BlazeDS. You can download the BlazeDS turnkey server (a version of Tomcat with BlazeDS preinstalled) here.
2. Open {blazeds-install-dir}/tomcat/webapps/samples/WEB-INF/flex/services-config.xml and add an AMF long polling channel defined as follows:

   <channel-definition id="my-longpolling-amf" class="mx.messaging.channels.AMFChannel">
   	<endpoint url="http://{server.name}:{server.port}/{context.root}/messagebroker/amflongpolling" class="flex.messaging.endpoints.AMFEndpoint"/>
   	<properties>
   		<polling-enabled>true</polling-enabled>
   		<polling-interval-seconds>5</polling-interval-seconds>
   		<wait-interval-millis>60000</wait-interval-millis>
   		<client-wait-interval-millis>1</client-wait-interval-millis>
   		<max-waiting-poll-requests>200</max-waiting-poll-requests>
   	</properties>
   </channel-definition>

3. Open WEB-INF/messaging-config.xml and add the following destination:

   <destination id="flexmaps">
   	<properties>
   		<server>
   			<allow-subtopics>true</allow-subtopics>
   			<subtopic-separator>.</subtopic-separator>
   		</server>
   	</properties>
   	<channels>
   		<channel ref="my-longpolling-amf"/>
   		<channel ref="my-polling-amf"/>
   	</channels>
   </destination>

4. (Re)start the BlazeDS turnkey server.
5. Download the source code of the Yahoo Maps Application here.
6. Create a Flex Builder project for the Flex application (maprooms). Make sure you configure your Flex Builder project to work with BlazeDS. To read instructions on how to set up a Flex Builder project that works with BlazeDS, make sure your BlazeDS turnkey server is started, and click here.
7. Download the Yahoo Maps ActionScript 3 API here, and add YahooMap.swc in the libs folder of your project.
8. Get a Yahoo API key here and assign it to the appid variable in MapArea.mxml.
9. Compile the application.
10. Open the Flex application in two browser windows (to simulate two users in different locations) and test the application as described above (in “Testing the hosted version”).

Here is a new version of my AIR-based SQLite Admin application updated for AIR 1.0. You can use this application to examine the structure of a database, create a new database or open an existing one, execute any type of SQL statement, etc.

An interesting aspect of this version is that the application itself uses a database (sqladmincache.db) to keep track of the databases you opened and the statements you executed. This is useful if you want to quickly re-open a recently accessed database, or re-execute a recently executed statement.

The UI is still simple, but uses some new AIR and Flex 3 features such as the AdvancedDataGrid and Native Windows.

Click here to download the source code.

Salesbuilder is a Sales Force Automation application written in Flex and deployed on the AIR runtime. It demonstrates local persistence using the embedded SQLite database, data synchronization, native drag-and-drop, and other features such as direct chart manipulation.

Additional Resources:

• Click here to install the application.
• Click here to download the source code.
• Follow this script for a guide tour of the application.

This application will also be packaged as a sample in the next version of LiveCycle Data Services currently in private beta.

Here is a quick look at the destinations and associations used in the application:

<destination id="account">
    <adapter ref="java-dao" />
    <properties>
        <source>com.salesbuilder.assembler.AccountAssembler</source>
        <scope>application</scope>
        <metadata>
            <identity property="accountId" undefined-value="0"/>
            <many-to-one property="salesRep" destination="sales-rep" lazy="true"/>
            <many-to-one property="industry" destination="industry" lazy="true"/>
            <many-to-one property="category" destination="account-category" lazy="true"/>
            <many-to-one property="state" destination="state" lazy="true"/>
        </metadata>
    </properties>
</destination>

<destination id="contact">
    <adapter ref="java-dao" />
    <properties>
        <source>com.salesbuilder.assembler.ContactAssembler</source>
        <scope>application</scope>
        <metadata>
            <identity property="contactId" undefined-value="0"/>
            <many-to-one property="account" destination="account" lazy="true"/>
            <many-to-one property="manager" destination="contact" lazy="true"/>
            <many-to-one property="salesRep" destination="sales-rep" lazy="true"/>
        </metadata>
    </properties>
</destination>

<destination id="opportunity">
    <adapter ref="java-dao" />
    <properties>
        <source>com.salesbuilder.assembler.OpportunityAssembler</source>
        <scope>application</scope>
        <metadata>
            <identity property="opportunityId" undefined-value="0"/>
            <many-to-one property="account" destination="account" lazy="true"/>
            <many-to-one property="salesRep" destination="sales-rep" lazy="true"/>
        </metadata>
    </properties>
</destination>

<destination id="industry">
    <adapter ref="java-dao" />
    <properties>
        <source>com.salesbuilder.assembler.IndustryAssembler</source>
        <scope>application</scope>
        <metadata>
            <identity property="industryId" undefined-value="0"/>
        </metadata>
    </properties>
</destination>

<destination id="sales-rep">
    <adapter ref="java-dao" />
    <properties>
        <source>com.salesbuilder.assembler.SalesRepAssembler</source>
        <scope>application</scope>
        <metadata>
            <identity property="salesRepId" undefined-value="0"/>
        </metadata>
    </properties>
</destination>

<destination id="account-category">
    <adapter ref="java-dao" />
    <properties>
        <source>com.salesbuilder.assembler.AccountCategoryAssembler</source>
        <scope>application</scope>
        <metadata>
            <identity property="categoryId" undefined-value="0"/>
        </metadata>
    </properties>
</destination>

<destination id="state">
    <adapter ref="java-dao" />
    <properties>
        <source>com.salesbuilder.assembler.StateAssembler</source>
        <scope>application</scope>
        <metadata>
            <identity property="stateId"/>
        </metadata>
    </properties>
</destination>

Installation instructions:

Prerequisite: You need to have LiveCycle Data Services installed on your system before executing the steps below.

1. Download salesbuilderlcds.zip
2. Unzip salesbuilderlcds.zip in /salesbuilderlcds

3. Copy the content /salesbuilderlcds/webapp/WEB-INF/classes to the WEB-INF/classes directory of your web application
4. Add the destinations defined in /salesbuilderlcds/webapp/WEB-INF/flex/data-management-config.xml to the data-management-config.xml file of your web application
5. Start the salesbuilder database
1. Open a command prompt and go to /salesbuilderlcds/db
2. Run startdb.bat (Windows) or startdb.sh (Unix-based systems)
6. Start your application server
7. Double-click /salesbuilderlcds/salesbuilderlcds.air to install the air application
8. Run the application

Configuration Note:

By default, the application tries to connect to the localhost server using the RTMP protocol on port 2037. If your server configuration is different, edit config.xml in the salesbuilder installation directory (”Program Files\Salesbuilder LCDS” on Windows).

If you are not familiar with the Salesbuilder application, here is a quick walkthrough:

Sales Pipeline
The sales pipeline features many “direct manipulation” options:

1. Grab the background of the chart with your mouse and scroll it left and write to navigate along the time axis.
2. Grab a vertical grid line, and move it left and right to zoom-out/zoom-in.
3. To modify your pipeline directly, grab a bubble with your mouse and move it up and down or left and right to adjust the probability and the expected closing date respectively. The projected revenue is automatically updated in the chart title. When you release the mouse button, the opportunity is automatically updated (probability and close date) in the database.
4. You can also double click a bubble to open a details view for the opportunity.

Search and Summary Screens

1. Type a few letters in the search box (upper right corner): matching accounts, contacts, and opportunities appear.
2. Use the arrow keys to navigate in the search results popup.
3. Use the Enter key to open the selected item.
4. Alternatively, you can also open the summary screens (”Accounts”, “Contacts”, and “Opportunities” buttons in the menu bar), and open individual items from there.

Working with Data

1. Open the “Alpha Corp” account.
2. Make some changes to the Alpha Corp data (for example, change the phone number), and click “Save””.
3. In the Contacts view of the Alpha Corp tab, you can grab an org chart item with your mouse and move the org chart around.
4. To open the details view for a contact, either double-click an org chart item or click the Grid button (lower left corner) and double-click a contact in the datagrid.
5. Add a contact by clicking “Quick Contact”. Make sure you select a manager, click save and notice that the org chart is updated automatically.
6. Continue to add and modify accounts, contacts, and opportunities. The data is persisted using the Data Management Service.

Native drag-and-drop

1. Click the “Opportunities” menu button.
2. Drag the dashboard title on the desktop: the chart is saved as a JPG on the desktop. Note: it can take a few seconds before you actually see the drag icon.
3. Open a Word document, drag the dashboard title again, and, this time, drop it directly in the Word document.
4. Select some rows in the datagrid, and, without releasing the mouse button, drag the selected rows and drop them on the desktop. The rows are saved as an Excel document on the desktop.
5. Double-click the Excel document to open the spreadsheet.
6. Drag some rows from the Datagrid again, and, this time, drop them directly somewhere in the Excel spreadsheet.