Skip to main content
Skip table of contents

Question form commands

GetQuestionForms

Return all Question Forms available in the system.

Input

md5sums

collection[md5list]

List of MD5 sums of the questions; used to determine if the question parts should be returned

standardflowcontrol

bool

True to return flowcontrol in a format which isn't mangled for the old app (the very first Android/iOS app)

Output

forms

collection [questionform]

All question forms in the system

Each entry in the md5list is a set with two fields: id and md5sum, e.g.: [{"id":2,"md5sum":"b1dc4b87fca0a715a902a8cfc915e3b3"},{"id":3,"md5sum":"6643b6a04ac28ddb04b7d430cb217cdd"}] .

The md5sum should be the value from the md5sum field in the question form objects that have previously been received. This allows Microbizz to detect if the app has an outdated version of the question form. If Microbizz sees that the app has an up-to-date version then it doesn't send the question parts, as these take up lots of bandwidth.

GetQuestionFormsAsHTML

Return all Question Forms available in the system - as HTML.

Input

md5sums

collection[md5list]

The MD5 sums known, see GetQuestionForms

Output

forms

collection [questionformhtml]

All question forms in the system

No HTML will be transferred for the forms which match the MD5 sums.

GetPendingQuestionRequests

Get all pending question requests in the system.

Input

None

-

-

Output

questionrequests

collection [ questionrequest  (old)]

A collection of all pending questions in the system.

GetPendingQuestionRequestsByTodoID

GetPendingQuestionRequestsByCustomerID

GetPendingQuestionRequestsByToolID

Get all pending question requests for a given task / company / equipment.

Input

todoid

number

Only for the call GetPendingQuestionRequestsByTodoID

customerid

number

Only for the call GetPendingQuestionRequestsByCustomerID

toolid

number

Only for the call GetPendingQuestionRequestsByToolID

Output

questionrequests

collection [ questionrequest (old) ]

A collection of all pending questions for the object.

LockIncompleteAnswer

Lock/unlock an incomplete answer so others can't edit it.

Input

answerid

number

The ID of a saved answer

unlock

bool

1 to unlock, 0 to lock, default is 0

Output

None

-

-

AnswerQuestionRequest

Delivers an answer on a question request.

Input

questionrequestid

number

The ID of the request which is answered.

answer

answer

The answer

answerdate

date

The date when the form was answered

answertime

time

The time when the form was answered

iscomplete

boolean

Set to 1 if the answer is complete, 0 if the answer should be saved for later

longitude

float

The longitude geo location of the phone.

latitude

float

The latitude geo location of the phone.

Output

answerid

number

The ID of the answer, may be 0 if no answer was saved

AnswerQuestionFree

Delivers an answer on a question form, (which wasn't requested).

Input

deliveron

string

Can be one of “customer” or “todo” depending on, on which object the answer is delivered.

deliverid

number

The ID of the relevant object. Either a customer id or a todo id.

answer

answer

The answer

answerdate

date

The date when the form was answered

answertime

time

The time when the form was answered

iscomplete

boolean

Set to 1 if the answer is complete, 0 if the answer should be saved for later

longitude

float

The longitude geo location of the phone.

latitude

float

The latitude geo location of the phone.

Output

answerid

number

The ID of the answer, may be 0 if no answer was saved

GetIncompleteAnswers

Get list of incomplete question form answers that may be edited.

Input

modcode

string

A modcode, eg. "todo" or "customer"

objectid

number

The ID of an object of the above type

answerid

number

An optional answer ID, if set then only get this answer

inclthumbs

bool

If 1 then also include thumbnails of pictures (max 200×200 px)

lock

bool

If 1 then also lock the answer, fail if it cannot be locked; ignored if 'answerid' is not set

Output

incompleteanswers

collection[ formanswer ]

A collection of incomplete answers

GetAllAnswers

Get list of question form answers for a task or company etc. This will only return completed answers, see GetIncompleteAnswers.

Input

modcode

string

A modcode, eg. "todo" or "customer"

objectid

number

The ID of an object of the above type

inclthumbs

bool

If 1 then also include thumbnails of pictures (max 200x200px)

Output

answers

collection[ formanswer ]

A collection of form answers

GetSelectedAnswers

Get list of selected Question Form Answers for a Task or Company etc.
You can choose to combine modcode, objectid and formid or only use formid to get the wanted selection of Question Form Anwers.

This will return a set all Answers. see GetAllAnswers.

Input

modcode

string

A modcode, eg. "todo" or "customer"

objectid

number

The ID of an object of the above type

formid

number

The ID of a Question Form

inclthumbs

bool

If 1 then also include thumbnails of pictures (max 200x200px)

startdate

date

Optional date, only return answers from this date or after

enddate

date

Optional date, only return answers from this date or earlier

Output

answers

collection[ formanswer ]

A collection of form answers

GetAnswer

Get a question form answers. This will only return completed answers, unless the allow_incomplete parameter is included.

Input

id

number

The ID of a form answer

inclthumbs

bool

If 1 then also include thumbnails of pictures (max 200x200px)

inclmedium

bool

If 1 then also include medium size version of pictures

inclfull

bool

If 1 then also include full size version of pictures

allow_incomplete

bool

If 1 the allow incomplete answeers to be retrieved

Output

answer

 formanswer 

answer

The formanswer set returned includes a field "iscomplete" which indicates if the answer is complete or not. 

If inclfull is set then inclmedium and inclthumbs are ignored. If inclmedium is set then inclthumbs is ignored.

The base 64 encoded binary data for the pictures will be included in fields named either thumb or medium or full.

GetAllAnswersByLastChange

Get a collection of question answers changed since a given date and time.

Input

changedate

date

Return all answers changed on or after the provided date.

changetime

time

If this is provided only return customers changed after the provided date and time.

inclthumbs

bool

If 1 then also include thumbnails of pictures (max 200x200px)

Output

answers

collection[formanswer]

The matching answers.

resumekey

string

Sometimes the entire result cannot be returned because it's to large. In that case a resumekey is returned along with the results. Execute the command again with this resumekey to get the remaining results.

CreateUpdatePendingQuestionRequest

Create or update an existing question request.

Input

question_request

Question form commands#questionrequest

question request

Output

answers

collection[formanswer]

The matching answers.

resumekey

string

Sometimes the entire result cannot be returned because it's to large. In that case a resumekey is returned along with the results. Execute the command again with this resumekey to get the remaining results.

ExecuteFormScript

A question form may allow dynamic updating of the values, so that when a user enters a value in field A this causes the value in field B to be updated. This API call handles the logic behind determining which fields to update and how. You should typically call this whenever a value is changed, perhaps when the focus moves away from field A.

Notice that you should not send picture and files and signatures in the answer. These are ignored and would only consume vast amount of bandwidth.

Notice that you should only use this API call if the questionform has the field executescript set.

Notice that static text fields may be updated.

Input

formid

number

The Microbizz ID of a questionform

answers

set

Form values hashed by the question IDs. Don't send pictures and files and signatures.

modcode

string

The type of object that the form is being filled in on, eg. "todo" or "customer"

objectid

number

The Microbizz ID of the object that the form is being filled in on

isservice

bool

Set to 1 if this is called because of equipment service

todoid

int

The ID of a Todo, used if isservice is set, can be 0 if no Todo has been selected

Output

values

set

The new values for those fields that should updated; hashed by the question IDs

errors

set

Errors to display in fields that generated errors; hashed by the question IDs

output

collection[string]

List of messages to display for the user

Forms

The question forms and question objects are also complex types, but due to their complexity they have their own section in this documentation.

A question form is a collection of questions, which contains texts, definition of which interface to use to present the question and flow control ie which question comes next. The completion of a question form results in a set of answers which can be transmitted back to the API.

The questions should be presented in a continous flow, up until a branch presents itself, where the further flow of the question form should only be revealed, when the question have been answered (or if the answer is predefined by a default value).

The flow is guaranteed not to loop under any circumstances.

answer

This describes the anwers form a question form; this is what the app sends to Microbizz.

qfid

number

A reference to the question form for which the answers are given.

answers

set

A set of answers hashed by the question ids i.e. [59:"Yes",62:"Sometimes",29:"15"]

Pictures should be sent as eg. “data:image/jpg;base64,/9j/4AAQS…”, i.e. the same data as is used for inline images in HTML.

Notice that the MIME type part may be replaced with a filename, eg. "data:image2.jpg;base64,/9j/4AAQS...", but in that case the filename may not include comma (,) or semicolon (;) .

formanswer

This describes the answers in a previously filled in question form; this is what Microbizz sends to the app.

id

number

The MB ID of a form answer

title

string

The title of the form itself

alttitle

string

Optional title of the answer, if not set then display title

qfid

number

The MB ID of the question form itself

customerid

number

The MB ID of the relevant company

answerdate

date

The date when the answer was saved

answertime

time

The time when the answer was saved

userid

number

The ID of the user who saved the answer

usertext

string

The name of the user who saved the answer

answers

set

The actual answers, each may hold questionanswerformvalue and other fields, see below

lockuserid

number

The ID of the user who has locked the answer, 0 if not locked

lockusertext

string

The name of the user who has locked the answer

modcode

string

The module/object this formanswer belongs to (customers,todo,tools,person,users)

objectid

number

The ID of the object this formanswer belongs to

parameters

set

The parameter result, the parameter name is the key

Each answer consists of these fields;

question

string

The question that was asked

formvalue

mixed

This is a machine-readable value, ie. decimal numbers use . (full stop) as decimal point; for dates it is in the format YYYY-MM-DD; for a user field it is the ID of a user, etc.

answer

string

The formatted, human-readable value, the text that should be presented to the user when displaying a previously saved form answer; ie. decimal numbers use the decimal point for the language that was selected in MB when the form was saved (this may be different from the language used in the app).

For a user field it is the name of the user. For a picture field it may be 

["category":1, "category2":14, "comment":"Image taken from balcony", "latitude": "0.1", "longitude": "0.2","data": binary...],

thumb

medium

full

string

Either of these may hold a base64 encoded version of the image, if the question is of the type "picture"

originalfilename

string

The filename of the original picture or document, eg. "mycat.jpg" or "annualreport.pdf",  if the question if of the type "picture" or "file"

filetype

string

The filetype of the original picture or document, eg. "jpg" or "pdf", if the question if of the type "picture" or "file"

The purpose of the answer field is to remember the value at the time when the form was saved, in case the answer is an object ID of a kind and the underlying object is changed afterwards.

questionform

This describes a collection of questions.

id

number

Question form ID used to uniquely define this question form.

title

string

The title of the question form

questions

collection [ question ]

The questions in the form

firstquestion

number

A number referencing the first question within the collection of questions.

openanswer

boolean

If this is set to true, then a user can freely submit question forms of this type.

md5sum

string

MD5 sum of the JSON encoded question collection

saveforlater

boolean

If this is set to true, then the form may be saved for later

modules

collection

List of modules that may use the form

executescript

bool

Set to 1 if the API call ExecuteFormScript should be called for this question form

questionformhtml

id

number

Question form ID used to uniquely define this question form.

title

string

The title of the question form

html

string

HTML version of the form

openanswer

boolean

If this is set to true, then a user can freely submit question forms of this type.

md5sum

string

MD5 sum of the HTML

question

This describes a single question within a question form.

id

number

An ID uniquely identifying the question within the question form. Two questions from different question forms can share the same ID.

question

string

The question text

type

number

A number identifying the type of answer expected,  1=text, 2=number, 3=yes/no, see complete list below

options

collection [string]

A collection of possible answers if the type request it.

required

boolean

Indicates if an answer is required.

flow

collection[number]

A collection of references to question id's indicating which question to show next. If the question is an open question, only one id will be present. An id reference of 0 means “end here”

min

number

If the requested answer is a number, this indicates a minimum allowed value.

max

number

If the requested answer is a number, this indicates a maximum allowed value.

default

string

This can provide a default answer, which in that case would already be present in the form (and will affect further flow)

static

boolean

If the field should return a static value, only questions of type "date" and "time"

staticparam

number

A value which adjusts the static value for a "date" field

placeholder

string

Text to display in the input field if the user hasn't yet input anything

fontsize

number

The font size to use for static texts (type:6), HTML sizes, 13 is the normal size

fontstyle

string

The font style for static texts (type:6), text should be bold if this includes the substring "bold", and italic if it includes the substring "italic" 

questionrequest (old)

This describes a request that the user fills in a question form on a given object. This is the old behavior which was only used for getting requests. The new verson below. is also intended for creating requests.

id

number

An id describing this request.

qfid

number

A reference to the question form, we want answered.

objecttype

string

Will be “Customer” if the question form is requested on a customer, or “Todo” if the question is requested on a todo.

objectid

number

A reference to either a customer id or a todo id depending on the object type

reqdate

date

When the question form was requested

title

string

The title of the question form

alttitle

string

The title of the request, usually the same as title

questionrequest

This describes a request that the user fills in a question form on a given object.

id

number

An id describing this request.

modcode

string

describing the type of object its connected to.

object_id

number

id of the object its connected to

qfref

number

Form its connected to.

answer_rule

number

key on an enum of who should answer. The options are 1: Responsible user, 2: Responsible team leader, 3: Responsible team member, 4: Every, 5: Producing employee and 6: Specfic employee.

answer_rule_user_id

number

id of user. used if the Specific employee is set in answer_rule otherwise irrelevant.

reqdate

date

The date for the request. empty string or no date. will give today as a default.

note

string

A note.

feedback_person

boolean

if the feedback should be sent to a person instead of a user.

feedback_to

number

id of user or person. user is default. but if feedback_person is set to true. then this will be for a person.

Question types

The following describes the available question types and how they affect the flow:

Text (type: 1)

Single line text input. For a question of this type, there won't be any options and the flow always contains a single question ID, which is the next question.

The default value and the requested answer would correspond to the entered text.

Number (type:2)

Numeric input in a single line. For a question of this type, there won't be any options and the flow always contains a single question ID, which is the next question. The min and/or max parameter can be provided if the number is to be limited.

The default value and the requested answer would correspond to the entered number.

Yes / No (type:3)

A single yes/no prompt. This type of question will always be required. The flow will always contain two question IDs. The first one indicates the next question if the user answers no, and the second indicates the next question if the user answers yes.

The default value and the requested answer, is 0 for no and 1 for yes.

One of many / Dropdown (type:4)

An interface to select one of several options, usually presented as a dropdown menu / scroller. This type of question will always be required. The options will contain all the options which should be presented to the user, and for each of these options, the flow will contain a question ID indicating the next question if exactly that option is selected.

The default value is the number of the selected option or 0 (or not present) if no option should be preselected (which the interface should also be able to present, even though an option should be selected). The requested answer is the number of the selected option, and here 0 is an invalid answer.

Example:

“options”:[“Apple”, “Grape”, “Orange”], “flow”:[23,24,24]

If the user selects “Grape”, the requested answer would be 2, and the next question would be the one with ID 24.

Several of many (type:5)

A list of checkboxes where one or several options can be checked. If this type of question is required at least one of the boxes must be checked. The options will contain all the possible options which can be checked. The flow will always contain a single question ID, which is the next question.

The default value and the requested answer would be a collection of all the answers checked.

Example:

“options”:[“Apple”, “Grape”, “Orange”]

Checking Apple and Orange, will result in the answer 1,3

Static text (type:6)

This type is special as it is not a question, but just a static text. The text should be displayed to the user, using the entire width of the display. The flow will contain a single question ID, which is the next question.

No answer is expected for this type of question.

Multi-line Text (type: 7)

Multi-line text input. For a question of this type, there won't be any options and the flow always contains a single question ID, which is the next question.

The default value and the requested answer would correspond to the entered text.

One of many / radio group (type: 8)

An interface to select one of several options, usually presented as a list of radio buttons with the option to select one. This type of question will always be required. The options will contain all the options which should be presented to the user, and for each of these options, the flow will contain a question ID indicating the next question if exactly that option is selected.

The default value is the number of the selected option or 0 (or not present) if no option should be preselected. The requested answer is the number of the selected option, and here 0 is an invalid answer.

Example:

"options":["Apple", "Banana", "Orange"], "flow":[65,66,89]

If the user selects “Apple”, the requested answer would be 1, and the next question would be the one with ID 65.

Single checkbox (type:9)

A single checkbox. This type of question will never be required. The flow will always contain two question IDs. The first one indicates the next question if the user doesn't check the checkbox, and the second indicates the next question if the user do check the checkbox.

The default value and the requested answer is 0 for an unchecked box, and 1 for a checked box.

Picture (type:10)

A field for selecting a picture file or taking a picture with the camera.

Signature (type:11)

A field for writing a signature.

Date (type:12)

A date selector.

The static flag may be set, in which case the field should not be editable but should display the current date, or the current date offset by the number of days specified in staticparam.

Time (type:13)

A time selector.

The static flag may be set, in which case the field should not be editable but should display the current time.

User (type:14)

Similar to a dropdown, but used to select a user.

File (type:16)

A field for selecting a file.

“advimg”: IF = “0” THEN show the regular image interface, IF = “1” THEN show the new image interface

“qfcategory”: IF = (null) THEN let the user choose a main category through the dropdown, IF = (any ID) THEN preselect a main category for the user

“qfcategory2”: IF = (null) THEN let the user choose a sub category through the dropdown, IF = (any ID) THEN preselect a sub category for the user

“longlatfrom”: IF = “user” THEN preselect the user location when showing the map, IF = “object” THEN preselect the object (task, customer, equipment location when showing the map

“a

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.