Helpdesk forms

A helpdesk project's request types, the forms its customers send: reading, creating, changing, reordering and retiring them, and raising a request of one.

A helpdesk project's request types are the forms its customers send from the portal: what the portal offers, who may send each one, and the fields it asks for. Reading them needs project:view. Changing them needs helpdesk:forms, a permission of its own so that the forms can be looked after without administering the project, and a form anyone may send without an account (submission open) needs helpdesk:publish as well, whether it is being opened or changed while open. Taking a form off the public, or retiring it, needs helpdesk:forms alone. Project administrators hold both. Every change is written to the workspace's audit log, with your agent's name beside the member's.

A form is named by its key (laptop), its name or its id.

GET /projects/{key}/request-types

The forms in portal order, and what the member may do to them. include_archived=true adds retired forms.

{
  "project": "HELP",
  "can_manage": true,
  "can_publish": false,
  "request_types": [
    {
      "id": "0c7e…",
      "key": "laptop",
      "name": "Laptop problem",
      "description": "Something wrong with your laptop",
      "help_text": null,
      "portal_group": "Hardware",
      "hidden": false,
      "submission": "authenticated",
      "ticket_type": "Task",
      "position": 0,
      "archived": false,
      "fields": [
        {"field": "summary", "name": "Summary", "displayed": true, "required": true, "label": null},
        {"field": "description", "name": "Details", "displayed": true, "required": false, "label": null},
        {"field": "priority", "name": "Priority", "displayed": true, "required": false, "label": null}
      ]
    }
  ]
}

GET /projects/{key}/request-types/{request_type}

One form, shaped as an entry above.

POST /projects/{key}/request-types

Adds a form. Answers 201 with it.

Field
key Required. Letters, digits, dashes and underscores, unique in the project.
name Required.
ticket_type Required. The ticket type a request of this form becomes.
description Shown under the name in the portal
help_text Shown above the form
portal_group The heading the portal lists it under
hidden true keeps it out of the portal
submission authenticated (people signed in, the default) or open (anyone, with no account; needs helpdesk:publish)
fields The form's fields in order: each {"field", "displayed", "required", "label"}, where field is summary, description, priority or a custom field's key. The summary is always shown and required. Given, it replaces the form's fields. 
POST /projects/HELP/request-types
Content-Type: application/json

{
  "key": "access",
  "name": "Access request",
  "ticket_type": "Task",
  "portal_group": "Accounts",
  "fields": [
    {"field": "summary", "label": "What do you need access to?"},
    {"field": "description", "required": true}
  ]
}

PATCH /projects/{key}/request-types/{request_type}

Changes a form with any of the fields above; what is left out stays. Making it open, or changing a form that is, answers 403 without helpdesk:publish.

POST /projects/{key}/request-types/order

Sets the portal order: {"order": ["access", "laptop"]}, keys, names or ids. Forms left out follow in their order. Answers with the list, as GET does.

DELETE /projects/{key}/request-types/{request_type}

Retires a form: the portal stops offering it, and requests already raised with it keep it. Answers with the form, archived now true.