CentriQS API

CentriQS provides a simple yet powerful REST-based application program interface to interact with the program: create, retrieve, update and delete records, perform searches, and more.

Learn more Download sample application

Overview

CentriQS prebuilt and customizable solutions offer advanced features to fit your business needs. However, there may be some specific requirements that are not supported by existing functionality. In this case, you can use CentriQS application program interface to implement necessary capabilities, provided you have a basic knowledge in software development and Web services.

We recommend you to get started by following the steps below:

  1. Learn more about CentriQS Application Server, Databases Components and Simple Web Server
  2. Use Sample Application and API Reference
  3. Request Support

Application server includes:

  • System Database (stores information about Server Administrators, License Keys and Mail Settings)
  • Databases
  • Web API (uses port 6496 to connect to server)

Authentication

Authentication can be done in either of two ways:

  • Using PUT request http://<serverhostname>:6496/api/databases/<databaseID>/auth with body (JSON text):
      1. {
      2. "User": '<user name>',
      3. "PasswordHash": '<password>'
      4. }
  • Using your login/password via HTTP Basic authentication (HTTP Header "WWW-Authenticate")

Session

Any request can be made within a session which contains information about user authentication and connected database.

A new session can be started in two different ways:

  • Using POST request: http://<serverhostname>:6496/api/session (5 minute timeout)
  • Using any request without ID of already started but not yet closed session (in this case a new session will be started automatically with 5 second timeout and its ID will be encrypted in the cookie)

There are three ways to specify within what opened session the given request should be made:

  • Using request URL: http://<serverhostname>:6496/api/session?sid=<session ID>
  • Using HTTP Header SID: <session ID>
  • Using cookie
Note that each new request within an opened session initiates new 5 minute timeout.

An opened session can be closed by:

  • Using DELETE request http://<serverhostname>:6496/api/session
  • Otherwise the session will be closed automatically after 5 minutes from the last request

Database

Each database includes:

  • Metadata
  • Database Tables
  • Entities
  • Analytics

Metadata

Metadata contains information of all data types in the database. It has a tree structure and allows users to request contents of particular nod as well as contents of its sub nodes.

Request that returns the contents of all nodes and their sub nodes in the database:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/metadata

Request that returns the contents of ‘entities’ node:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/metadata/entities

Request that returns the contents of nod ‘task’ and contents of its sub notes:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/metadata/entities/task?all=1

(where 'all=1' is a parameter used to get the contents of sub nodes)

Database tables

Each database includes the following database tables (i.e. tables which structure is almost similar to relational database tables):

  • Notifications table contains records of all notifications created up to the given moment
  • TmSchedulerRecord table contains records of task schedule items and appointments for displaying on Scheduler view.

Request that returns the list of new notifications with all fields:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/tables/notifications?filter=[New]

Request that returns the list of notifications with selected fields:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/tables/notifications/query?filter=[New]&fields=subject;new;read;eventkind

(where field1;field2;…;fieldN are fields names)

Request that returns the list of scheduler records with selected fields and set parameters:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/tables/TmSchedulerRecord/query ?fields=id;start:asc;finish;allday;users;folder:folder.title

(where [:asc] is ascending sorting (or [:dsc] descending sorting) and [:folder.title] is expression which is used to display value 'field title' instead of 'field name')

Entities

Entity is a fundamental unit of the database. It has Properties and can aggregate Entity Tables which also have their Properties, ex.:

Request that returns the list of all tasks with all fields:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task

Request that returns the list of filtered tasks with selected fields and set parameters:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task/query?fields=id;name:asc&filter=[state]='Vqs.Tm.Shared.TmTaskStates.InProgress'

Request that returns all fields of the given task:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task/<entityID>

Entities can be edited in two ways (only if no other user is editing it at that very moment):

  • Within a single request (entity gets opened for editing, is being edited and then saved in one step)

    Request that changes property 'Name' of the given task:

    PUT: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task/<entityID>
    Content:

      1. {
      2. "Properties":
      3. {
      4. "Name": "My Task New Name"
      5. }
      6. }

    Request that assigns the given task to the given user (adds User to entity table 'TaskAssignment'):

    POST: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task/<entityID>/TaskAssignment
    Content:

      1. {
      2. "Properties":
      3. {
      4. "User": "<user ID>"
      5. }
      6. }

  • Within multiple requests (the first request opens a copy of the entity for editing, next requests edit the copy of the entity and the last request saves the changes from the copy into the original entity)

    Request that opens a copy of the original task for editing:

    POST: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task/<entityID>/edit

    Request that returns all the fields of the copy of the original task:

    GET: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task/<entityID>/edit

    Request that assigns the copy of the original task to the given user (adds User to entity table TaskAssignment):

    POST: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task/<entityID>/edit/TaskAssignment

    Content:

      1. {
      2. "Properties":
      3. {
      4. "User": "<user ID>"
      5. }
      6. }

    Request that saves the changes made in the copy into the original task:

    GET: http://<serverhostname>:6496/api/databases/<databaseID>/entities/task/<entityID>/edit/save

Analytics

Analytics includes:

  • OLAP Cubes
  • Dimension Tables.

OLAP Cubes contain fields of two different types: measures and dimensions. Measures are calculated values and can be of numeric types only. Dimensions can be of any type including reference to Dimension Tables (except for BLOB type and its derived types Image, BigString, etc.).

OLAP Cube structure example:

OLAPCube: Facts_TaskWorkTurnoverRegistry
Fields:


ChangingDate: Dim_TimeKey (Dimension)
ClosedDate: Dim_TimeKey (Dimension)
Priority: Dim_TmPriority (Dimension)
Owner: Dim_Users (Dimension)
Project: Dim_Project (Dimension)
HasSubtasks: Boolean (Dimension)
Estimate: Double (Measure)
Remain: Double (Measure)
Actual: Double (Measure)
Completed: Double (Measure)

Request examples:
Request that returns selected fields and settings of the given OLAP Cube:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/analytics/olapcubes/<cube name>?fields=<fields>&settings=<settings>

Note that if selected fields are of measure type, they must include aggregate function (Sum, Min, Max, etc.)

Request that returns the dynamics of remaining time per project summed up by task owners sorted ascendingly for the last year divided by weeks:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/analytics/olapcubes/TaskWorkTurnoverRegistry?fields=remain:sum(remain);owner:asc;project&settings=dm;ChangingDate;Week;LastYear

Dimension Tables are reference tables that store Dates & Time, Enums and Entities to which refer OLAP Cube fields.

Dimension Tables structure examples:
Dim_TimeKey:

Key: DateTime;
Title: String;
Year: DateTime;
Quarter: DateTime;
Month: DateTime;
DayOfMonth: Integer;

Dim_Users:

Key: GUID;
Title: String;
Code: string;
EntityModifiedTime: Dim_TimeKey;
Folder: Dim_Folders;

Dim_Project:

Key: GUID;
Title: String;
Code: string;
EntityModifiedTime: Dim_TimeKey;
Folder: Dim_Folders;

Request examples:

Returns the list of all records of the given dimension table:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/analytics/dimensions/Dim_TimeKey

Returns the details of the given record of the given dimension table:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/analytics/dimensions/Dim_TimeKey/{id}

Returns the list of all records with selected fields of the given dimension table:

GET: http://<serverhostname>:6496/api/databases/<databaseID>/analytics/dimensions/Dim_TimeKey/query?fields=id;key;title;Year;MonthOfYear;DayOfMonth;DayOfWeek

Simple WEB server

Simple Web Server (which is based on Application Server) makes it easy to create and deploy HTML5 and JavaScript Web applications that let users generate custom reports, import/export data from/to other programs, integrate with other applications and much more.

It returns files 'as is' from the directory: c:\ProgramData\VIP Quality Software\CentriQS\www by URL: http://<serverhostname>:6496/<path> (relative path …\CentriQS\www)

Request that returns Web API documentation from directory with path c:\ProgramData\VIP Quality Software\CentriQS\www\doc:

GET: http://<serverhostname>:6496/doc/index.html