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.

Traits

• 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

PHP

$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

PHP

$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

PHP

$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

PHP

$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	Whether 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

PHP

$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	Whether 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

PHP

$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

PHP

$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

PHP

$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
}