Assembla Development

Assembla can integrate external applications as tools.  For example, Assembla wraps around Trac (The <repo> & Trac tools), subversion (the Source/SVN tool), and git (the Source/Git tool).  There are three major advantages to wrapping an application in to an Assembla tool.

• New team members in Assembla automatically get the correct permissions in the related tools.  You do not need to manage many separate accounts.
• The app can send events to the Assembla stream (for example, trac notifications and repository commits), where they will get distributed to the correct subscribers.
• Other types of integration.  For example, the Assembla code browser adds many features to the basic repository.

Each external tool is represented in the Assembla application by a normal tool object.  This gives the tool a place in the space, with a tab.  That tool object makes Web service calls to an external tool server.  Whenever the tool is added to a space, it calls a web service to create a matching instance of the tool (a project, repository, etc.) on the external tool server.

The diagram below shows the simplest type of communication between Assembla.com and an external tool server.

For full integration, we customize an external app in two ways:

First, we add a "Control server" that can create, copy, and delete instances of the tool for each space that uses it.  In our implementations his is usually a simple RPC server.

Second, we modify the user authentication on the external application, so that users can log in with their Assembla.com accounts, and get correct permissions.  In a loose integration, the external app collects the username and password, and submits it to the GetUser Web service to log in a user.  This is how our subversion server authenticates subversion clients.  In a "single sign on" integration, the external app runs on a *.assembla.com host and grabs a session_id that is assigned to the assembla.com domain when a user logs in.  Invisibly to the user, the app can call a GetSession web service to get user information and permissions.

The GetUser and GetSession web services pass a secret key for the space tool instance that the user wants to use.  They return a user object, plus the permissions for the desired space (none, view, edit, all)

Document returned userstruc here.

Looser Integration

It is possible to integrate external applications more loosely.  You can make an Assembla.com tool for managing communication with the external application, without implementing the automatic create/copy/delete or the user integration.  For example, the Twitter tool sends data to a Twitter account.  It does not create a Twitter account.  Instead, you have to configure it with authentication information for an existing Twitter account.