Question form commands
Henrik Bjerregaard
Brian Thorning Jørgensen (Unlicensed)
Adriel Man
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 | 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 |
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 question, answer, formvalue 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
|
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