kazana-group-entities

This is a fork of kazana-entities, adding group permissions, to check if we can use this in Guinea Connect. The groups are slightly simplified compared to le grande masterplan, theres no specific read/write permissions, only access/no access.

How to limit entity access:

Access are controlled by the access property on objects

• Admins can access all items
• If an object has no access key, all authenticated users can read, only admins can update/delete
• If an object has an access key only users whose roles are in that array can access

kazana-groups are prefixed, kazana-group:ps-myplace on the user conforms to ps-myplace in the access array

Rest API

GET /api/entities

Gets api info (version of kazana-entities) This route is useful sonce it doesn't require auth so you can use it to find the other routes when running this as a plugin. (Kazana namespaces routes from plugins)

GET /api/entities/{type}

gets all entities of a certain type

Optional Query Params: limit and skip can be passed in to do pagination

GET /api/entities/{type}/id

gets a certain entity

POST /api/entities/{type}

Create a new entity, the payload need to include 'id' and 'name'

PUT /api/entities/{type}/id

Update an entity

DELETE /api/entities/{type}/id

Deletes an entity

Per default, all the routes require authorization

Client (server) side library

When you need to use data from kazana-group-entities in your other kazana-plugins, there's a client side library. Here's how to use it:

var entitiesClient = require('kazana-group-entities/lib/client')

// this is a hapi request handler
function hapiRequestHandler (request, reply) {
  return Promise.all([
    // client uses request for auth
    entitiesClient.find(request, 'facilities', 'hm0330'),
    entitiesClient.all(request, 'report-types')
  ]).then(function (res) {
    var facility = res[0]
    var reportTypes = res[1]

    // do something here and call reply
  })
}

entitiesClient.find(hapiRequest, entityName, id)

returns a promise, then an object with the entity

entitiesClient.all(hapiRequest, entityName)

returns a promise, then gives all entities of this type

{
  total: 2,
  data: [{ /*entity1*/ }, { /*entity2*/ }]
}

Using in your kazana app

It's recommended that you create a new app, that uses kazana-entities as a dependency. Then you apply configuration and bootstrap data from the repository of your app. A short example:

Route prefixes when running as a plugin

When kazana-group-entities is running as a plugin, the routes will be prefixed with /kazana/group-entities. For example will the first route above be /kazana/group-entities/api/entities.

// myproject-entities/index.js

var path = require('path')
var entitiesApp = require('kazana-group-entities')

entitiesApp.name = 'myproject-entities'
entitiesApp.version = require('./package.json').version
entitiesApp.bootstrap = path.resolve(__dirname, 'bootstrap')

module.exports = entitiesApp

Bootstrapping data

Bootstrap the database via kazana-bootstrap

// myproject-entities directory

bootstrap/
  |
   -myproject-entities/ (name must match .kazanarc, see below)
      -entitype:id.json (one json file / bootstrap doc)

See kazana-bootstrap for more bootstrap options (users, security, etc)

Configuration

Configure the database name through kazana-config

// myproject-entities/.kazanarc

[db]
  entities=myproject-entities

List of Entities

The only required property for all entities is "name". An optional "aliases" array allows set alternative names by with an entity can be found as well.

Use Cases

1. Select boxes for values, e.g. in a registration form, or inindices
2. Validation of data reports
3. Search / Filtering of data in the bottleneck analysis dashboard