zn-resource

Handle Zengine API resources in Zengine backend services (unofficial and experimental).

Install

$ npm install zn-resource

Use

// Require the built-in ZnHttp (notice the path depends on where you are)
var ZnHttp = require('../../lib/zn-http.js');

// Inject ZnHttp into zn-resource and ask for the resource service you want
var znRecordService = require('zn-resource')({ resource: 'record', ZnHttp: ZnHttp });
var znFormService = require('zn-resource')({ resource: 'form', ZnHttp: ZnHttp });
var znActivityService = require('zn-resource')({ resource: 'activity', ZnHttp: ZnHttp });
var znMemberService = require('zn-resource')({ resource: 'member', ZnHttp: ZnHttp });

For each of those services, you should be able to perform regular operations plus extra things, depending on the service. The interfaces are similar:

• get one resource with get passing an id
• query resources with query passing a request object – the service will be smart enough to figure out what goes on the endpoint and what goes as query params
• save a resource with save passing resource data – if data has no id, it will create a new resource, otherwise it will update the existing resource

Records

Get record:

  var compositeId = {
    id: 40
    formId: 5
  };

  // GET /forms/5/records/40
  znRecordService.get(compositeId).then(function(record) {
    // record.id === 40
    // record.formId === 5 (set by the service for convenience)
  });

Query records (paginated):

  var request = {
    formId: 5
    field123: 'apples'
  };

  // GET /forms/5/records?field123=apples
  znRecordService.query(request).then(function(response) {
    // response.totalCount
    // response.data
  });

Create record:

  var recordData = {
    formId: 5,
    field123: 'apples'
  };

  // POST /forms/5/records
  znRecordService.save(recordData).then(function(record) {

  });

Update record:

  var recordData = {
    id: 40,
    formId: 5,
    field123: 'apples'
  };

  // PUT /forms/5/records/40
  znRecordService.save(recordData).then(function(record) {

  });

Find by field value:

  var request = {
    formId: 5,
    fieldId: 123,
    value: 'apples'
  };

  // GET /forms/5/records?field123=apples&limit=1
  znRecordService.findByFieldValue(request).then(function(record) {
    // record or null
  });

Forms

Similar to record service but you get an instance of ZnForm instead, which means you not only get form data but you can also call methods.

  // GET /forms/5
  znFormService.get(5).then(function(form) {
    // form instanceof ZnForm === true
    // form.id === 5
    // form.getEmailValidatedFields()
  });

Query forms

  var request = {
    workspace: {
      id: 18
    }
  };
  
  // GET /forms?workspace.id=18&attributes=id,name&related=fields,folders
  znFormService.query(request).then(function(response) {
    // response.data is array of ZnForms
  });

Workspace Membership

Pseudo-resource concerning the current user and a workspace.

  var workspaceId = 18;
  znMemberService.get(workspaceId).then(function(membership) {
    // membership.userId (via /users/me)
    // membership.isOwner (boolean)
    // membership.isAdmin (true, if owner or admin)
    // membership.isMember (true, if member of any kind)
  });

Testing

To test your backend service without doing actual requests to Zengine, you can use zn-resource-fake.