Akkroo
  1. Support
  2. Developers
  3. API
  4. Endpoints
  5. Events
  6. Questions definition

Definition of Questions

Each Event can contain an array of questions, each defined in an object. Every question must contain an id and type. Other parameters are specific to the type of question. Common parameters are defined below.

Common Parameters

Property Required Type Description
id String
{ "id" : "email" }
The id identifies the question and associates the question with collected data. It is an alpha-numerical Camel Case string with no spaces. When created in Akkroo, it is auto-generated based on the label entered for the question, but can also be set manually.
type String
{ "type" : "email" }
The type parameter identifies the type of question. See the types definitions for allowed values.
label
Except divider
String
{ "label" : "Email Address" }
The label defines the text label for the question — the question you want to ask the user.
required Boolean, Logic Expression Object
{ "required" : true }
The required parameter defines if the question requires a response. It is valid on all question types, except label, note and divider. If not defined, the default is false i.e. not required
displayed Boolean, String, Logic Expression Object
{ "displayed" : { "field1" : "Yes" } }
The displayed parameter defines if the question should be displayed. It is valid on all question types. If not defined, the default value is true i.e. the question is displayed.
In addition to a boolean or logic value, displayed can also be set to "required" to alias the required field
successMessage String
{ "successMessage" : "Well done" }
The success message once shown once an invalid e-mail is corrected
warningMessage String
{ "warningMessage" : "Please don't use a personal email address" }
A warning message shown before the field is interacted with
errorMessages String
{ "errorMessages" : { "required" : "You must enter an email address" } }
Override the App's built in error messages with custom error messages for different types of error. To see a full list of error messages, see the error messages section

Types

Text

Example

{
	"type" : "text",
	"subtype" : "multiline",
	"id" : "postcode",
	"required":true,
	"label" : "Postcode",
	"placeholder" : "SE1 7TJ",
	"autoCapitalize" : "on",
	"autoCorrect" : "off"
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
subtype String
{ "subtype" : "short" }
The subtype of the field
  • normal (default) — single line answer e.g. HTML <input type="text">
  • short — a half-width single line textbox for short answers
  • multiline — multiple line answer e.g. HTML <textarea>
initialVal String
{ "initialVal" : "My name is " }
The initial value the field is set to (not a placeholder)
minLength Integer
{ "minLength" : 5 }
The minimum string length allowed
maxLength Integer
{ "maxLength" : 10 }
The maximum string length allowed
placeholder String
{ "placeholder" : "John Doe" }
A placeholder for the field
pattern String, Object
{ "pattern" : { "pattern":"[a-z]{3}", "flags":"i" } }
A regular expression pattern. Can be specified as a string (no modifiers) or an object, as shown
autoCapitalize String
{ "autoCapitalize" : "words" }
Sets the autoCapitalize field on the form element. In the App this will mean the words are auto-capitalised on all letters ("characters"), all words ("words"), sentences ("on"), or not at all ("off").
autoCorrect String
{ "autoCorrect" : "on" }
Sets the autoCorrect field on the form element. In the App this will mean the words are auto-corrected from the dictionary.

Email

An email address matching the format:

/[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?/i

From regular-expressions.info

Example

{
	"type" : "email",
	"id" : "yourEmail",
	"required":true,
	"label" : "Your E-mail Address",
	"placeholder" : "jennifer@example.com"
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
initialVal String
{ "initialVal" : "example@example.com" }
The initial value the field is set to (not a placeholder)
placeholder String
{ "placeholder" : "example@example.com" }
A placeholder for the field

Date

Example

{
	"type" : "date",
	"id" : "birthDate",
	"required":true,
	"label" : "Your Birthday",
	"initialVal" : "1985-05-31",
	"subtype" : "date",
	"minVal" : "1920-01-01",
	"maxVal" : "2015-12-31"
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
initialVal String
{ "initialVal" : "2013-01-01T12:12:12" }
The initial value the field is set to (not a placeholder)
subtype String
{ "subtype" : "datetime" }
The type of date
  • date — date in format YYYY-MM-DD e.g. '2013-01-01'
  • datetime — date in format YYYY-MM-DDTHH:MM:SS e.g. '2013-01-01T12:12:12'
  • time — time in format HH:MM:SS e.g. '12:12:12'
  • week — Week of year in format YYYY-WWEEK e.g. '2013-W01'
  • month — Month of year in format YYYY-MM e.g. '2013-01'
placeholder String
{ "placeholder" : "Enter a date" }
A placeholder for the field

Example

{
	"type" : "select",
	"id" : "selectColour",
	"required":true,
	"label" : "Please select three colours",
	"options":
		[
			{
				"value" : "green",
				"label" : "Green",
				"initialVal":true
			},
			{
				"label" : "Purple"
			},
			{
				"label" : "Shades of Black",
				"options": [
					{
						"value" : "jet",
						"label" : "Jet Black"
					},
					{
						"label" : "Charcoal",
						"initialVal":true
					}
				]
			}
		],
	"multiSelect" : "true",
	"minLength":3,
	"maxLength":3
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
initialVal String
{ "initialVal" : "Purple" }
The initial value the field is set to
options Array
{ "options" : [ { "label" : "Purple" } ] }
An array of options the user can select from. An 'option' with an 'options' array itself represents an option group. An option object is defined with the following parameters:
  • value — optional, string, the value stored when selected. If not specified, the label is stored.
  • label — required, string, the text displayed for the option
  • initialVal — optional, boolean, defines if selected by default (multiselect only)
multiSelect Boolean
{ "multiSelect" : true }
Specifies if the user can select more than one option. If no value is specified, the default is false.
addEmpty Boolean
{ "addEmpty" : true }
If set to true, clients will add an empty option at the start of a select so the question can be left unanswered. If no value is specified, the default is false.
minLength Integer
{ "minLength" : 5 }
The minimum number of options the user can select. Only available if multiselect is true
maxLength Integer
{ "maxLength" : 10 }
The maximum number of options the user can select. Only available if multiselect is true

Single Checkbox

Example

{
	"type" : "checkbox",
	"id" : "optInMarketing",
	"initialVal":true,
	"label" : "I am happy to receive emails from you"
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
initialVal Boolean
{ "initialVal" : true }
The initial value the field is set to. true is ticked.

Checkbox group

Example

{
	"type" : "checkboxGroup",
	"id" : "pickContinents",
	"label" : "Select two to four continents",
	"options":[
		{
			"id" : "africa",
			"label" : "Africa",
			"initialVal":true
		},
		{
			"id" : "antartica",
			"label" : "Antarctica"
		},
		{
			"id" : "asia",
			"label" : "Asia",
			"initialVal":true
		},
		{
			"id" : "europe",
			"label" : "Europe"
		},
		{
			"id" : "north-america",
			"label" : "North America"
		},
		{
			"id" : "south-america",
			"label" : "South America"
		}
	],
	"minLength":2,
	"maxLength":4
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
options Array
{ "options" : [ { "label" : "Antarctica" } ] }
An array of options the user can select from. An option object is defined with the following parameters:
  • id — optional, string, the value stored when checked. If not specified, the label is stored.
  • label — required, string, the text label displayed next to the checkbox
  • initialVal — optional, boolean, defines if checked by default
minLength Integer
{ "minLength" : 2 }
The minimum number of options the user can select
maxLength Integer
{ "maxLength" : 4 }
The maximum number of options the user can select

Radio group

Example

{
	"type" : "radio",
	"id" : "whichClass",
	"required":true,
	"initialVal" : "business",
	"label" : "Which travel accommodation?",
	"options":
	[
		{
			"id" : "first",
			"label" : "First Class"
		},
		{
			"id" : "business",
			"label" : "Business Class"
		},
		{
			"id" : "standard",
			"label" : "Standard Class"
		}
	]
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
initialVal String
{ "initialVal" : "business" }
The initial value the field is set to
options Array
{ "options" : [ { "label" : "First Class" } ] }
An array of options the user can select from. An option object is defined with the following parameters:
  • id — optional, string, the value stored when selected. If not specified, the label is stored.
  • label — required, string, the text label displayed next to the radio button

Text labels

Example

{
	"type" : "label",
	"id" : "labelOne",
	"label" : "Please complete all the questions in this section",
	"subtype": "header"
}

Parameters

In addition to id, type and label the following parameters are available:

Property Required Type Description
subtype String
{ "subtype" : "heading" }
Select if the label is normal size, or a header (larger)
  • header - show as a larger header, with greater importance
  • normal - default, a normal text label

Number

Example

{
	"type" : "number",
	"id" : "carPrice",
	"required":true,
	"label" : "How much is the car worth (to the closest 1,000)?",
	"initialVal":5000,
	"minVal":0,
	"maxVal":10000,
	"step":1000
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
subtype String
{ "subtype" : "short" }
The subtype of the field
  • normal (default) — single line answer e.g. HTML <input type="text">
  • short — a half-width single line textbox for short answers
  • multiline — multiple line answer e.g. HTML <textarea>
initialVal Integer
{ "initialVal" : 50 }
The initial value the field is set to (not a placeholder)
minVal Integer
{ "minVal" : 10 }
The minimum number
maxVal Integer
{ "maxVal" : 100 }
The maximum number
step Integer
{ "step" : 5 }
The step between values
placeholder String
{ "placeholder" : "Enter a number" }
A placeholder for the field

Telephone

Example

{
	"type" : "tel",
	"id" : "telephoneNumber",
	"required":true,
	"label" : "Your Mobile Number",
	"initialVal" : "07000000000"
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
initialVal String
{ "initialVal" : "07000000000" }
The initial value the field is set to (not a placeholder)
placeholder String
{ "placeholder" : "07000000000" }
A placeholder for the field

URL

A URL matching the pattern:

/^((?:https?://|www\d{0,3}[.]|[a-z0-9.\-]+[.][a-z]{2,4}/)(?:[^\s()<>]+|\(([^\s()<>]+|(\([^\s()<>]+\)))*\))+(?:\(([^\s()<>]+|(\([^\s()<>]+\)))*\)|[^\s`!()\[\]{};:'".,<>?«»“”‘’]))$/i

From Daring Fireball

Example

{
	"type" : "url",
	"id" : "yourWebsite",
	"required":true,
	"label" : "Your Website Address",
	"initialVal" : "http:\/\/www.example.com"
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
initialVal String
{ "initialVal" : "http://akkroo.com" }
The initial value the field is set to (not a placeholder)
placeholder String
{ "placeholder" : "Enter your website" }
A placeholder for the field

Twitter Username

A twitter username, 15 characters or less

Example

{
	"type" : "twitter",
	"id" : "yourTwitterName",
	"initialVal" : "akkroo_app",
	"required":true,
	"label" : "Your Twitter Username"
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
initialVal String
{ "initialVal" : "AkkrooApp" }
The initial value the field is set to (not a placeholder)
placeholder String
{ "placeholder" : "Enter your twitter account name" }
A placeholder for the field

Rating / Stars

A star rating out of 5 or 10

Example

{
	"maxRating": "5",
	"id": "starRating",
	"type": "rating",
	"label": "Star rating",
	"minLabel": "Poor",
	"maxLabel": "Great"
}

Parameters

In addition to the common parameters, the following parameters are available:

Property Required Type Description
maxRating Numeric String
{ "maxRating" : "5" }
The number of stars to display, either 5 or 10
minLabel String
{ "minLabel" : "Poor" }
Text label to be displayed underneath the first star
maxLabel String
{ "maxLabel" : "Great" }
Text label to be displayed underneath the last star

Reserved (Special) IDs

A small number of reserved ‘special’ IDs are used which add or trigger certain Akkroo-specific functionality.

fullName Used when a name is displayed inside the application, split into 'firstName' 'lastName' and 'otherNames' in spreadsheet output. Validation is performed to check two names are entered.
A fullName question is required for events with check-in.
email Used when an email is configured for the event
An email question is required for events with check-in.
mobile Used when a SMS message is configured for the event
emailMe If this field exists, it's value determines if an instant email will be sent out. This field is usually defined as a checkbox.

Error Messages

The errorMessages parameter is an object which defines alternative error messages to those provided in the App by default. This allows you to translate the form to a different language, or just provide more user friendly errors.

Property Description
required
{ "required" : "This field is required" }
An error that occurs when no value is entered on a required field
pattern
{ "pattern" : "Invalid characters" }
An error that occurs when the value provided does not match the provided pattern or built in patterns for specific field types
minLength
{ "minLength" : "Must be greater than 10 characters" }
An error that occurs when the value entered into the form is too short
maxLength
{ "maxLength" : "Must be less than 20 characters" }
An error that occurs when the value entered into the form is too long
minVal
{ "minVal" : "Must be greater than 10" }
An error that occurs the value provided is less than the minimum allowed
maxVal
{ "maxVal" : "Must be less than 20" }
An error that occurs the value provided is greater than the maximum allowed

Logic

Logic works by defining logic expressions for the required and displayed fields. Logic expressions are MongoDB queries on the values already entered into the form.

Questions that are not displayed are not required, so the displayed parameter must be evaluated before the required parameter.

For example, the following example would only be displayed and required if field1 was set to "Yes"

{
	"id":"logicTest",
	"type":"text",
	"label":"Please enter some text if you can see this question",
	"required":true,
	"displayed":{"field1":"Yes"}
}

Logic expressions use the MongoDB query format on the form values collected. For example, on the following collected data

{
	"fullName":"Rebecca Hall",
	"email":"rebecca@mailinator.com"
}

This query would match and return true, so the field would be displayed.

"displayed":{
	"fullName":"Rebecca Hall",
	"email":"/^Rebe/"
}

Implementations of MongoDB querying have been developed by Akkroo and are available for you to use in your application. These implementations do not support all MongoDB operators, but no operators other than those in these libraries would be used by Akkroo.

Custom Logic operators

$displayed

Syntax: {otherQuestion: {"$displayed": <boolean>}}

$displayed determines whether a question is required.

For example, to display the HideMe question only if otherQuestion is not displayed:

{
	"id": "HideMe",
	"type": "text",
	"label": "You can enter text here if otherQuestion is hidden"
	"displayed": {"otherQuestion": {"$displayed": false}}
}

To evaluate the $displayed operator, you need to evaluate the displayed attribute of the specified question.

$required

Syntax: {otherQuestion: {"$required": <boolean>}}

$required determines whether a question is required.

For example, to display the IfRequired question only if otherQuestion is required:

{
	"id": "IfRequired"
	"type": "text",
	"label": "Will only be displayed if otherQuestion is required",
	"displayed": {"otherQuestion": {"$required": true}}
}

To evaluate the $required operator, you need to evaluate the required attribute of the specified question.

MongoDB operators

In addition to these operators, equality can be checked by using “field”:”value”. You can also use regular expressions for the value, as shown in the example above.

Comparison

Logical

Element