Create a new connector

Example Walkthroughs

Foursquare Example using OAuth 2 Username & Password

---

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

We've worked towards abstracting out as much of the connector logic as possible so that there is a bare minimum of repeated code. 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. There's the beginnings of an oauth1 provider baked into the Twitter connector that will need to be abstracted and made available to other connectors. The IMAP connector is an example of a connector that just uses username/password authentication. When storing username/passwords locally, please use the provided lcrypto functions to ensure we aren't storing plain text username and passwords on a person's machine. While this provides little to no security in the case of someone having access to the filesystem, it does at least ensure that a simple grep of a user's machine doesn't expose passwords.

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 collections.

• init.js - This is mostly a configuration file. These options are passed to the init function of the connector/client module which needs to be included from here. 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.
                 width :               980,                          // This defines the width of the popup window used for authenticating to the provider.
                 height :              750};                         // This defines the height of the popup window used for authenticating to the provider.
    

• 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.