Deutsche Version

Back to overview

Markdown Support: API Integration

The plugin has no ticket API of its own. When a thread entry is created, it sets the format if the request carries one, and it can optionally detect Markdown syntax automatically.

Format in the request

The signal handler threadentry.created determines the format in this order:

1. The form field format in $_POST.
2. With Content-Type: application/json, the field format in the JSON body.

Valid values are markdown, html and text (case-insensitive). Any other value becomes html. The plugin then writes the determined format to the format column of the thread entry.

{
  "name": "Max Mustermann",
  "email": "max@example.com",
  "subject": "Ticket with Markdown",
  "message": "## Problem\n\nThe server does **not** respond.",
  "format": "markdown"
}

The plugin reads the text for line break restoration and auto-detection from the fields response, note, message and body (the first non-empty field wins).

osTicket partly strips line breaks when saving. The plugin restores them if the text in $_POST contains line breaks and the saved entry has none.

Auto-detection

With the option Auto-Convert Markdown Syntax, the plugin stores entries as Markdown when the request carries no format in $_POST and the text contains Markdown syntax.

Each pattern counts once, no matter how often it occurs:

The threshold is fixed at 5. A single detected pattern is therefore enough to store the entry as Markdown.

The detection is very sensitive: even a line like - item or a word in *asterisks* counts as Markdown. For API calls, rather send the format field explicitly.

Interplay with API Endpoints

The API Endpoints plugin accepts format on POST /tickets and validates the value. It merges the JSON body into $_POST before the ticket is created. This is how the signal handler of this plugin finds the format.

• For notes through the update function of API Endpoints, the field noteFormat applies. If it is missing, API Endpoints uses markdown.
• The option Require Markdown Plugin of API Endpoints (default: off) rejects format=markdown with an error if Markdown Support is not active. API Endpoints recognizes the plugin by the existence of the class MarkdownThreadEntryBody. The class only exists when Markdown Support is activated and Parsedown has been loaded.
• Use the value markdown in requests. Markdown Support does not know other spellings that API Endpoints accepts.

Emails for API tickets

The plugin converts Markdown to HTML in advance for outgoing emails only for requests with format=markdown in $_POST (see Technical details). This conversion runs when osTicket starts and does not yet see the JSON body of an API request. For API tickets the plugin therefore only sets the format of the stored entry.