It is recommended to read the entire "Getting started" section to get the basic understanding of how this API can be used before starting to use it, as this will reduce your level of stress while working with this API. It is only a few paragraphs long.

We assume you are familiar with some tools like Postman or cURL to be able to make use of this documentation.

Help Center has many articles, such as Hailer Product Description, to help you get more familiar with Hailer.

Staging backend

The examples are written for Hailer's staging (sandbox) backend, which base URL is https://api.hailer.biz/api.

Important: The staging backend is a playground for new versions and database might be cleared from time to time. Let us know if you are working in that environment so we can inform you when we are making changes or dropping data.

Production backend

Hailer's production backend's base URL is https://api.hailer.com/api.

Ways of interacting

There are two ways of interacting with the Hailer API; HTTP REST and Socket.io API. The Socket.io API also provides signals for real-time updates, which is not supported on the HTTP REST API.

HTTP REST

All requests to the HTTP REST API have the operator in the path and the arguments as POST payload in JSON format, Content-Type: application/json. If you use Postman, be sure to set body to raw and type to JSON.

Arguments can be given in three ways.

Type 1, args array as key in an object:

{ "args": ["user@mail.com", "password"] }

Type 2, argument as key mapped object:

{
  "0": "user@mail.com",
  "1": "password"
}

Type 3, argument array:

["user@mail.com", "password"]

Throughout this documentation the examples are generated with Type 2 due to how OpenAPI works. Manually written examples use Type 3, passing a JSON array. Type 1 is there for backwards compatibility.

Socket.io API

The socket API provides events which make responding to updates fast and easy.

To get started using the socket.io api there is a node.js client called HailerCli. See it's README for instructions to set it up. It is both a Command Line Interface (CLI) and SDK.

Three quick steps for starting with the staging backend & HTTP REST

1. Register to Hailer's staging backend.

2. Log in programmatically with cURL, Postman, or your custom application by sending POST request to https://api.hailer.biz/api/login with your username and password as arguments.

Example: log in with cURL

curl -H "Content-Type: application/json" -d '["user@mail.com", "password"]' https://api.hailer.biz/api/login

Example: log in with Postman

["user@mail.com", "password"]

Response on successful login is a session key, for example:

"8cErRKj+F3d1ud7e4TTXZme004jcs5HGNn9tK0LcDqlQAKWpxSpEY8LlYOLgJFWlM5GAqnHbGwTLK28KMenY1g=="

Save the session key to yourself.

3. Now you can run any API command using the given session key (based on the permissions of that user) by setting a cookie hlrkey to the session key, or setting it as an http header directly.

Example: send post to Feed with cURL

curl -s -H "Content-Type: application/json" -H "hlrkey: 8cErRKj...KMenY1g==" -d '[{ "subject": "Posting via API", "text": "Cool post from API." }]' https://api.hailer.biz/api/wall2/new_post

Example: send post to Feed with Postman

Before sending your POST request in Postman, do the following steps:

1. go to Authorization tab
2. set "Type" to "API Key"
3. set "Key" to hlrkey
4. set "Value" to the session key you got

URL: https://api.hailer.biz/api/wall2/new_post

POST request body example:

[
  {
    "subject": "Posting via API", 
    "text" : "Cool post from API."
  }
]

Do you have a workflow or a dataset yet?

Before you can call activities endpoints, you need to have a workflow or a dataset. It is most convenient to create workflows and datasets in the Hailer UI. You can read more about managing workflows and datasets and how to create a custom workflow at Hailer's Help Center.

How to get workflowId and phaseId?

When you have your workflow or dataset created, click the phase or category you want to create a template from, and you will see two ids in the URL path in your browser's address bar. workflowId is the 24-character string after subdirectory named processes, and phaseId is the 24-character string after subdirectory named phase.

Example URL with 000000000000000000000000 as workflowId and 111111111111111111111111 as phaseId: https://app.hailer.biz/#/activities/process/000000000000000000000000/phase/111111111111111111111111/table

Hailer insights exists to provide a simple way for Hailer users to create insights from their data. Primarily we focus on presenting data that comes out from Hailer, but we also want to allow advanced users such as members of our project team to bring data into the Hailer insights tool from other systems.

Hailer insights provides all Hailer data in light SQL chart format. Users can manipulate the data using SQL queries to make it more user friendly. For instance date timestamps become a whole lot more usable when stringifying them into week, month and year and field names can be renamed to be more explanatory.

Insights makes it quick and easy to filter and view the data from different angles. The data can be made into shareable HTML or CSV links or opened up in a pivot view. The pivot view in itself solves a large number of requirements coming from people engaged in business intelligence analysis.

This introduction was picked from this article: Hailer Insights.

Improvements from the previous Insight implementation

• Seamless UX

• Performance

• No session keys need to be extracted and maintained

• No cryptic table names needed

• Almost live data (only caching for performance, which can be bypassed with option)

• Insights can be kept inside the workspace

--

2023-04

• Added support for phase move timestamps
• Added support for teams
• Added support for range fields (all Hailer fields are now supported)

2022-11-22 Insights Native

Insights have been available in Hailer since 2020(??) as a separate service loosely integrated into Hailer. The original implementation was written in whole by Juha Järvinen, and had a separate server downloading activity data and enabling the pivoting. A simple iframe integration to show Insights in Hailer web frontend was written by Jonas Ritzmo.

When enough experience from customer usage was collected in 2022, it was decided to make Insights an integral part of Hailer, and during the development, is was popularly called "Native Insights". At this point the Insight data source was built into the Hailer backend, and a frontend for editing and viewing these Insights was implemented into the Hailer frontend. This effort was a cooperation between Juha Järvinen and André Kaustell.

Introduction

Insight is a simplistic pivoting tool designed to work on all activity data in Hailer, and is designed with potential support for other data sources in mind.

An Insight contains defined data sources. These sources are Activities from Workflow and Datasets, their fields and meta data. These sources are built into temporary SQLite tables, on which a user defined query is executed, building the final output. This output is then read into the Insight component in the frontend which provides pivoting functionality to the user.

In order to not break Insights when Workflows are trivially changed, like field names or workflow name, Insights are built using the underlying fieldId's. Those are defined in sources.

Key features

• New Insights can be created by workspace administrators and owners
• When creating or editing an Insight a preview of the result is presented, or error shown if Insight is incomplete or broken
• An Insight can have one of the following visibility and edit permission: per user or team
• Insights listing for workspace users
• Workspace administrators and owners can see all Insights available in a workspace
• Ordinary workspace Users and Inviters can see Insights with in which they are members, and edit those which they have edit permission set
• An Insight always concerns one workspace, it can not collect data from many workspaces
• If an Insight is set as public, it is accessible through a secret link, which requires no authentication for viewing the Insight
• The data presented in an Insight must always be up to date (Up to 60 minute delay is acceptable)

When adding or editing an Insight, the following parameters can be set:

• Name
• Which workflows/datasets it concerns
• Visibility and edit permission: per user or team
• Public: Yes / No
• SQLite query
• Timestamp when Insight last updated

Not yet implemented:

• Default view configuration

Endpoints

v3.insight.list
v3.insight.create
v3.insight.update
v3.insight.preview
v3.insight.data
v3.insight.member.add
v3.insight.member.remove
v3.insight.permissions.grant
v3.insight.permissions.deny

Publicly available endpoints:

v3.insight.public

See test/test-story-insight.ts, for usage examples of endpoints.

Database

Insights have a collection in the database.

Permissions

Insights are workspace specific and their permissions are based on the members structure, providing user and team specific view or edit permissions.

Public

When an Insight is created, a publicKey is generated. When public is set to true, the publicKey will allow access to anyone with the link. The publicKey cannot be changed.

There is a fronend implementation which produces the link based on the publicKey, and it ends up being something like this:

https://app.hailer.com/insight?key=<publicKey>

The frontend implementation uses the v3.insight.public endpoint to get data from the API.

Selecting sources, field support and SQL mappings

Fields

All activity field types are supported. Field type mappings are as follows FieldType: '<SQLite Type>':

All range fields will result in two columns, with Start and End added to the name.

numeric: 'REAL',
numericunit: 'REAL',
date: 'INTEGER',
time: 'INTEGER',
datetime: 'INTEGER',
timerange: 'INTEGER',
daterange: 'INTEGER'
datetimerange: 'INTEGER',
activitylink: 'TEXT',
country: 'TEXT',
teams: 'TEXT',
text: 'TEXT',
textarea: 'TEXT',
textunit: 'TEXT',
textpredefinedoptions: 'TEXT',
users: 'TEXT',

Meta data

Meta data from activities can be read using the following meta keys:

_id           // activityId
uid           // createdBy userId
createdBy     // createdBy userId
name
created       // Unix timestamp when activity was created
updated       // Unix timestamp when activity was last updated
phaseId       // current phase id
phaseName     // name of current phase
phaseLastMove // Unix timestamp of when activity was last moved to given phaseId
workflowId    // workflow or dataset id
workflowName  // workflow of dataset name

For users and teams there are tables created so they are accessible in every Insight by default. These meta tables are called user and team, and both have _id and name columns.

Example with activity name and createdBy:

v3.insight.create(
    <workspaceId>,
    {
        name: 'Book Insights',
        sources: [{
            name: 'books',
            workflowId: <workflowId>,
            fields: [
                { name: 'title', meta: 'name' },
                { name: 'addedBy', meta: 'createdBy' }
            ]
        }],
        query: 'SELECT title, adder.name FROM books LEFT JOIN user AS adder ON adder._id = books.addedBy',
    }
)

Example with phaseLastMove:

v3.insight.create(
    <workspaceId>,
    {
        name: 'Tasks',
        sources: [{
            name: 'Done',
            workflowId: <workflowId>,
            fields: [
                { name: 'Title', meta: 'name' },
                { name: 'done', meta: 'phaseLastMove', phaseId: <phaseId> }
            ]
        }],
        query: "SELECT Title, datetime(done, 'unixepoch') AS done FROM Tasks",
    }
)

Example with range field:

v3.insight.create(
    <workspaceId>,
    {
        name: 'Project durations',
        sources: [{
            name: 'Projects',
            workflowId: <workflowId>,
            fields: [
                { name: 'Title', meta: 'name' },
                { name: 'Duration', meta: 'phaseLastMove', phaseId: <phaseId> }
            ]
        }],
        query: "SELECT Title, datetime(DurationStart, 'unixepoch') AS Start, datetime(DurationEnd, 'unixepoch') as End FROM Projects",
    }
)

Introduction

Roles are still work in progress.

Creating, editing, listing and removing of roles is currently possible with workspaces with 'customRoles' license override

Key features

Roles don't do anything yet, you can just remove edit and add them.

• Workspace administrators and owners can see and manage all Roles available in a workspace
• Workspace Users, Inviters and guests cannot see or manage any Roles
• Roles are workspace specific

Endpoints

v3.network.role.list
v3.network.role.create
v3.network.role.update
v3.network.role.remove

See test/test-api-v3-network-role.ts, for usage examples of endpoints.

Database

Roles have a collection in the database.

Permissions

Roles are can be managed by workspace owners and admins. This might change to include some permission like 'role-manager' for a custom role