Introduction to QBank Connectors

What is the QBank Connector?

To make integrations in other systems easy to create and maintain, we decided to develop a completely embeddable JavaScript module for QBank 3 that can be easily implemented while providing a lot of functionality. The connector is designed to provide users with a slimmed down, easily navigated QBank browser where media can be selected and inserted into the system, usually some sort of CMS. The system can report usage data back to QBank, so when a new version is uploaded in QBank, or the media receives other updates, the editor knows all external usages that may need to be updated.

Previously, each CMS plugin was built from scratch, which gave them a strong feel of being part of the system, working closely with each systems respective architecture. The problem however was that each plugin was a separate codebase, and every new system required more or less a complete rewrite. Creating plugins took a long time, and maintaining all the different plugins was a huge task. With the new connector, the local code required for each plugin is basically just initializing the connector window, opening it in an appropriate dialog or panel, and receiving the media that should be inserted into the content. The window itself is one codebase, maintained by us at QBank, that is the same for all implementations. Whenever we update the connector, every implementation receives the updates at the same time!

So the Connector is only for CMS?

While we have designed the connector with the CMS workflow in mind, there is nothing preventing you from using it in any scenario or product that involves searching for media and retrieving information when the user selects one. The connector does not only return the file when a media is selected, but in fact the complete media data object, with properties, meta data, comments, usages, etc. 

But how can one module fit well in so many different systems?

The connector GUI is very slimmed and unobtrusive, so graphically it shouldn't stand out too much in any environment. At writing moment, it is not possible to configure the visual style, but we are ready to add support for supplying an additional stylesheet to the connector, if the need should arise.

Functionality wise, the connector can be heavily configured, so you only have the menus and options relevant to your particular implementation. 

What is required to implement the connector?

First off, your system needs to support JavaScript content and retrieving remote resources, since we recommend you fetch the JS file from us instead of storing a local copy. A local copy may be nice for fallback purposes, but even then, the connector will still be doing a lot of outside communication, so if you can't retrieve the JS file in the first place, you probably won't get much response from the internal resource & API calls.

We use the OAuth2 protocol for authenticating and communicating with our REST API, which is of course how the connector communicates with it's QBank host (through JSONP). Preferably, your system authenticates server side and retrieves an access token. You can either talk directly with the API, or use one of our prepared API wrappers for your programming language (https://github.com/qbnk). To retrieve an access token through OAuth2, you will have to request a client ID from your QBank representative, along with a username and password for the QBank host.

Pass the access token, client ID and QBank host to the JavaScript responsible for initializing the connector interface, and you're ready to open a connector window! 

NOTE: It is possible to skip access token, and only pass client ID and QBank host. This will prompt a login interface once a connector window is opened. By skipping the access token, you don't need any backend code at all, and can get straight to coding the JavaScript implementation. This login procedure relies on modern techniques and will not work in some web browsers. Also, you may need to login again each time the connector is closed/opened, depending on how the session is handled.