Ticket Creation From External Webpage

From MochaTicket
Jump to: navigation, search


Contents

Overview

MochaTicket provides functionality for creating tickets from an external web page. This is good if you have an established website with a unique look and feel and you want to allow your users to submit tickets directly from a web page on said website.

Requirements

In the admin Settings page of each site is a 'Mocha Token' that is required when you use this functionality. Every request for ticket creation must include this token or you'll get a '403 Forbidden' response.

Supported

External Ticket Creation is supported in two ways:

  • simple postback with at least a 'success redirect' specified, or
  • ajax call with json specified as the response.

Arguments

The following are the arguments used in the ticket creation


Argument Name Description Notes Required
email Email address the ticket is 'from' Yes
subject Email subject Yes
body-text The description of the issue Yes
dyn-field-1 The first dynamic field see Custom Fields Never
dyn-field-2 The second dynamic field see Custom Fields Never
dyn-field-3 The third dynamic field see Custom Fields Never
token The Mocha Token required for identification Yes
department-id The department that this ticket should be submitted to. Internal Only Departments cannot have tickets added to them through this mechanism. Yes
success-redirect Where to redirect on success Only if json-response is set to false
failure-redirect Where to redirect on failure No, will use success-redirect if this is not specified
json-response Should the response be JSON to enable AJAX? No, will assume false unless this field is set to 'true'


A few things to note:

  • The argument name in the above list is the name value that should be specified in the form or the AJAX request
  • custom fields are never required, even if they're set as required in MochaTicket. It's up to you to make sure the user includes the information.
  • custom fields are always named according to their displayed index on the admin settings page. If you've disabled the first custom field and enabled the second custom field, the second custom field is still referred to as 'dyn-field-2'.

Simple Postback

Simple Postback is enabled by not including the 'json-response' argument, or setting its value to 'false'.

When Simple Postback is enabled the 'success-redirect' argument is required or the server will respond with a 403 Forbidden. If no 'failure-redirect' is specified, then a failure will also redirect to the location specified by the 'success-redirect'.

Ajax with JSON Response

JSON response is enabled by setting the 'json-response' argument to 'true'.

The JSON response will be a javascript object with the following form

   {"status":"SUCCESS",
    "messages":[],
    "redirectTarget":""}

status can have the following 3 values:

  • SUCCESS
  • FAILURE
  • REDIRECT

If no success-redirect is specified, then the value will be SUCCESS/FAILURE. If a success-redirect (and optionally a failure-redirect) is specified, then the status will be REDIRECT, and the redirectTarget will be set based upon the success/failure of the ticket creation. It's strongly recommended that if you specify a success-redirect, you always specify a failure-redirect to help differentiate between success and failure.

messsages is an array of strings, this is helpful for detailing why the request failed.

Errors

Philosophy

Errors that tend to be 'programmer error' such as a missing token or an invalid department specified, will be given HTTP 4xx responses.

Errors that tend to be 'user error' such as a missing Email address, are simply treated as failures. This means a failure redirect if specified, or a status of FAILURE for the JSON, and so forth.

Responses

401 Unauthorized

  • 'Mocha Token' argument is missing or invalid

403 Forbidden

  • The department ID is missing, invalid, or the department is marked as internal only
  • 'json-response' is not set to 'true' and the 'success-redirect' argument is not specified or invalid
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox