OpenPlatform / 06. OpenPlatform module
Updated: 14. October 2019
Author: Peter Širka

06. OpenPlatform module

The module can simplify work with OpenPlatform and it's targeted for OpenPlatform applications.

Topics:

Features

  • the module reads openplatform.json from root of the application
  • it can modify openplatform.json dynamically
  • it reads meta-data
  • it handles user synchronization very effective
OP; // {Object} is a global variable defined in module
OP.meta; // {Object} returns a meta data from "openplatform.json" file
OP.meta.save(); // {Function} can re-save meta-data into the "openplatform.json" file

Authorization

Create a definition file called auth.js with the content below:

Delegate OP.init

This delegate is executed if the OpenPlatform is initialized for the first time or if the module synchronizes the OpenPlatform again, it's each 10 minutes. Be careful because the application can handle multiple and different OpenPlatform instances.

OP.init = function(platform, next) {

    // platform.id {String}
    // platform.directoryid {String}
    // platform.directory {String}
    // platform.openplatformid {String}
    // platform.name {String}
    // platform.email {String}
    // platform.url {String}
    // platform.urlmeta {String}
    // platform.users {String}
    // platform.apps {String}
    // platform.services {String}
    // platform.servicetoken {String}
    // platform.sn {String} means Serial number
    // platform.settings {Object}

    // IMPORTANT:

    // Continue to application
    // next([err]);
    next();
    
    // OR you can respond with an error
    // next('Sorry, your OpenPlatform is blocked');
};

Method OP.auth

The code below performs authorization of user. The module handles sessions automatically and very effective.

AUTH(function($) {

    var op = $.query.openplatform;
    if (!op || op.length < 20) {
        $.invalid();
        return;
    }

    // Saves memory
    $.query.openplatform = undefined;

    var opt = {};
    opt.url = op;

    OP.auth(opt, function(err, user, type, cached, raw) {

        // @type 0 : from session
        // @type 1 : profile downloaded from OP without OP meta data
        // @type 2 : profile downloaded from OP with meta data
        // @cached : means that meta data of OP has been downloaded before this call
        // @raw    : contains a raw received data

        if (user) {

            if (type) {
                user.filter.push(user.id);
                user.admin = user.sa || user.roles.indexOf('admin') !== -1;
            }

            user.language && ($.req.$language = user.language);
            $.success(user);

        } else
            $.invalid();
    });
});

Synchronization

Synchronization of users is very simple with this module. You can synchronize users easily between app and OpenPlatform.

// OP.users.autosync(interval, init_options, options, process, after, before);
// @interval {String} e.g. 30 minutes
// @init_options {Object} init options for the synchronization immediately, "null" skips init synchronization
// @options {Object} options for the synchornization
// @process {Function(users, next, platform)}
// @after {Function(err, counter)}
// @before {Function(platform)} if returns "false" then the synchronization won't be processed.

// @init_options or @options argument can contain:
// options.removed {Boolean}
// options.modified {String} e.g.: 1 hour
// options.fields {String} e.g.: id,name,email
// options.id {String} e.g. id1,id2,id3
// options.appid {String}
// options.role {String}
// options.group {String}
// options.q {String} search query
// options.ou {String} organization unit
// options.locality {String}
// options.company {String}
// options.directory {String}
// options.statusid {Number}
// options.customer {Boolean} only customers
// options.reference {String}
// options.online {Boolean} only online users
// options.logged {String} e.g.: 1 hour

// Synchronizes only modified users
OP.users.autosync('30 minutes', {}, { modified: '1 hour' }, function(users, next, platform) {

    // @users {Object Array} max. 100 users
    // @next {Function} processes next 100 users
    // @platform {Object} meta information about the platform

    next();

}, null);

// Synchronizes only online users
OP.users.autosync('30 minutes', {}, { online: '10 minutes' }, function(users, next, platform) {

    // @users {Object Array} max. 100 users
    // @next {Function} processes next 100 users
    // @platform {Object} meta information about the platform

    next();

}, null);

Services

The module can handle service requests from OpenPlatform. It means that another OpenPlatform application can communicate with your application through the OpenPlatform.

OP.services.init(function(meta, next) {

    // meta.id {String} A unique ID of OpenPlatform
    // meta.openplatformid {String}
    // meta.directoryid {String}
    // meta.userid {String}
    // meta.verifytoken {String}
    // meta.servicetoken {String} A unique token generated by OpenPlatform, you can compare it with "meta.servicetoken" obtained in "OP.init()"

    // next(null, true);
    next(null, false);
});

The method below registers a new endpoint for the OpenPlatform services.

OP.services.route('/api/something/', function(err, meta) {

    // @err {Error} Always nullable because "OP.services.check" handles error automatically

    // meta.id {String}
    // meta.openplatformid {String}
    // meta.directoryid {String}
    // meta.userid {String}
    // meta.verifytoken {String}
    // meta.servicetoken {String}

    // self.body {Object} --> RECEIVED DATA from another app
    self.success();
});

User session

$.user
controller.user
// ==== Basic public data
// user.id {String}
// user.openplatformid {String}
// user.darkmode {Boolean}
// user.dateformat {String}
// user.datefdow {String}
// user.email {String}
// user.filter {String Array}
// user.language {String}
// user.name {String}
// user.photo {String}
// user.roles {String Array}
// user.sa {Booealn}
// user.status {String}
// user.statusid {Number}
// user.timeformat {String}
// user.dtlogged {Date}

// ==== Internal data
// user.profile;
// user.platform;

// ==== Methods

Method: user.permit()

This method returns first found allowed permission.

// user.permit(type, permissions)
// @type {String}
// @permission {String Array}
// return {String}

// https://wiki.totaljs.com/dbms/04-querybuilder/#-builder-permit-name-type-value-useridfield-userid-must-
var permissions = ['R@admin'];

console.log(user.permit('CRUD', permissions));
// Output: R

Method: user.permissions()

This method returns all allowed permissions.

// user.permit(type, permissions)
// @type {String}
// @permission {String Array}
// return {String}

// https://wiki.totaljs.com/dbms/04-querybuilder/#-builder-permit-name-type-value-useridfield-userid-must-
var permissions = ['R@admin', 'D@admin'];

console.log(user.permit('CRUD', permissions));
// Output: RD

Method: user.copy()

Copies values from specified keys to a new object instance.

// user.copy(key1, key2, keyN)
// return {Object}

console.log(user.copy('id', 'name', 'email'));
// { id: ..., name: ..., email: ... }

Method: user.json()

Serialized basic user-data into the JSON.

// user.json()
// return {String}

Method: user.service()

IMPORTANT: Sends a data to another OpenPlatform application via POST method.

// user.service(app, service, data, callback)
// @app {String} can contain Application ID, Application Reference or Application Name
// @service {String} a name of service/endpoint
// @data {Object} a data
// @callback {Function(err, response)}

user.service('files', 'browse', {}, function(err, response) {
    console.log(err, response);
});

Good to know: user.service('openplatform', 'servicename', ...) will execute operation directly in the OpenPlatform instance. Just you need to specify custom operations in the form:

NEWOPERATION('api_YOURSERVICENAME', function($) {
    $.success();
});

NEWOPERATION('api_servicename', function($) {
    $.success();
});

Method: user.logout()

Removes user session from memory.

// user.logout()

function action_logout() {
    var self = this;
    self.user.logout();
    self.success();
}

Notifications and Badges

Global methods for sending notifications or badges.

Notifications

OP.users.notify(url, data, callback);
// @url {String} User absolute URL for notifications
// @data {Object}
// @callback {Function(err, response)}

// data.type {Number} 1: success, 2: warning, 3: info
// data.body {String} A markdown message
// data.data {String} A custom data which will be sent into your application

Badges

OP.users.badge(url, callback);
// @url {String} User absolute URL for badges
// @callback {Function(err, response)}

Hidden features

OP.sessions;  // {Object} contains all session instances
OP.platforms; // {Object} contains all platform instances
OP.blocked;   // {Object} contains all blocked instances
OP.services;  // {Object} contains all service instances