Getting started

Hi, nice to see you.

Let’s build awesome things.

This is the developer guide for the Q. API, which allows developers to access entities and business logic of Q. We’re glad you’re here, and we hope that the documentation will help you build something awesome.

At HQLabs we do our best to build a powerful and easy-to-use public API. What does that mean to you? It means that if you see something happening in the Q. web app, you can probably do that same thing via the API.

Before you get started you’ll need to do the following steps:

  • Create an account in Q.
  • Check out the article about Authentication.
  • Check out how the API works.
Yes No Suggest edit
Last updated on 13. Mai 2018

API Description

Request Structure

The Q. API is available via HTTP endpoints and follows a RESTful address structure where resources are selected with text and Id segments in the URL. Typically Ids are in Guid format, i.e. a hexadecimal representation of a 128-bit integer separated by hyphens.
Other values are usually sent in the body of the request, which are only accepted in JSON format (content type: application/json).

Base URL: https://myQ.ai/api/v1/

CRUD Calls vs. Business Operations

Most API calls contain simple CRUD endpoints to handle the data manipulation for that particular entity. In some cases the default POST, PUT or DELETE routes are replaced by so-called business operations. The reason for this separation is that actions do not only manipulation the entity itself, but also affect other entities or even trigger further actions, workflows or events in other parts of Q. An example for this would be an automatic task creation triggered by the status change of a project.

Business operations can be identified by an additional segment in the URL, which usually begins with a verb. For Example:

  • setArchived
  • removeProjectMember
  • renameTag
  • setStatus
  • etc.

Deleted vs. Archived

In some cases, deleting an object can have unintended side effects because of dependencies of other objects. An example for this is the project type. Once you’ve linked projects to a particular type, it can be complicated to delete the type because you will have to move all projects using that type to another type. For these cases you can set that particular object to archived, which is a form of soft-deletion. Once flagged as archived, it can no longer be used, but still exists for legacy data it is already linked to.

Error Handling

In case a request to our API fails, the return value of the endpoints follows standard HTTP status code conventions. A detailed reason can be found in the response. Common codes indicating a client error are 400 (Bad Request) & 404 (Not Found). To give some further information on the cause of the error the API also returns a standardized error object in the response body:

{
  "code""validation-failed"
  "description""The model sent in the request is invalid. See the validation errors for details."
  "link""https://developers.hellohq.io/#response-types",
 "space""On Venus a day is longer than a year.",
 "details": [ 
    "Some more details about the error can go here.",
    "Or here."
  ]
  "validationErrors": [ 
    {
      "property""Name"
      "message""'Name' should not be empty."
    }
  ]
}
  • Code: These string error-codes are constants indicating the exact misbehaviour. The following codes are in use:

Code
Description
teamid-missing
The request is missing a valid team id. Most likely your token is invalid.
not-foundThe requested resource could not be located.
entity-archivedThe request tried to perform an operation with an archived entity.
duplication-violationA property that requires a unique value detected a duplication.
database-commitThe commit to the database failed. Your changes have not been commited!
concurrency-violation
Concurrent processes changed data and created conflicts in the process.
date-dependencyTwo or more date values are in violation with each other (e.g. start date after due date).
date-out-of-range
A single date value is not in its validity range (e.g. birth date in the future).
value-out-of-rangeA value is not in its defined range of validity (e.g. negative prices).
invalid-operationThe request would have caused an illegal data state.
invalid-model
The body of the request is invalid or empty.
validation-failed
The model validation of the request failed.
server-errorAn internal error occured.
already-exist-errorThe request adds an entity which already exists.
invalid-filter-or-order
The request contains an invalid filter or sort statement.
illegal-property-transition
The request would cause a value transition which is not allowed.
unauthorizedThe owner of the request has insufficient permissions.
invalid-batch-operationThe request for a batch operations is invalid.
deactivated-userThe request tried to perform an operation with a deactivated user.
request-body-too-largeThe uploaded file exceeds the allowed size limit
insufficient-subscription-levelYour team does not have the required subscription level to use this feature. Upgrade to a higher plan.
insufficient-seatsYour team does not have enough remaining seats while trying to invite or activate users.

  • Description: A human-readable explanation for the cause of the error.
    For example:

    • Identity cannot be invited to this team. The identity is already part of the team.
    • The password is too simple
  • Space: An interesting fact about space.
  • Link: A link to the corresponding documentation.
  • Details: Further explanations or hints on fixing the request.
  • ValidationErrors: If the model validation failed, all violations are listed here.

HTTP Status Codes

On each request to our API you get a response with a HTTP status code that indicates if it was successful.

Success Status Codes


GET           200 (OK) including the object(s)
POST          200 (OK) including the newly created object
              202 (Accepted) for batch or background operations
              204 (No content) for business operations without a return value
PUT           200 (OK) including the updated object
DELETE        204 (No content)

Client Failure Status Codes


400 (Bad request)   When the request model is invalid or the operation is not allowed
401 (Unauthorized)  When the requesting user is lacking the necessary permissions for the request
404 (Not found)     When a requested resource does not exist

Pagination

Why pagination?

To obtain data from Q., you have to make calls to the Q. REST API. The response of such a call can lead to a huge data set. To avoid this, Q. smartly paginates the responses so that they are flexible and easier for users to handle.
For example, if you get all the projects, the response could end up with hundreds or thousands of projects and their details which, certainly creates a bad experience for your users. To avoid this, a built-in default limit on the server response is set which varies on which data you are trying to retrieve. The limit is configurable, i.e. you can specify the number of results that you would like to receive from the server.

How to configure the limit?

You can set the number of items that you would like to get from the API via two properties: page and pageSize.

For example, if you want to get 50 users you would end up making a call with the following url: https://myQ.ai/api/v1/users?page=1&pageSize=50.

NameTypeDescription
pageinteger (query)The number of the current page.
pageSizeinteger (query)The number of items on this page.
sortBystring (query)The property to define on which property the items sorted by.
orderstring (query)Define if the items are ordered by ascending or descending.

How to find the total number of results?

When you make a call to retrieve the users from the API, you get the response as well as its headers. The headers of the response contain a property named „x-q-totalitems“, which provides the information about the maximum retrievable results.

Any smart options?

You can sort as well as filter the data that you would like to get from the API by specifying the properties sortby and order.

Filter

Q. uses a subset of the query syntax from ODATA, so most of the common queries will be compatible.

Operator DescriptionExample
eqThe eq operator filters and returns the items which matches the expression.https://api.myq.ai/api/v1/users?filterby=firstname eq 'Neil'
neThe ne operator filters and returns the items which do not match the expression.https://api.myq.ai/api/v1/users?filterby=firstname ne 'Neil'
endswithThe endswith operator filters and returns the items which end with the string.https://api.myq.ai/api/v1/users?filterby=endswith(FirstName, 'Neil' )
startswithThe startswith operator filters and returns the items which start with the string.https://api.myq.ai/api/v1/users?filterby=startswith(FirstName, 'Neil' )
contains.The contains operator filters and returns the items which contain the stringhttps://api.myq.ai/api/v1/users?filterby=substringof('Neil',FirstName)
gtThe gt operator filters and returns the items which are greater than the expression.https://api.myq.ai/api/v1/users?filterby=birthDate gt datetime'2018-04-03T00:00'
ltThe lt operator filters and returns the items which are less than the expression.https://api.myq.ai/api/v1/users?filterby=birthDate lt datetime'2018-04-03T00:00'
leThe le operator filters and returns the items which are less than or equal to the expression.https://api.myq.ai/api/v1/users?filterby=birthDate le datetime'2018-04-03T00:00'
geThe ge operator filters and returns the items which are greater than or equal to the expression.https://api.myq.ai/api/v1/users?filterby=birthDate ge datetime'2018-04-03T00:00'
anyThe any operator iterates through the main entity (Project), executes the condition and returns the filtered list of projects whose any member with the first name Neil.https://api.myq.ai/api/v1/projects?filterby=members/any(p: p\FirstName eq 'Neil')
allThe all operator iterates through the main entity (Project), and returns the filtered list of projects where all members have the first name Neil.https://api.myq.ai/api/v1/projects?filter=members/all(p: p\FristName eq 'Neil')
countThe count operator iterates through the main entity (Project) and returns the filtered list of projects that have less than 10 members.https://api.myq.ai/api/v1/projects?filter=members/count() lt 10
minThe min operator iterates through the time entries of a projects, computes the minimum tracked time on the project and returns the filtered list if the minimum value is greater than one hour.https://api.myq.ai/api/v1/projects/timetrackings?filter=duration/min() gt 3600
maxThe max operator iterates through the time entries of a projects, computes the maximum tracked time on the project and returns the filtered list if the maximum value is equal to one hour.https://api.myq.ai/api/v1/projects/timetrackings?filter=duration/max() eq 3600
sumThe sum operator iterates through the time entries of a project, computes the sum and returns the filtered list of projects where the sum is greater than one hour.https://api.myq.ai/api/v1/projects/timetrackings?filter=duration/sum() gt 3600
averageThe average operator iterates through the time entries of a projects, computes the average and returns the filtered list of projects where the average is greater than one hour.https://api.myq.ai/api/v1/projects/timetrackings?filter=duration/average() gt 3600

Tags

Tags are small strings of additional information that can be added to certain entities in Q. Tags are simple strings with no additional data, but they help to categorize the entities and it is easier to find them via uplink.

Yes No Suggest edit
Last updated on 13. Mai 2018

Authentication

Basics

The Q. API uses the OAuth 2.0 authentication framework to allow external applications to access the team data.

Client Application

A client application needs to be registered in Q. before you can make API calls. Go to the team settings panel in Q. and add a new client application. You will be asked to provide a unique name and a display name for your client. You will receive a client secret in return.

The client secret is only shown while creating the client application! It can be regenerated, but all clients will lose access when their tokens expire.

Client Id

The client_id is used to identify your client application. After you registered a client application in Q., you’ll find the client_id in the list of client applications in the team settings panel.

Client Secret

The client_secret is generated in the client applications section of your Q. It is located next to the client_id in the team settings page. The secret will be used to authenticate your client application when you request a token.

The client secret is only displayed when creating the client application! It can be regenerated, but all clients will lose access when their tokens expire.

Scopes

The OAuth 2.0 authentication flow uses scopes to define which rights are granted to the application by the user. Scopes are sent as a space separated list. The Q. API currently supports these scopes:

  • full_access: read and write access to all resources.
  • offline_access: continued access, issues a refresh token.

Tokens

Access Token

The Access Token is used to authenticate yourself with the API resources. It needs to be included in every request to the Q. API. Each user has to use their own unique Access Token, since such tokens are only valid for the associated user. Also, Access Tokens are valid for one Q. team only. If the client application wants to access multiple teams, it needs to request separate tokens. The token is usually valid for a few days only.

Refresh Token

The Refresh Token is used to get a new Access Token, once it has expired. A Refresh Token only expires when the user manually revokes access for the client application.

Authorization Code

The Authorization Code is a transitory code to retrieve an Access Token. It should not be stored in the client application.

Endpoints

The OAuth endpoints are required to get an Access Token and exchange a Refresh Token for a new Access Token:

Authorization Endpoint: /accounts/authorize may be used to initially retrieve an Authorization Code.

Token Endpoint: /accounts/token may be used to retrieve an Access Token from either an Authorization Code or a Refresh Token.

Authorization Code Flow

Authorization Request

The client constructs the request URI by adding the following parameters to the query string of the authorization endpoint URI using the application/x-www-form-urlencoded format. The client directs the user to the constructed URI using a browser window. The user is prompted to log in, enter her or his username and password, and grant the requested permissions to the client application. If the user is part of several teams in Q., the user needs to select the team before authorizing the application.

Parameter:

  • client_id: The client Id of the client application. Required.
  • redirect_uri: The user will be redirected to a custom URI after the access was granted. Needs to be the same as specified when registering the client application. Required.
  • scope: A space-separated list of API scopes. Required.
  • state: An arbitrary state string that helps the client application to identify the request. Optional.
GET https://myQ.ai/api/v1/accounts/authorize?
    client_id={client_id}&
    response_type=code&
    grant_type=authorization_code&
    redirect_uri={redirect_uri}&
    state={state}&
    scope={scope}

Note: The generated URL needs to be opened in a browser window. the user has to log in to authorize the application.

All query parameters (especially the redirect_uri) may be properly URL-encoded.

User Authentication

The user logs in and grants or revokes the authorization request.

Authorization Response

If the user grants the authorization request, the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query string of the redirection URI using the application/x-www-form-urlencodedformat.

Parameter:

  • redirect_uri: The previously specified redirect URI.
  • code: The authentication code that can be exchanged for a token later.
  • state: The same arbitrary state string that the client application passed in the authorization request earlier.
302 Found
{redirect_uri}?code={code}&state={state}

Access Token Request

If the client application has been successfully authorized, it sends a request with the following parameters in the body to the token endpoint using the application/x-www-form-urlencoded format.

Parameter:

  • code: The code that was received in the previous authorization response. Required.
  • redirect_uri: The previously specified redirect URI. Required.
  • client_id: The client Id of the client application. Required.
  • client_secret: The client secret of the client application. Required.

Note: To build a proper HTTP Authorization header for Basic Access Authentication, you need to encode your client_id and client_secret using Base64, and add it to the Authorization header as follows: Authorization: Basic Base64({AppId}:{AppSecret})

POST https://myQ.ai/api/v1/accounts/token
redirect_uri={redirect_uri}
  &grant_type=authorization_code
  &code={code}
Authorization: Basic Base64({client_id}:{client_secret})

Note: All query parameters (especially the redirect_uri) should be properly URL-encoded.

Access Token Response

If the access token request is valid and authorized, the authorization server issues an Access Token and Refresh Token. If the request failed or is invalid, the authorization server returns an error response.

{
   "access_token""eyJhbGciOiJ...",  // The Access Token used for authorization.
   "token_type""Bearer",            // The token type, usually 'Bearer'.
   "resource""myQ.ai",          // The resource that granted the token.
   "expires_in": 86400,               // The expiration time of the token, in seconds.
   "refresh_token""eyJhbGciOiJ..."// The refresh token to get a new access token, if requested.
}

After receiving the Access Token, you can use it to request resources from the API.

Resource Request

To receive resources from the API, add the Access Token to the Authorization header in the following form:

Authorization: Bearer {access_token}

Note: Access Tokens expires and needs to be refreshed with the Refresh Token.

Examples

Postman

In Postman, open a new Request tab, click on Authorization and select OAuth 2.0 in the dropdown. Click „Get New Access Token“ and fill in the details as shown below. Replace the Callback URL, Client ID, Client Secret and optionally State with your values as described above.

Postman Auth Example
How to receive a token with Postman
Yes No Suggest edit
Last updated on 13. Mai 2018

Examples

Access Token

To use the examples, you need an access token. You can use Postman to obtain the token.
First, open a new tab and select Authorization.  Set the Type to OAuth 2.0 and Add authorization data to the Request URL and click Get New Access Token.

Fill the popup with the information you see in the screenshot below. You have to replace the Client ID and Client Secret with your own data.
After clicking on Request Token a new popup opens. Add your credentials to log in, then select your team and authorize the client.

Postman Auth Example
How to receive a token with Postman

After this step, you will get back the access token that you can use for the examples or in the postman to try out all available endpoints.

Client Examples

The examples are hosted on GitHub.

Some Q. API client examples written in C#
https://github.com/hellohq-io/Q.-API-Examples
0 forks.
1 stars.
0 open issues.
Recent commits:

Yes No Suggest edit
Last updated on 13. Mai 2018

Permissions

Basics

The Q. Permissions allow you to define user access to certain features.
To simplify this, Q. uses a role-based approach that allows a collection of users to be handled by the same collection of permissions.

Permissions

Q. has two permissions: read and manage. With the read permissions of a feature, you have access to all GET endpoints which are related to this feature.
To get access to the POST,PUT, DELETE and Business Operation endpoints, manage permissions for this feature is required.

Features

A feature groups a functional area in Q. to which permissions can be assigned. This simplifies configuration considerably.

With the permission on a function you not only get access to one API endpoint but to all those who belong to this functional area.
Let’s take the project-planning data feature as an example. This will give you access to the project task endpoints. You also get access to the comments endpoints, which allows you to leave comments on project tasks.

Roles

Roles connect users and features. They define which users are authorized to use the functions of the role.
However, there is a difference between standard and project roles. A regular role defines the rights of a user in the entire Q.
Each user must be in exactly one role.
Project roles define the permissions of a user (project member) in a project.

In Q. there is always one admin role and it must always contain at least one user. The users in the admin role have access to all features and can manage permissions for other users.

 

Yes No Suggest edit
Last updated on 13. Mai 2018

Accounts

The registration data used to login with Q. is referred to as an account. An account is associated with a unique email address and password that the user provided when logging in to his or her Q. account.

A user can work in several teams with the same account (and also the same access data). As shown below, the account of [email protected]astronauts.com is part of two teams, Moon and Mars. Tommy uses the same email address and credentials to access both teams. While there is only one account, each team has a user entity associated with the account. A user entity is always team-specific.

 

The account only contains basic account information. More details about the user in each team can be retrieved and edited at the /user endpoints.

Client applications are important for the external login flow used by your applications. These endpoints allow you to administrate the client applications managed by your team. Check out the Authentication guide to learn more about client applications.

Permissions

In order to make permission changes, the user has to be in an administrator role.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 14. Mai 2018

ActivityLogs

Activities in Q. show you which changes have been made to an object and by whom.

Activities can be viewed from the main objects in Q. These are projects, tasks, companies and users.

Permissions

To retrieve the activities, you need read permissions on the master-data feature of the respective entity.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 24. April 2018

Comments

In Q. you can leave comments on all main objects. Comments can help to clarify procedures and questions or provide additional information.
Users can reply on comments, but it is not possible to reply to a reply.
Files can also be attached to each comment and reply.
However, these files are uploaded via the Files-API of Q. The file is automatically linked to the comment, therefore the EntityId, which must be set when the file is uploaded, must contain the comment’s id.

Permissions

To create and edit comments, permissions are required on the respective object to which the comment belongs. These are the read permissions on the master-data features of the respective entity.
In the projects example, this means that the user needs read permissions on the project-master-data feature.
A special case are comments on tasks. The user must be either the task’s assignee or have read permissions on the project-planning-data feature to comment on project tasks.
For entity tasks, read permissions are required on the feature entity-master-data, where entity stands for the respective entity.

When deleting comments, please note that this can only be done by the creator of the comment, but not if the comment has replies.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 13. Mai 2018

Companies

In Q., companies represent all kinds of real companies such as customers, partners, suppliers, competitors, etc. Its main purpose is to present the most important information, contact data and serve as a link to various other types of data such as projects or tasks. Contact information is managed as a separate entity, therefore each company can have multiple contacts.

Company Types

Company types are freely definable and should define what kind of relationship the team has with companies of this type. Common types are customer and supplier. In many cases, a single type is not enough because the company is connected to the team in several ways. In this case, several types can be assigned to each company. Company types are optional, a company does not need to have a type.

Company Number Schemas

In addition to the name of a company, they can be identified by a unique number. Numbers are not necessarily plain digits but can be defined by patterns called number schemas. These are used to generate numbers in user-defined formats and can contain letters, special characters and placeholders for running numbers and date components. For example, a pattern C-yyyy-#### would generate the numbers: C-2018-0000, C-2018-0001 in the year 2018.

Permissions

To receive data or to create companies, read permissions on the company-master-data feature are required.

If the user also has permissions on the feature company-manage-config, then this user is authorized to edit Company Types and Company Number Schemas. Whether the user is allowed to rename the tags of companies also depends on this permission.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 13. Mai 2018

Files

Q. differentiates between the content of a file and its metadata. While you can retrieve the metadata like any other object of the Q. API, the content is available separately on dedicated endpoints. When you upload new files, this distinction is not made and the file is created by a single multipart/form-data POST request with all the metadata and content in the body of the request.

Another convenient feature is that Q. creates different versions of your files. You can update the metadata and content of an existing file without losing the original file. Q. automatically creates a new version in this case and links it to the existing version.

For images, Q. offers special API endpoints that allow you to automatically scale and crop images as needed.

Permissions

Files are linked to a specific entity using an EntityId. This also determines whether the user is allowed to work with these files. Depending on the entity, permissions are required on the corresponding master-data feature. This also applies to the images.

It is also possible to work with files that do not have a link to an entity. These are available for all users in the team who have permissions to the feature files-master-data.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 13. Mai 2018

Permissions

Permissions give you control over the actions that users within a team can perform on the API endpoints. For this case, users are assigned to roles. In fact, every user is in exactly one role which defines their access rights. Teams can have multiple roles.

Certain actions require the special admin permission flag. To ensure every team has at least one administrator, the last user in the admin role cannot be removed from the role.

To change the permissions for a user you can either

  • change the permission set of the current role
  • or move the user to another role

Global roles define the global permissions for a user in Q. Furthermore, project roles allow you to give users special permissions on a project member basis. The permissions regarding project roles are not directly linked to the user, but are assigned in combination with a project membership. You grant a certain set of additional permissions to a user that is assigned to a certain project role in a project. These permissions are only valid for that particular project.

Permissions

Permissions are a highly sensitive area in Q. Therefore only users with administration access or team-manage-config feature can edit permissions.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 13. Mai 2018

Projects

A project is a planned set of interrelated and sometimes dependent tasks that must be executed over a certain period of time, taking certain costs, resources and other constraints into consideration.

Q. helps you organize these interrelated tasks via projects. A project contains all the details for your corresponding plan/design. For example, a project can have a specific type (project type), with various phases (project statuses) and a group of people (team) working on it.

Project Types

A project can be distinguished based on its type, for example design, development, testing, etc.
Creating a project type, Q. helps you define basic statuses for that type (to-do, running and done status). You can assign project roles, project numbering schemes and task bundles to your project type.

Project Roles

Projects of different sizes have different requirements for the organization of people. A small project requires little organizational structure. However, more and more people are involved in large projects and it is important that people understand what is expected of them and what role they should play.

Q. helps you define project roles for each member of your team. Assigning a specific role to a member of your team helps him or her to get a better understanding of his or her tasks and work effectively towards a common goal. Project members of a certain role can also have special permissions on that project. See the project role permissions for more details.

Project Statuses

Each project goes through a lifecycle of events from start to end. Defining the project status is critical to enable your team members to communicate, organize, and work towards a common goal.
Q. helps you to define the lifecycle of a project by the project status. You can create statuses for each phase of your project.

Project Number Schemas

A project can be identified with respect to its project number.
Numbers are not necessarily plain digits but can be defined by patterns called number schemas. These are used to generate the numbers in custom formats and can contain letters, special characters and placeholders for regular numbers and date components. For example, the pattern P-yyyy-#### would generate the numbers: P-2018-0000, P-2018-0001 in the year 2018.

Project Keys

Every project in Q. gets a unique key assigned. The tasks corresponding to this project will receive numbers based on the project key. This helps your users in identifying which project a task is assigned to.

Work Together

In Q., while creating a project, you must specify its type (mandatory). This project type has a set of project statuses, number schemas and project roles which are then assigned to that particular project.
Some of the other configurable options in a project are start date, a due date, customer, time budget, etc.

Permissions

To edit and read projects, you need permissions on the project-master-data feature.

In case a user should be able to edit the environment for projects, i.e. creating and editing Project Roles, Project Statuses, and Project Number Schemas, permissions are required on the project-manage-config feature. This feature also gives the user permission to change the project key.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 13. Mai 2018

Tasks

Tasks are awesome! Q. loves having some work to do. Tasks in Q. are available in two basic types: project tasks and private tasks.
Project tasks are the workload of a project with which you can plan. They follow a status workflow that you can define yourself. They are only „valid“ if the project is in a status of a phase that is „in progress“ and is therefore visible to the project members.
Private tasks are your personal to-dos. They also follow a status workflow that you can define yourself.

Smart task lists

Smart lists are custom filters regarding tasks that filter entities (Users, Projects, Tasks) or their specific properties (Statuses, Types, Tags). Users can share their smart lists by setting the IsShared property to true. When a smart list is shared, other users in the team either subscribe to or unsubscribe from it. Only the user who created the smart list has the permission to edit/delete it. If you are editing a shared smart list, you edit the filter for all users who have subscribed to the smart list.

Task Types

In Q., task types are used to define the task status for all tasks of that type. When you create a custom task type, it must contain at least one ‚to-do‘ status and one ‚done‘ status.

Task Statuses

The task status defines the different steps a task can pass through. A task can only be assigned to one task type. The user can use the standard task statuses in Q. („To Do“ and „Done“) to create a custom status („Stuck“ and „Done“).

Task Lists

A task list is a project-related grouping mechanism for tasks. They can be created manually or by templates. Tasks within a project can be in several lists in the same project. Users can also have private lists, in which case a task list is linked to a user id.

Task List Filters

In Q., you can filter your tasks on a wide variety of options. For example,
• based on task types
• based on timeline (Cont., Weekly and Monthly)
• based on the members of your project team
• based on done status
• based on priority
• based on due date
• based on the input filter query which the user has typed

Task Bundles

The task bundles are sets of predefined tasks and lists that can be added to a project. The user has the option to import a template for a project or assigning it to the project when it is created (if the task bundle is assigned to that particular project type).

Task Templates

In Q., task templates contain basic details to create tasks of it.

Task List Templates

In Q., a task list template is basically a task list that can be added to a project. It contains multiple task templates that will create tasks in the project when added.

Permissions

The permissions needed to work with tasks depend on the task type. Secondly, whether the user is also the task’s assignee.
Regardless of the type of task, a user always has the right to edit a task if he or she is also assigned to the task.

Users who want to see and edit project tasks, but are not assigned, need permissions for the feature project-planning-data.
Only the assignee or owner has access to private tasks.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 24. Juli 2018

Teams

A team in Q. is the group of people you work with. Every project you create and every file you upload is always linked to the team you work in.

When you work with the API, the authentication token determines which team you are currently working in. You can only access projects etc. of this team.

A user can work in several teams with the same account (and thus the same login credentials). As shown below, the account of [email protected] is part of two teams, Moon and Mars. Tommy uses the same email address and credentials to access both teams. While only one account exists, there is one user entity linked to the account in each team. A user entity is always team-specific.

 

A new team

When you create a new team, we set up various defaults. The unique subdomain is assigned automatically. We also create a set of default permissions, roles, task types and status for you so you can get started right away.

Adding users

A team usually consists of several users. When you create a new team via the API, your team is empty. Now you can invite users to your team.

To invite users, create new invitations, which will send an email to the user’s email address. To create an invitation, you need the role you want to assign the users to. For your convenience, we create a set of default roles when you create a new team.

Permissions

Only a user with administrator permissions is allowed to make changes to the team settings.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 13. Mai 2018

TimeTrackings

In Q., times can be tracked on tasks and projects.

Q. offers various possibilities for tracking times.  A timing can be started when you begin an activity and stopped when you end it. It is also easy in Q. to log some times afterwards.

Time entries can be billed to the customer. To do this you have to mark it as billable and as isBilled if it has been billed. From this point on, the time entry can no longer be changed.

TimeTracking Types

The type of a time entry specifies what kind of time is being tracked and what kind of work has been done. Every time entry needs a type, so it is not possible to have a time without a type.
The type break is available as a default in Q. and can be used to track breaks. The time entry of this type are ignored in any evaluations and controlling.

If additional types are required, they can be created in Q.

Tags

Time entries can also be tagged. In contrast to tags on other entities such as companies or tasks, the tags for times are predefined. Here is a list of available ones:

  • Meeting
  • Call
  • Home office
  • On-Site
  • Rework
  • Bug-Fixing
  • Web-Session
  • Preparation
  • Follow-up
  • Night work
  • Billable
  • Customer Project

Q. tries to support the user in selecting the right tags by providing suggestions for suitable tags based on the experience.

Timezone

Q. uses the IANA standard to identify the time zone. The time zone must be set for each tracked time so that Q. can convert the user’s time to UTC.
When time entries are queried, Q. returns the original time as well as the time in UTC. The client is responsible for the conversion to the times in the current viewer’s time zone.

Permissions

Permissions depend on the entity of the tracked time.
To create or receive a time entry for a project you need permissions on the feature project-timetracking. Regarding time entries of a task, however, the permissions depend on the type of the task.
For project tasks, project-planning-data permissions are required. If the user assigned to a task, they are allowed to create and edit time entries on that particular task.
When a time is tracked without an assignment to a certain project or task, no specific permissions are required. The creator of  time entry also has the right to change this time entry at any time.

To edit the time tracking types, the user needs permissions on the feature time-tracking-manage-config. These permissions are also needed to rename the tags of time entries.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 24. Juli 2018

Users

Users are your team members in Q.

A user can be part of several teams with the same account (and therefore the same login credentials). As shown below, the account of [email protected] is part of two teams, Moon and Mars. Tommy uses the same email address and credentials to access both teams. While only one account exists, there is one user entity in each team linked to the account. A user entity is always team-specific.

 

All actions and events in Q. are associated to a user. Almost all entities in Q. have a CreatedBy and UpdatedBy property which refer to a user in the team.

User details

The detailed information of Q. users includes status, contact details and tags. The status of a user is based on whether he or she has accepted the invitation, been activated or deactivated, etc. The contact details and tags are configurable by the user.

Activate/Deactivate

A user in Q. can only be activated/deactivated by users with sufficient permissions to do so. An activated user is available throughout the entire Q. A deactivated user will still be part of the team but cannot be assigned to any project/task and can no longer log in.

Contact Info

A user in Q. can have one or more contact info objects. These types are: Phone, Address, E-Mail, Messenger, Social profiles, etc. The following subtypes are available: Business, Private, Slack, etc.

Permissions

Each user has the permissions to change their own data at any time. However, as soon as the data of other users is visible or changeable, this requires permissions on the feature user-master-data.
To configure the environment for the users in Q. permissions on the feature user-manage-config are needed. This can be used to rename the user’s tags, for example.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 13. Mai 2018
Suggest Edit