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
resumekey | string | Optional string returned by previous call to GetPendingQuestionRequests |
Output
questionrequests | collection [ questionrequest (old)] | A collection of all pending questions in the system. |
resumekey | string | If there are too many requests then a resumekey is returned; you should then call GetPendingQuestionRequests again with this resumekey to get more requests. |
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 | 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 | 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 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. |
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 |