Managing instances of collaboration

In this post, we’ll explain how to manage collaboration instances (we call the workspaces) on the XTWIP infrastructure. The workspace is an XML description of the data in your application, which several instances and several users can access, modify and interact with at the same time.

Think of the workspace as some sort of real time interactive, collaborative document.

workspace = real time XML document

While running a collaborative instance of your application, all changes are tracked, sent to all online participants and saved on the XTWIP. However, in this post we’re going to show you how to create, delete and access a workspace.

Creating a workspace

As a third party application developer, all you need to do is post a request to our front end server, authenticating yourself by sending the devKey provided to you. The server will respond with the workspaceID assigned to that workspace. You will need to store this ID, since you will later need it to refer the workspace. For more information on how to post a create workspace request, go through the XTWIP JSON-RPC API Reference [pdf].

Here’s what happens when you make the request

1. The user  hits a “New” button and the server-side for your application receives a request.
2. Your server then forwards the request to the XTWIP server, providing the devKey as an authentication mechanism. Optionally, it can also provide a name for the workspace or an initial content of the workspace XML (by default, the name is set to “Workspace” and the XML content is set to be empty).
3. The XTWIP front end performs a number of tasks before  stepping further:
   • • Checks the availability of your devKey
     • Checks if you have the right to create additional workspaces (if the creation limits per developer has not been exceeded)
     • Are you a paying customer ? Should any additional quality of service conditions be met for this request ?
     • It balances the request on the least occupied backend server, depending on your developer subscription type.
     • Finally, it forwards the request to the backend server that best fits several criteria (load, quality of service).
4. The backend server actually creates the workspace and it confirms the operations as successful. In case the operation fails, the request will be sent again to another available backend server.
5. The front end server marks the operation as successful, stores the workspace ID in the database together with the server onto which it is hosted. It returns the workspace ID to the developer server.
6. The developer server should also store the workspace ID, for any further reference (access request, deletion etc). It also notifies the end-user of the successful operation.

As a general fact, the business logic inside the XTWIP infrastructure is transparent to you. In order to manage collaboration instances, you only need to post the JSON-RPC requests and interpret the results.

Accesing a workspace

After you’ve created the workspace, your main concern will be how to access it: how to make your application aware of the collaboration instance and make sure all changes are delivered on that instance.

The XTWIP SDK for Flash/Flex automatically looks for the authentication information it needs to connect to the workspace in the flashvars of the embed code of your application. In order to get that authentication information however, you need to follow the steps described below:

1. The user decides to open an existing workspace, so the browser sends a request to the developer server.
2. Your developer server makes any additional verification (“does this user have rights to the workspace requested?” sort of thing). If everything checks out, the request for access is forwarded to the XTWIP front-end, together with the devKey associated to the application. Optionally, the email and the name of the user may be provided, so each user can have a unique identity in the collaboration environment.
3. The XTWIP front-end authenticates that the developer identified by devKey indeed has the right to access the workspace. It also finds the back-end server that currently stores the workspace. After that, a request for a temporary token is sent to the back-end server.
4. The back-end server randomly generates a temporary username & temporary password and then sends them to the front-end.
5. The front-end forwards them to the developer server, together with the IP and the port of the back-end server that is hosting the collaboration session.
6. The developer server pastes the temporary username and temporary password into the embed code for the collaborative application.
7. The application runs, the XTWIP Flash/Flex SDK loads the authentication data from the embed code (flashvars) and it connects to the back-end server, providing the credentials for authentication. The application instance has now joined collaboration on the workspace and may send/receive data, changes, chat messages, presence, ownership and so on.

This combination of devKey and temporary credentials bares several guarantees of security and flexibility:

• Each developer can only access those workspaces he/she created.
• Developers can define their own access control policies for their users (since this logic is to be implemented in the developer server, not in the XTWIP infrastructure)
• Users cannot access workspaces without a confirmation of access rights from the application developer.
• Users do not have access to devKey and do not have access to directly creating, deleting or accessing workspaces (without going through the application developer)
• Temporary credentials expire minutes after the user has left the collaboration session. In order to reconnect, the user must obtain a new set of temporary credentials.

Deleting a workspace

The workflow for deleting a workspace is almost the same as for creating one, the only exception being you need to provide the ID of the workspace you wish to delete.

We hope this post provided an overview on how you, as a developer, can manage the collaboration instances hosted on the XTWIP infrastructure. For a more detailed understanding of creating, deleting, accessing and retrieving workspaces, go through the XTWIP JSON-RPC API Reference [pdf].