OpenPlatform / 02. How does it work?
Updated: 13. March 2018
Author: Peter Širka

02. How does it work?

Professional Support Chat with contributors

OpenPlatform has a simple logic. It's a container for users and third-party applications. Each application needs own domain name and it needs to contain a file openplatform.json with application's meta data.

For example: https://127.0.0.1:8001/openplatform.json

{

    // required, application's name
    "name": "TestApp",

    // required, application's description
    "description": "Some text for the super user.",

    // required, application's version
    "version": "1.0.0",

    // required, application's icon
    "icon": "http://127.0.0.1:8001/icon.png",

    // required, application's URL address which is open in iFrame
    "url": "http://127.0.0.1:8001",

    // required, author of the application
    "author": "Peter Širka",

    // required, email to support
    "email": "petersirka@gmail.com",

    // optional, custom roles (String Array)
    "roles": ["create", "read", "update"],

    // optional, your custom server-side IP addresses for remote access e.g. for sending notifications (String Array)
    "origin": ['IP_address']
}

Authorization

OpenPlatform has a very simple authorization mechanism. The whole authorization is executed on the client-side over iFrame messaging if the server-side verification is disabled.

Authorization processing

  • user launches some app in OpenPlatform main window
  • app is open in iframe container
  • then app needs to init OpenPlatform client-side library
  • main window OpenPlatform checks the app and roles on the server-side
  • then iframe obtains meta-data described below

Client-side library

OpenPlatform offers a small client-side library called openplatform.js. The application can obtain user/meta-data from OpenPlatform and it supports another features for OpenPlatform manipulation.

App meta-data

Your application needs to use this code below:

<script src="https://cdn.totaljs.com/openplatform.min.js"></script>
<script>

    OPENPLATFORM.init(function(err, response, redirectTimeout) {

       // response === meta-data

        if (response.serverside) {
            // 1. you don't have all data because of security context
            // 2. you need to send a verification URL to your backend
            // 3. and your backend needs to create a request to verification URL
        } else {
            // you have all meta-data from OpenPlatform
        }

    });

</script>
  • if err contain a value then app can't continue (otherwise: null)
  • response contains all meta data
  • reidrectTimeout contains an ID of timeout if the redirect will be executed

Sample of meta data

The content depends on application's privileges.

{
    // {Date} Current date/time
    "datetime":"2017-09-11T08:29:10.621Z",

    // {String} Current user IP
    "ip": "78.98.35.929",

    // {String} Custom settings (defined in application's section)
    "settings": ""

    // {String} ID of application
    "id": "se1hlb6qfbd852av4m2n",

    // {String} OpenPlatform URL address
    "openplatform": "https://openplatform.totaljs.com",

    // {String} Application's URL address
    "url": "http://127.0.0.1:8001/",

    // {String} A redirect URL (optional)
    "redirect": "http://127.0.0.1:8001/orders/"

    // {String/Object/Number/Boolean/Time} A data from another third-party application (optional)
    "data": null,

    // {Boolean} Inditicates a server-side verification of the user profile
    "serverside": false,

    // {String} URL address for verifying of the meta data on server-side (BTW: CORS enabled), response contains same result
    "verify": "https://openplatform.totaljs.com/api/verify/?accesstoken=i343839tzj14zsgfenapdlxoqa300asdqo-se1hlb6qfbd852av4m2n-pokp1xaccwtjgqpdtn00rik054hhvbg0p5qvdpal-17082512500002gkj0",

    // {Object} OpenPlatform meta data (code lists)
    "meta": {
        "companies":   [{ "count": 1, "name": "Name", id: "name" }],
        "customers":   [{ "count": 1, "name": "Name", id: "name" }],
        "departments": [{ "count": 1, "name": "Name", id: "name" }],
        "groups":      [{ "count": 1, "name": "Name", id: "name" }],
        "languages":   [{ "count": 1, "name": "Name", id: "name" }],
        "places":      [{ "count": 1, "name": "Name", id: "name" }],
        "positions":   [{ "count": 1, "name": "Name", id: "name" }]
    },

    // {Object} User profile
    "profile": {

        // {String} ID user
        "id": "17082512500002gkj0",

        // {String} ID supervisor, can be empty (optional)
        "idsupervisor": "17082512500002gkj0",

        // {String}
        "firstname": "Peter",

        // {String}
        "lastname": "Širka",

        // {String}
        "name": "Peter Širka",

        // {String} Can be "male" or "female"
        "gender": "male",

        // {String} Languages can be defined in OpenPlatform "config"
        "language": "sk",

        // {String} Photo URL address (optional)
        "photo": "https://openplatform.totaljs.com/201709022152_19xhww41.jpg",

        // {String} A custom reference (optional, can be defiend in "Users" section)
        "reference": "",

        // {String Array} User roles for this application (optional, can be defined in "Users" section)
        "roles": ["read"],

        // {String Array} User global roles defined in "Users" section
        "globalroles": [],

        // {String Array} User global groups defined in "Users" section
        "globalgroups": [],

        // {Date} Date of birth
        "datebirth": "1984-11-05T23:00:00.000Z",

        // {Date} Creation date - profile
        "datecreated": "2017-08-25T10:50:38.648Z"

        // {Date} Update date - profile
        "dateupdated": "2017-08-25T10:50:38.648Z"

        // {Date} When did the user begin in your company? (optional)
        "datebeg": "2017-08-25T10:50:38.648Z"

        // {Date} When did the user end in your company? (optional)
        "dateend": "2017-08-25T10:50:38.648Z"

        // {String} + optional
        "company": "Company",
        "companylinker": "company",

        // {String} + optional
        "group": "Developers",
        "grouplinker": "developers",

        // {String} + optional
        "depeartment": "IT department",
        "depeartmentlinker": "it-department",

        // {String} + optional
        "place": "Slovakia",
        "placelinker": "slovakia",

        // {String} + optional
        "position": "Web developer",
        "positionlinker": "web-developer",

        // {Boolean} Is super-admin account?
        "sa": true,

        // {Boolean} Is the user online?
        "online": true,

        // {Boolean} Is the user blocked?
        "blocked": false,

        // {Boolean} Has the user enabled sounds?
        "sound": true,

        // {Boolean} Has the user enabled notifications?
        "notifications": true,

        // {String} URL address for sending of push notification
        "notify": "https://openplatform.totaljs.com/api/notify/?accesstoken=i343839tzj14zsgfenapdlxoqa300asdqo-se1hlb6qfbd852av4m2n-pokp1xaccwtjgqpdtn00rik054hhvbg0p5qvdpal-17082512500002gkj0"
    },

    // {Object Array} Users
    "users": [

    ],

    // {Object Array} Applications
    "apps": [

    ]
}

Limitations

Modern browsers block third-party cookies in iFrames (Safari). In other words: your application can't use cookies. This behaviour can be disabled in web browser's settings.