HelpDesk Forms
/api/helpdesk/forms/{formId}
Exposes HelpDesk form definitions through the annotation-based WebAPI.
The endpoint stages changes in request-local state. WebAPICore invokes commit once after applying supplied setters, so PATCH requests preserve properties omitted by clients. Ticket-field, action, and status details are not copied into this endpoint; clients resolve them through the canonical HelpDesk settings resources returned by capabilities.
Sections replace as an ordered collection. Conditions are OR-connected blocks, with conditions inside one block connected by AND. Select defaults and condition values must remain JSON encoded select-option strings, for example {"label":"Other","value":"Other"}.
Form DELETE is a hard delete. After a successful DELETE the form identifier is no longer resolvable and a subsequent GET returns 404; deletion does not create an inactive form.
DELETE /api/helpdesk/forms/{formId}
Hard-deletes this form. A subsequent GET of its identifier returns 404.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
formId |
path | string |
yes | form identifier from the URL |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
204 |
— | — | No content. |
Example Request
# Request DELETE /api/helpdesk/forms/<formId> HTTP/1.1 Accept: application/json Authorization: Bearer <access-token> # Response HTTP/1.1 204 No Content
GET /api/helpdesk/forms/{formId}
Exposes HelpDesk form definitions through the annotation-based WebAPI.
The endpoint stages changes in request-local state. WebAPICore invokes commit once after applying supplied setters, so PATCH requests preserve properties omitted by clients. Ticket-field, action, and status details are not copied into this endpoint; clients resolve them through the canonical HelpDesk settings resources returned by capabilities.
Sections replace as an ordered collection. Conditions are OR-connected blocks, with conditions inside one block connected by AND. Select defaults and condition values must remain JSON encoded select-option strings, for example {"label":"Other","value":"Other"}.
Form DELETE is a hard delete. After a successful DELETE the form identifier is no longer resolvable and a subsequent GET returns 404; deletion does not create an inactive form.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
formId |
path | string |
yes | form identifier from the URL |
fields |
query | string |
no | Comma-separated readable properties to include in the JSON response. |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
FormRead |
Successful response. |
Example Request
# Request
GET /api/helpdesk/forms/<formId> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
# Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "string",
"id": "62poawqokc9bkvkvyji3qw5bs",
"iconDataUri": "string",
"submitType": "CREATE_TICKET",
"sections": [
{
"label": "string",
"title": "string",
"fields": [
],
"conditions": [
],
"actions": [
]
}
]
}
PATCH /api/helpdesk/forms/{formId}
Exposes HelpDesk form definitions through the annotation-based WebAPI.
The endpoint stages changes in request-local state. WebAPICore invokes commit once after applying supplied setters, so PATCH requests preserve properties omitted by clients. Ticket-field, action, and status details are not copied into this endpoint; clients resolve them through the canonical HelpDesk settings resources returned by capabilities.
Sections replace as an ordered collection. Conditions are OR-connected blocks, with conditions inside one block connected by AND. Select defaults and condition values must remain JSON encoded select-option strings, for example {"label":"Other","value":"Other"}.
Form DELETE is a hard delete. After a successful DELETE the form identifier is no longer resolvable and a subsequent GET returns 404; deletion does not create an inactive form.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
formId |
path | string |
yes | form identifier from the URL |
Request Body
| Content Type | Schema | Required | Description |
|---|---|---|---|
application/json |
FormUpdate |
yes | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
FormRead |
Successful response. |
Example Request
# Request
PATCH /api/helpdesk/forms/<formId> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json
{
"name": "string",
"id": "am52uxnhqynv57o50ps1cqrfp",
"iconDataUri": "string",
"submitType": "CREATE_TICKET",
"sections": [
{
"label": "string",
"title": "string",
"fields": [
],
"conditions": [
],
"actions": [
]
}
]
}
# Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "string",
"id": "62poawqokc9bkvkvyji3qw5bs",
"iconDataUri": "string",
"submitType": "CREATE_TICKET",
"sections": [
{
"label": "string",
"title": "string",
"fields": [
],
"conditions": [
],
"actions": [
]
}
]
}
PUT /api/helpdesk/forms/{formId}
Exposes HelpDesk form definitions through the annotation-based WebAPI.
The endpoint stages changes in request-local state. WebAPICore invokes commit once after applying supplied setters, so PATCH requests preserve properties omitted by clients. Ticket-field, action, and status details are not copied into this endpoint; clients resolve them through the canonical HelpDesk settings resources returned by capabilities.
Sections replace as an ordered collection. Conditions are OR-connected blocks, with conditions inside one block connected by AND. Select defaults and condition values must remain JSON encoded select-option strings, for example {"label":"Other","value":"Other"}.
Form DELETE is a hard delete. After a successful DELETE the form identifier is no longer resolvable and a subsequent GET returns 404; deletion does not create an inactive form.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
formId |
path | string |
yes | form identifier from the URL |
Request Body
| Content Type | Schema | Required | Description |
|---|---|---|---|
application/json |
FormUpdate |
yes | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
FormRead |
Successful response. |
Example Request
# Request
PUT /api/helpdesk/forms/<formId> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json
{
"name": "string",
"id": "am52uxnhqynv57o50ps1cqrfp",
"iconDataUri": "string",
"submitType": "CREATE_TICKET",
"sections": [
{
"label": "string",
"title": "string",
"fields": [
],
"conditions": [
],
"actions": [
]
}
]
}
# Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "string",
"id": "62poawqokc9bkvkvyji3qw5bs",
"iconDataUri": "string",
"submitType": "CREATE_TICKET",
"sections": [
{
"label": "string",
"title": "string",
"fields": [
],
"conditions": [
],
"actions": [
]
}
]
}
Common Error Responses
The status codes 400, 403, 404, 405, 406, 409, 413, 415, and 500 use the same ApiError JSON error format:
{
"status": 404,
"code": "route_not_found",
"message": "The requested API route does not exist.",
"details": []
}
Schemas
Request and response schemas used on this page.
FormRead
| Property | Type | Required | Description |
|---|---|---|---|
name |
string |
no |
Returns form name. |
id |
string |
no |
Returns stable form identifier. |
iconDataUri |
string |
no |
Returns form icon as a base64 data URI. Persisted icons are materialized lazily when this getter is serialized; use |
submitType |
string [CREATE_TICKET, APPLY_ACTION, NOTIFY_TASK_PLANNER] |
no |
Returns form submit behavior. |
sections |
array<FormSectionDefinition> |
no |
Returns ordered sections, including fields, conditions, and submit actions. |
activated |
boolean |
no |
Returns whether form is active. |
useFormLogo |
boolean |
no |
Returns whether form logo is used on the start page. |
parentFolderId |
string |
no |
Returns containing folder identifier. |
showOnStartPage |
boolean |
no |
Returns whether form is shown on the start page. |
maxAttachmentSizeMb |
integer (int32) |
no |
Returns maximum attachment size. |
startPageLinkName |
string |
no |
Returns optional start-page link name. |
startPageLinkDescription |
string |
no |
Returns optional start-page link description. |
submitButtonLabel |
string |
no |
Returns optional custom submit-button label. |
linkPresetFieldKeys |
array<string> |
no |
Returns field keys accepted as URL preset parameters. |
title |
string |
no |
Returns optional form title. |
FormSectionDefinition
| Property | Type | Required | Description |
|---|---|---|---|
label |
string |
no | — |
title |
string |
no | — |
fields |
array<FormFieldDefinition> |
no | — |
conditions |
array<FormConditionBlockDefinition> |
no | — |
actions |
array<FormSubmitActionDefinition> |
no | — |
FormFieldDefinition
| Property | Type | Required | Description |
|---|---|---|---|
visibility |
string [Normal, ReadOnly, Hidden] |
no | — |
defaultValue |
string |
no | — |
selectOptions |
array<string> |
no | — |
values |
object |
no | — |
imageDataUri |
string |
no | — |
label |
string |
no | — |
selectFilter |
string |
no | — |
mandatory |
boolean |
no | — |
labelSetting |
string [SHOW, HIDE, KEEP_SPACE] |
no | — |
customDefaultValue |
boolean |
no | — |
placeholder |
string |
no | — |
fieldType |
string [Ticket, TicketAttribute, Standard, Email, Ui] |
no | — |
key |
string |
no | — |
fieldDataType |
string |
no | — |
includeLabelInInquiry |
boolean |
no | — |
applyToTicketText |
boolean |
no | — |
FormConditionBlockDefinition
| Property | Type | Required | Description |
|---|---|---|---|
conditions |
array<FormConditionDefinition> |
no | — |
FormConditionDefinition
| Property | Type | Required | Description |
|---|---|---|---|
fieldKey |
string |
no | — |
forTicketValue |
boolean |
no | — |
value |
string |
no | — |
operator |
string [EQUALS, EQUALS_NOT, EQUALS_IGNORECASE, IS_OR_IS_BELOW, CONTAINS, CONTAINS_NOT, ENDSWITH, STARTSWITH, IS_NOT_EMPTY, GREATER_OR_EQUAL, GREATER_THAN, LESS_OR_EQUAL, LESS_THAN] |
no | — |
FormSubmitActionDefinition
| Property | Type | Required | Description |
|---|---|---|---|
actionId |
integer (int32) |
no | — |
type |
integer (int32) |
no | — |
afterExecutionText |
string |
no | — |
ApiError
| Property | Type | Required | Description |
|---|---|---|---|
status |
integer (int32) |
yes | — |
code |
string |
yes | — |
message |
string |
yes | — |
details |
array<object> |
no | — |
FormUpdate
| Property | Type | Required | Description |
|---|---|---|---|
name |
string |
no |
Stages a form name change. The manager validates uniqueness within the target folder. |
id |
string |
no |
Accepts the identifier emitted by a GET response so complete form representations can be sent back unchanged. The URL-selected identifier remains authoritative. |
iconDataUri |
string |
no |
Stages form icon replacement. |
submitType |
string [CREATE_TICKET, APPLY_ACTION, NOTIFY_TASK_PLANNER] |
no |
Stages form submit behavior. |
sections |
array<FormSectionDefinition> |
no |
Replaces the complete ordered section collection. |
activated |
boolean |
no |
Stages active-state change. |
useFormLogo |
boolean |
no |
Stages form-logo usage. |
parentFolderId |
string |
no |
Stages a move to another existing folder. |
showOnStartPage |
boolean |
no |
Stages start-page visibility. |
maxAttachmentSizeMb |
integer (int32) |
no |
Stages maximum attachment size. |
startPageLinkName |
string |
no |
Stages start-page link name. |
startPageLinkDescription |
string |
no |
Stages start-page link description. |
submitButtonLabel |
string |
no |
Stages custom submit-button label. |
linkPresetFieldKeys |
array<string> |
no |
Replaces field keys accepted as URL preset parameters. |
title |
string |
no |
Stages a form title change. |