Surveys

Introduction

Surveys are used to collect feedback, opinions, or information from Users and Departments.

The possible answer options for a survey are defined in the SurveyAnswerOptions, while the SurveyVotes represent the votes submitted by users.

Surveys can either be targeted to specific Users or Departments or to a targetable entity

Model Definition

Alias

survey

Relations

Key

Relation

Type

Relation Field(s)

user

User

Belongs to

user_id

folder

Folder

Belongs to

folder_id

targetable

Targetable

Morph to

targetable_id, targetable_type

departments

Department

Belongs to many

department_survey

users

User

Belongs to many

survey_user

surveyAnswerOptions

SurveyAnswerOptions

Has many

survey_answer_option.survey_id

surveyVotes

SurveyVotes

Has many

survey_votes.survey_id

currentVote

CurrentVote

Has one

survey_votes.survey_id, survey_votes.department_id, survey_votes.user_id

sharedItems

SharedItems

Has many

Computed Properties

hash - The hashed id of the Survey.
url - The URL to view the Survey.

Funktionen

Restrictable
SoftDeletes
HasTargetable
HasFolder

Targetable Types

chatMessage - A Survey targeted to a ChatMessage.
infoboardPost - A Survey targeted to a InfoboardPost.
manualEntry - A Survey targeted to a ManualEntry.

Survey Types

singleChoice – Users can select only one SurveyAnswerOption.
multipleChoice – Users can select multiple SurveyAnswerOptions.

Show Votes Types

The show_votes_type specifies when the user can view the results of the Survey.

none – Never.
always – Always.
after_vote – After submitting their vote.
after_survey_end – After the Survey has ended.

Appends

The following appends can be applied to all Surveys:

`answer_options_summary`

Adds a node answer_options_summary to the response, which shows the total number of SurveyVotes for each SurveyAnswerOption of the Survey.

Example Response

{
  "answer_options_summary": [
    {
      "survey_answer_option_id": 1,
      "count": 1
    },
    {
      "survey_answer_option_id": 2,
      "count": 2
    }
  ]
}

List

Get a list of all Surveys for the authenticated user.

Definition

GET /api/surveys

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/surveys', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": 1,
    "user_id": 2,
    "folder_id": null,
    "lang_id": "en-US",
    "targetable_id": null,
    "targetable_type": null,
    "type": "singleChoice",
    "active": true,
    "title": "Employee Satisfaction",
    "description": null,
    "show_votes_type": "after_vote",
    "assign_mode": null,
    "user_confirmation_required": false,
    "one_vote_per_department": false,
    "anonymous": false,
    "sort_number": 1,
    "start_date": null,
    "end_date": null,
    "created_at": "2024-07-15 12:00:00",
    "updated_at": "2024-07-15 12:00:00",
    "deleted_at": null,
    "hash": "zn7m24owk63qolxryge8pj05"
  },
  {
    "id": 2,
    "user_id": 2,
    "folder_id": null,
    "lang_id": "en-US",
    "targetable_id": 10,
    "targetable_type": "infoboardPost",
    "type": "multipleChoice",
    "active": true,
    "title": "Product Feedback",
    "description": null,
    "show_votes_type": "always",
    "assign_mode": null,
    "user_confirmation_required": true,
    "one_vote_per_department": false,
    "anonymous": false,
    "sort_number": 2,
    "start_date": null,
    "end_date": null,
    "created_at": "2024-07-15 13:00:00",
    "updated_at": "2024-07-15 13:00:00",
    "deleted_at": null,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  }
]

Show

Show a single Survey by id.

Definition

GET /api/surveys/{id}

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/surveys/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

{
  "id": 1,
  "user_id": 2,
  "folder_id": null,
  "lang_id": "en-US",
  "targetable_id": null,
  "targetable_type": null,
  "type": "singleChoice",
  "active": true,
  "title": "Employee Satisfaction",
  "description": null,
  "show_votes_type": "after_vote",
  "assign_mode": null,
  "user_confirmation_required": false,
  "one_vote_per_department": false,
  "anonymous": false,
  "sort_number": 1,
  "start_date": null,
  "end_date": null,
  "created_at": "2024-07-15 12:00:00",
  "updated_at": "2024-07-15 12:00:00",
  "deleted_at": null,
  "hash": "zn7m24owk63qolxryge8pj05"
}

[Adm.] List

Get a list of all Surveys.

Definition

GET /api/administration/surveys

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/surveys', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": 1,
    "user_id": 2,
    "folder_id": null,
    "lang_id": "en-US",
    "targetable_id": null,
    "targetable_type": null,
    "type": "singleChoice",
    "active": true,
    "title": "Employee Satisfaction",
    "description": null,
    "show_votes_type": "after_vote",
    "assign_mode": null,
    "user_confirmation_required": false,
    "one_vote_per_department": false,
    "anonymous": false,
    "sort_number": 1,
    "start_date": null,
    "end_date": null,
    "created_at": "2024-07-15 12:00:00",
    "updated_at": "2024-07-15 12:00:00",
    "deleted_at": null,
    "hash": "zn7m24owk63qolxryge8pj05"
  },
  {
    "id": 2,
    "user_id": 2,
    "folder_id": null,
    "lang_id": "en-US",
    "targetable_id": 10,
    "targetable_type": "infoboardPost",
    "type": "multipleChoice",
    "active": true,
    "title": "Product Feedback",
    "description": null,
    "show_votes_type": "always",
    "assign_mode": null,
    "user_confirmation_required": true,
    "one_vote_per_department": false,
    "anonymous": false,
    "sort_number": 2,
    "start_date": null,
    "end_date": null,
    "created_at": "2024-07-15 13:00:00",
    "updated_at": "2024-07-15 13:00:00",
    "deleted_at": null,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  }
]

[Adm.] Show

Show a single Survey by id.

Definition

GET /api/administration/surveys/{id}

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/surveys/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

{
  "id": 1,
  "user_id": 2,
  "folder_id": null,
  "lang_id": "en-US",
  "targetable_id": null,
  "targetable_type": null,
  "type": "singleChoice",
  "active": true,
  "title": "Employee Satisfaction",
  "description": null,
  "show_votes_type": "after_vote",
  "assign_mode": null,
  "user_confirmation_required": false,
  "one_vote_per_department": false,
  "anonymous": false,
  "sort_number": 1,
  "start_date": null,
  "end_date": null,
  "created_at": "2024-07-15 12:00:00",
  "updated_at": "2024-07-15 12:00:00",
  "deleted_at": null,
  "hash": "zn7m24owk63qolxryge8pj05"
}

Create

Create a new Survey.

Definition

POST /api/administration/surveys

Request Keys

Key

Type

Default

Description

title *

string

The title of the Survey.

description

string

The description of the Survey.

type *

string

The Type of the Survey.

folder_id

integer

The ID of the folder in which the Survey should be organized in the administration.

active

boolean

false

Controls the visibility of the survey for participants.

show_votes_type

string

none

The Show Votes Type of the Survey.

assign_mode

string

The assign mode of the Survey.

user_ids

array

Users who can participate in the survey.

department_ids

array

Departments who can participate in the survey.

user_confirmation_required

boolean

false

The user must confirm if logged in with a group account. Voting with group accounts is then no longer possible.

one_vote_per_department

boolean

false

Only one vote can be cast per Department.

anonymous

boolean

false

Wether SurveyVotes are shown to other participants.

start_date

datetime

The start date of the Survey.

end_date

datetime

The end day of the Survey.

sort_number

integer

Current highest +1

The index of the Survey related to the Folder.

Keys with * are required.

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/surveys', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'IT Service Improvement',
        'type' => 'multipleChoice',
        'targetable_type' => 'infoboardPost',
        'targetable_id' => 15
    ]
]);

Example Response

{
  "id": 3,
  "user_id": 2,
  "folder_id": null,
  "lang_id": "en-US",
  "targetable_id": "infoboardPost",
  "targetable_type": 15,
  "type": "multipleChoice",
  "active": true,
  "title": "IT Service Improvement",
  "description": null,
  "show_votes_type": "none",
  "assign_mode": null,
  "user_confirmation_required": false,
  "one_vote_per_department": false,
  "anonymous": false,
  "sort_number": 3,
  "start_date": null,
  "end_date": null,
  "created_at": "2024-07-15 14:00:00",
  "updated_at": "2024-07-15 14:00:00",
  "deleted_at": null,
  "hash": "d54q7g6wnj1eylm8k9e0xpz2"
}

Update

Update an existing Survey by id.

If a survey contains SurveyVotes, editing is restricted to only those fields that are still allowed to be changed. Further editing is only possible after a reset of the Survey.

Definition

PUT /api/administration/surveys/{id}

Request Keys

Key

Type

Description

title *

string

The title of the Survey.

description *

string

The description of the Survey.

type *

string

The Type of the Survey.

folder_id

integer

The ID of the folder in which the Survey should be organized in the administration.

active

boolean

Controls the visibility of the survey for participants.

show_votes_type

string

The Show Votes Type of the Survey.

assign_mode

string

The assign mode of the Survey.

user_ids

array

Users who can participate in the survey.

department_ids

array

Departments who can participate in the survey.

user_confirmation_required *

boolean

The user must confirm if logged in with a group account. Voting with group accounts is then no longer possible.

one_vote_per_department *

boolean

Only one vote can be cast per Department.

anonymous *

boolean

Wether SurveyVotes are shown to other participants.

start_date *

datetime

The start date of the Survey.

end_date

datetime

The end day of the Survey.

sort_number

integer

The index of the Survey related to the Folder.

Keys with * can no longer be edited after at least one vote has been submitted.

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/surveys/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'show_votes_type' => 'after_vote',
    ]
]);

Example Response

{
  "id": 3,
  "user_id": 2,
  "folder_id": null,
  "lang_id": "en-US",
  "targetable_id": "infoboardPost",
  "targetable_type": 15,
  "type": "multipleChoice",
  "active": true,
  "title": "IT Service Improvement",
  "description": null,
  "show_votes_type": "after_vote",
  "assign_mode": null,
  "user_confirmation_required": false,
  "one_vote_per_department": false,
  "anonymous": false,
  "sort_number": 3,
  "start_date": null,
  "end_date": null,
  "created_at": "2024-07-15 14:00:00",
  "updated_at": "2024-07-15 14:30:00",
  "deleted_at": null,
  "hash": "d54q7g6wnj1eylm8k9e0xpz2"
}

Reset

Reset an existing Survey by id.

When resetting, all SurveyVotes submitted for this Survey will be deleted.

Definition

PUT /api/administration/surveys/{id}

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/surveys/reset/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

{
  "id": 3,
  "user_id": 2,
  "folder_id": null,
  "lang_id": "en-US",
  "targetable_id": "infoboardPost",
  "targetable_type": 15,
  "type": "multipleChoice",
  "active": true,
  "title": "IT Service Improvement",
  "description": null,
  "show_votes_type": "after_vote",
  "assign_mode": null,
  "user_confirmation_required": false,
  "one_vote_per_department": false,
  "anonymous": false,
  "sort_number": 3,
  "start_date": null,
  "end_date": null,
  "created_at": "2024-07-15 14:00:00",
  "updated_at": "2024-07-15 15:00:00",
  "deleted_at": null,
  "hash": "d54q7g6wnj1eylm8k9e0xpz2"
}

Delete

Delete an existing Survey by id.

Definition

DELETE /api/administration/surveys/{id}

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/administration/surveys/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

{
  "status": "success",
  "data": null
}

PreviousSurveys NextSurveyAnswerOptions

Last updated 1 month ago