This project is inactive. Effektif was accuired by Signavio so the project has moved to signavio-api.
Unofficial node effektif api wrapper.
Table of contents
The module is auto-generated from the effektif documentation json-endpoint.
All Api-endpoints are represented.
The interface constructor takes an object with options.
options
: Object with the following properties:authorization
: optional string - Authorization token, will be set as Authorization http headercredentials
: optional object - Default credentialsusername
: string - Usernamepassword
: string - Password
basePath
: optional string - Effektif-api base url, defaults to api endpoint documentation basePathbaseRequest
: optional - Default requestlog
: optional - Logging function, defaults to console.logusers
: optional - Users instanceonUnauthorized
: optional function that will be called when an unauthorized call is made
Example:
const request = require('request');
const Api = require('effektif-api');
const Users = require('effektif-api').User;
const baseRequest = request.defaults({'proxy':'http://localproxy.com'});
const workflows = new Api.Workflow({
authorization: 'token',
credentials: {
username: 'me@example.com',
password: 'sup3rs3cr3t'
},
basePath: 'http://effektif-cluster.local/api'
baseRequest: baseRequest
});
Optional function used to get user authorization token. The function is called when an unauthorized call was made. If a token is returned in callback the operation will be called with then new authorization token. The function is bound to the module instance on execution, i.e. this
can be used to access module options.
The function signature is:
operationArguments
: The actual operation argumentscallback
:error
: Error if anytoken
: The new authorization token to use
Example:
const db = require('database'); // Arbitrary database module
function onUnauthorized(operationArgs, callback) {
db.findOne({
username: this.options.credentials.username
}).exec((err, doc) => {
if (err) return callback(err);
// Return token in callback
return callback(null, doc.token);
});
}
let workflows = new Api.Workflow({
onUnauthorized: onUnauthorized,
credentials: {
username: 'me@example.com'
}
});
A User instance is created with the same options as the module and this is the function to retrieve it.
Example usage:
const Api = require('effektif-api');
function onUnauthorized(operationArgs, callback) {
let users = this.getUserInstance();
let loginOptions = {};
if (operationArgs.organizationKey) loginOptions.organizationKey = operationArgs.organizationKey;
users.login('me@example.com', 'sup3rs3cr3t', loginOptions, (err, result) => {
// Return token in callback
return callback(err, result && result.token);
});
}
const workflows = new Api.Workflow({
basePath: 'https://effektif.local/api'
});
All interfaces inherit from EventEmitter.
The authorized
event is emitted when a succesfull login was performed.
The listener function will get username
and authorization
-token.
const Api = require('effektif-api');
let workflows = new Api.Workflow({
credentials: {
username: 'me@example.com',
password: 'sup3rs3cr3t'
}
});
workflows.on('authorized', (result) => {
console.log('A good place to store new token', result.authorization, 'for', result.username);
});
const Api = require('effektif-api');
const Tasks = Api.Task;
const tasks = new Tasks({
authorization: 'token'
});
tasks.createTasks('test-org', { workflowId: '1' }, (err, body, resp) => {
if (err) console.log(err);
});
Utility function to get FormField by name from task data.
const Api = require('effektif-api');
const Tasks = Api.Task;
const tasks = new Tasks({
authorization: 'token'
});
tasks.getTask('test-org', '1', (err, resp, task1) => {
if (err) return console.log(err);
let field = task1.getFormFieldByName(task, 'myField');
field.value = '123';
tasks.updateTaskFormField('test-org', task1.id, field.id, field, (err) => {
console.log('success?', !!!err);
});
});
const Api = require('effektif-api');
const Tasks = Api.Task;
const tasks = new Tasks({
authorization: 'token',
credentials: {
username: 'me@example.com',
password: 'sup3rs3cr3t'
}
});
tasks.createTasks('test-org', { workflowId: '1' }, (err, body, resp) => {
if (err) console.log(err);
});
Utility function to perform user login.
const Api = require('effektif-api');
const users = new Api.User();
users.login('me@example.com', 'superse3cret', (err, body) => {
console.log('new token', body.token);
});
Module functions are generated from the api-endpoints.
The name is composed of the http-operation and the api-endpoint.
HTTP-verb | function prefix |
---|---|
GET |
get |
POST |
create |
PUT |
update |
DELETE |
delete |
Examples:
To call POST /{organizationKey}/tasks
:
const Api = require('effektif-api');
const tasks = new Api.Task({authorization: 'token'});
let newTask = {};
tasks.createTasks(organizationKey, newTask, (err, body) => {
console.log(err, body);
});
or DELETE /{organizationKey}/workflows/{editorWorkflowId}
:
const Api = require('effektif-api');
const workflows = new Api.Workflow({authorization: 'token'});
workflows.deleteWorkflow(organizationKey, workflowId, (err, body) => {
console.log(err, body);
});
The plural ending is removed if the noun is immediately followed by a path parameter.
The path parameters will build the method signature. They are considered required.
The query parameters will also be appended to the method signature. All query parametes are considered optional in get-operations.
const Api = require('effektif-api');
const workflows = new Api.Workflow({ authorization: 'token'});
workflows.getWorkflows('test-org', (err, body) => {
console.log('This should work and result in', body);
});
If a body is expected, the query parameters must be defined. Since they are optional, a null
value is accepted.
The operation schemas (joi) are stored with the module.
const Api = require('effektif-api');
const inputSchema = Api.Workflow.schemas.getWorkflow.input;
console.log("#getWorkflow input", inputSchema.describe());
const outputSchema = Api.Workflow.schemas.getWorkflow.output;
console.log("#getWorkflow output", outputSchema.describe());
The schemas are also stored with the instance methods.
const Api = require('effektif-api');
const workflows = new Api.Workflow({ authorization: 'token'});
console.log(workflows.getWorkflows.schemas.output.describe());
All operations takes callback as final argument. The callback is required.
error
: Error or null. Api-calls with a http response status code above 399 will be considered an errorresult
: Operation resulthttpResponse
: The HTTP response from the call to the actual api. Should be returned even if an error has occurred
The module uses debug so run with environment variable DEBUG=effektif-api*
.