Create a new connector

Recommended reading before proceeding: https://github.com/LockerProject/Locker/wiki/The-Anatomy-of-a-Connector

We've worked to abstracting out as much of the connector logic as possible so that the only code that's necessary to write is specific to the connector that's being built. All of this base connector logic is provided via the Common/node/connector set of files. Those will be described first, and then this document will walk through the process of utilizing those to create a new connector.

Common Files

• api.js - Common set of data access endpoints.
• client.js - This launches the connector, as well as establishing a connection to mongo, instantiating an express-based web server, and loading in the remainder of the files required for a connector to run.
• dataStore.js - This library handles all the data storage for a connector. Currently, it's setup to write data to mongo and to dump data in a JSON-like format to disk.
• oauth2.js - This will handle oauth2 connections. Right now, any other type of authentication will need to be custom written.

Custom Files (using foursquare as the example)

• foursquare.connector - The manifest file for a service. Must use the file extension of connector, as that will be what differentiates this service from applications and from collections.

• init.js - This is mostly a configuration file. Options currently supported are:

  • 'enableCookies' : boolean (default false) - Setting this to true will cause the client to add in all the session logic from express.

  • 'id' : string (default 'id') - This is the ID key used for mongo. Usually this will be id, but sometimes (for example, twitter uses id_str instead since id is a very large integer that doesn't play nicely with javascript) the provider will use a different string as the id.

  • 'oauth2' : object - This object contains a set of options used for defining the way oauth2 is integrated into this connector. The defaults for the oauth2 object are as follows:

      options = {provider :            'Some oauth2 consumer',       // This is the name of the provider
                 endPoint :            'http://consumer.com/oauth/', // This is the base endpoint at the provider
                 linkToCreate :        'http://change.me/',          // This is the URL where someone would add an application
                 appIDName :           'App ID',                     // String shown to the user when asking for app ID
                 appSecretName :       'App Secret',                 // String shown to the user when asking for app secret
                 authEndpoint :        'authorize',                  // End point used for authorization at the provider
                 promptForUsername :   false,                        // Whether or not the user should be prompted for their username.
                 accessTokenResponse : 'text',                       // Either text or JSON.  If the token is passed in the body of the response, leave this as the default.
                 grantType :           '',                           // If a grant type needs to be specified to the provider, it should be defined here.
                 extraParams :         ''};                          // Any extra params that need to be included when establishing a connection.
    

• sync-api.js - This file will contain all of the endpoints used to synchronize data from the provider. It must contain a function called 'authComplete' that accepts 2 parameters, the first being the authentication object, and the second being the mongo object. This function should establish all the sync API endpoints, and should handle emitting events from the sync library to the locker itself. This file should contain very little logic, it should simply establish endpoints that are used to call functions in the sync.js file that handle all the work of querying the provider.

• sync.js - This is where the majority of custom code will reside. All the logic for pulling down data from the provider will reside in this file. All that data is subsequently loaded into the dataStore via the functions provided by the dataStore.js file. This file should export an eventEmitter for all of the supported service types to pass along events up the chain on create, update, and delete of objects.

Testing

Testing should be done via the fakeweb library to provide fixtures to the sync library. connector-local-foursquare-test.js is a fully featured example test. This covers the syncing functions, the events that are generated, as well as ensuring that the data is properly accessible via the common APIs.