A general-purpose Communibase client for node.js projects. It is primarily a Singleton connector doing REST-calls on the Communibase API using a queuing system. It returns A+ promises for Communibase responses. Behaviour is reflected by a PHP-version that can be found at Github.

Installation

npm install --save communibase-connector-js

Usage

Make sure environment variable exists with your API-key called COMMUNIBASE_KEY

const { Connector } = require('communibase-connector-js');

const cbc = new Connector(process.env.COMMUNIBASE_KEY);

cbc.search('Person', { firstName: 'Tim' }).then((peopleCalledTim) => {
  // eslint-disable-next-line no-console
  console.log(peopleCalledTim.length);
});

Advanced usage

If you need to connect to a specific version of the endpoint, you may want to set a environment variable COMMUNIBASE_API_URL e.g.

COMMUNIBASE_API_URL=https://api.communibase.nl/0.1/

Use via a tunnel requires also adding an extra Host header

COMMUNIBASE_API_URL=https://17.42.0.1:8888/0.1/ COMMUNIBASE_API_HOST=api.communibase.nl node script.js

API

The following methods exists, all returning a promise for a result.

"selectors" may be provided MongoDb style.

"params" is a key value store for e.g. fields, limit, page and/or sort . See API docs for more details.

The param includeMetadata will set a metadata-property on the promise, when available.

cbc.getById(entityType, id, params): Promise for Entity;

cbc.getByIds(entityType, id[], params): Promise for Entity[];

cbc.getAll(entityType, params): Promise for Entity[];

cbc.getId(entityType, selector): Promise for id[];

cbc.getIds(entityType, selector, params): Promise for id[];

cbc.search(entityType, selector, params): Promise for Entity[];

cbc.update(entityType, document): Promise for Entity;

cbc.destroy(entityType, id): Promise for null;

cbc.undelete(entityType, id): Promise for null;

Entity

An entity is an plain JavaScript object: a key/value store of data in Communibase, also called "document".

E.g.

{
	"firstName": "Tim",
	"addresses": [
		{
			"street": "Breestraat"
		}
	]
}

Error handling

The update-Promise may be rejected if an entity is not considered valid. The Error has one or more of the following properties:

{
	"message": <a simplified error-string>
	"code": <http response code of API>
	"errors": {
		[
			"field": "<string>",
			"message": "<string>"
		], ...
	}
}

File handling

upload a new file or update an existing one:

/**
 * @param {Stream|Buffer|String} resource a stream, buffer or a content-string
 * @param {String} name The binary name (i.e. a filename)
 * @param {String} destinationPath The "directory location"
 * @param {String} id The `File` id to replace the contents of (optional; if not set then creates a new File)
 */

cbc.updateBinary = function updateBinary(resource, name, destinationPath, id) {

create a readable stream:

cbc.createReadStream(fileId) : Stream;

Work with document history

First, find the _id of both the document and the version you are looking for. To find all available versions of a specific document, use

cbc.getHistory(entityType, id) : Promise for  VersionInformation[];

Alternatively, you can search the entire history of documents to look for specific properties. e.g.

//Lookup all versions of any person (even deleted documents) ever with first name Tim.

cbc.historySearch('Person', { firstName: 'Tim' }): Promise for VersionInformation[]

VersionInformation has the following structure

• _id - The _id of the version.
• refId - The _id of the original document. You can use this at the regular CRUD endpoint
• updatedAt - The date this version was created
• updatedBy - A human readable description describing who created it

With an _id and a refId, we can lookup that specific version via the API

cbc.getById(entityType, id, params, versionId) : Promise for version of document;

Aggregate document data via Mongodb pipeline. For more information, see http://docs.mongodb.org/manual/core/aggregation-pipeline/

cbc.aggregate(entityType, aggregationPipeline);

//Example:
var participantCounters = cbc.aggregate('Event', [
	{ "$match": { "_id": {"$ObjectId": "52f8fb85fae15e6d0806e7c7"} } },
	{ "$unwind": "$participants" },
	{ "$group": { "_id": "$_id", "participantCount": { "$sum": 1 } } }
]);

Work with "DocumentReferences"

A DocumentReference is a unified specification to point to some other (sub-)doucment within the administration. A DocumentReference looks like:

{
	rootDocumentId: '524aca8947bd91000600000c',
	rootDocumentEntityType: 'Person',
	path: [
		{
			field: 'addresses',
			objectId: '53440792463cda7161000003'
		}, ...
	]
}

The contents will be parsed and the requested data will be retrieved.

EXPERIMENTAL - Work with local in-memory cache for query results

The connector may cache documents locally. To enable in-memory cache for a certain instance of the connector:

cbc.enableCache(communibaseAdministrationId, socketServiceUrl)

Contact Kingsquare for these values in your particular scenario and use with caution: BEWARE of excessive memory usage!