Document toolboxDocument toolbox

Question form commands

GetQuestionForms

Return all Question Forms available in the system.

Input

md5sumscollection[md5list]List of MD5 sums of the questions; used to determine if the question parts should be returned
standardflowcontrolboolTrue to return flowcontrol in a format which isn't mangled for the old app (the very first Android/iOS app)

Output

formscollection [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

md5sumscollection[md5list]The MD5 sums known, see GetQuestionForms

Output

formscollection [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

questionrequestscollection [ 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

todoidnumberOnly for the call GetPendingQuestionRequestsByTodoID
customeridnumberOnly for the call GetPendingQuestionRequestsByCustomerID
toolidnumberOnly for the call GetPendingQuestionRequestsByToolID

Output

questionrequestscollection [ questionrequest (old) ]A collection of all pending questions for the object.

LockIncompleteAnswer

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

Input

answeridnumberThe ID of a saved answer
unlockbool1 to unlock, 0 to lock, default is 0

Output

None--

AnswerQuestionRequest

Delivers an answer on a question request.

Input

questionrequestidnumberThe ID of the request which is answered.
answeranswerThe answer
answerdatedateThe date when the form was answered
answertimetimeThe time when the form was answered
iscompletebooleanSet to 1 if the answer is complete, 0 if the answer should be saved for later
longitudefloatThe longitude geo location of the phone.
latitudefloatThe latitude geo location of the phone.

Output

answeridnumberThe 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

deliveronstringCan be one of “customer” or “todo” depending on, on which object the answer is delivered.
deliveridnumberThe ID of the relevant object. Either a customer id or a todo id.
answeranswerThe answer
answerdatedateThe date when the form was answered
answertimetimeThe time when the form was answered
iscompletebooleanSet to 1 if the answer is complete, 0 if the answer should be saved for later
longitudefloatThe longitude geo location of the phone.
latitudefloatThe latitude geo location of the phone.

Output

answeridnumberThe 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

modcodestringA modcode, eg. "todo" or "customer"
objectidnumberThe ID of an object of the above type
answeridnumberAn optional answer ID, if set then only get this answer
inclthumbsboolIf 1 then also include thumbnails of pictures (max 200×200 px)
lockboolIf 1 then also lock the answer, fail if it cannot be locked; ignored if 'answerid' is not set

Output

incompleteanswerscollection[ 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

modcodestringA modcode, eg. "todo" or "customer"
objectidnumberThe ID of an object of the above type
inclthumbsboolIf 1 then also include thumbnails of pictures (max 200x200px)

Output

answerscollection[ 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

modcodestringA modcode, eg. "todo" or "customer"
objectidnumberThe ID of an object of the above type
formidnumberThe ID of a Question Form
inclthumbsboolIf 1 then also include thumbnails of pictures (max 200x200px)
startdatedateOptional date, only return answers from this date or after
enddatedateOptional date, only return answers from this date or earlier

Output

answerscollection[ 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

idnumberThe ID of a form answer
inclthumbsboolIf 1 then also include thumbnails of pictures (max 200x200px)
inclmediumboolIf 1 then also include medium size version of pictures
inclfullboolIf 1 then also include full size version of pictures
allow_incompleteboolIf 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

changedatedateReturn all answers changed on or after the provided date.
changetimetimeIf this is provided only return customers changed after the provided date and time.
inclthumbsboolIf 1 then also include thumbnails of pictures (max 200x200px)

Output

answerscollection[formanswer]The matching answers.
resumekeystringSometimes 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_requestquestionrequestquestion request

Output

answerscollection[formanswer]The matching answers.
resumekeystringSometimes 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

formidnumberThe Microbizz ID of a questionform
answerssetForm values hashed by the question IDs. Don't send pictures and files and signatures.
modcodestringThe type of object that the form is being filled in on, eg. "todo" or "customer"
objectidnumberThe Microbizz ID of the object that the form is being filled in on

Output

valuessetThe new values for those fields that should updated; hashed by the question IDs
errorssetErrors to display in fields that generated errors; hashed by the question IDs
outputcollection[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.

qfidnumberA reference to the question form for which the answers are given.
answerssetA 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.

idnumberThe MB ID of a form answer
titlestringThe title of the form itself
alttitlestringOptional title of the answer, if not set then display title
qfidnumberThe MB ID of the question form itself
customeridnumberThe MB ID of the relevant company
answerdatedateThe date when the answer was saved
answertimetimeThe time when the answer was saved
useridnumberThe ID of the user who saved the answer
usertextstringThe name of the user who saved the answer
answerssetThe actual answers, each may hold question, answer, formvalue and other fields, see below
lockuseridnumberThe ID of the user who has locked the answer, 0 if not locked
lockusertextstringThe name of the user who has locked the answer
modcodestringThe module/object this formanswer belongs to (customers,todo,tools,person,users)
objectidnumberThe ID of the object this formanswer belongs to
parameterssetThe parameter result, the parameter name is the key

Each answer consists of these fields;

questionstringThe question that was asked
formvaluemixed

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.

answerstring

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

stringEither of these may hold a base64 encoded version of the image, if the question is of the type "picture"
originalfilenamestringThe filename of the original picture or document, eg. "mycat.jpg" or "annualreport.pdf",  if the question if of the type "picture" or "file"
filetypestringThe 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.

idnumberQuestion form ID used to uniquely define this question form.
titlestringThe title of the question form
questionscollection [ question ]The questions in the form
firstquestionnumberA number referencing the first question within the collection of questions.
openanswerbooleanIf this is set to true, then a user can freely submit question forms of this type.
md5sumstringMD5 sum of the JSON encoded question collection
saveforlaterbooleanIf this is set to true, then the form may be saved for later
modulescollectionList of modules that may use the form
executescriptboolSet to 1 if the API call ExecuteFormScript should be called for this question form

questionformhtml

idnumberQuestion form ID used to uniquely define this question form.
titlestringThe title of the question form
htmlstringHTML version of the form
openanswerbooleanIf this is set to true, then a user can freely submit question forms of this type.
md5sumstringMD5 sum of the HTML

question

This describes a single question within a question form.

idnumberAn ID uniquely identifying the question within the question form. Two questions from different question forms can share the same ID.
questionstringThe question text
typenumberA number identifying the type of answer expected,  1=text, 2=number, 3=yes/no, see complete list below
optionscollection [string]A collection of possible answers if the type request it.
requiredbooleanIndicates if an answer is required.
flowcollection[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”
minnumberIf the requested answer is a number, this indicates a minimum allowed value.
maxnumberIf the requested answer is a number, this indicates a maximum allowed value.
defaultstringThis can provide a default answer, which in that case would already be present in the form (and will affect further flow)
staticbooleanIf the field should return a static value, only questions of type "date" and "time"
staticparamnumberA value which adjusts the static value for a "date" field
placeholderstringText to display in the input field if the user hasn't yet input anything
fontsizenumberThe font size to use for static texts (type:6), HTML sizes, 13 is the normal size
fontstylestringThe 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.

idnumberAn id describing this request.
qfidnumberA reference to the question form, we want answered.
objecttypestringWill be “Customer” if the question form is requested on a customer, or “Todo” if the question is requested on a todo.
objectidnumberA reference to either a customer id or a todo id depending on the object type
reqdatedateWhen the question form was requested
titlestringThe title of the question form
alttitlestringThe 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.

idnumberAn id describing this request.
modcodestringdescribing the type of object its connected to.
object_idnumberid of the object its connected to
qfrefnumberForm its connected to.
answer_rulenumber

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_idnumberid of user. used if the Specific employee is set in answer_rule otherwise irrelevant.
reqdatedateThe date for the request. empty string or no date. will give today as a default.
notestringA note.
feedback_personbooleanif the feedback should be sent to a person instead of a user.
feedback_tonumberid 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