Making a Microbizz app
- Michael Sahl
- Adriel Man
- Madrigal Totayo
A Microbizz app is a piece of software which can communicate with Microbizz using their API, display information within Microbizz and get notified if something happens in Microbizz.
In order to make a Microbizz app one needs to go through the following steps:
- Obtain a set of Microbizz App keys.
- Make a program that can make a connection to Microbizz.
- Program one or more endpoints to serve subsequent requests from Microbizz.
Obtaining keys from Microbizz.
You need two keys to make a Microbizz app. An application key and a secret key. These keys can be acquired by contacting Ventu. You should obtain one set of keys for each of your applications.
Connecting to Microbizz.
You need to program two scripts to connect to Microbizz. A request script and a negotiation script.
The request script
The request script is very simple and should just redirect the user to the following URL: https://system.microbizz.dk/appconnect/ using a POST.
This POST should consist of a single field called request which is a JSON structure describing how you want to connect to Microbizz.
| publicid | string | Here you should put your application key. |
|---|---|---|
| negotiateurl | string | The complete URL to your negotiation script. |
| returnurl | string | The user will be returned to this URL when finished connecting. |
| hooks | array | A request of one or more hooks into the Microbizz system. |
Hook elements are formed like this:
| modcode | string | A module code to identify a part of the Microbizz system. |
|---|---|---|
| hook | string | A hook keyword to identify what you want to "hook". |
| title | string | A human readable title of your hook. |
| url | string | The complete URL to the endpoint at your system which will be servicing this hook. |
Example request: https://system.microbizz.dk/appconnect/?request={"publicid":"MY APPLICATION KEY","negotiateurl":"https://MYSERVER/negotiate/","returnurl":"https://MYSERVER/return/", hooks:[{"modcode":"invoice","hook":"menu","title":"My invoice plugin","url":"https://MYSERVER/myplugin/"}]}
The user will be asked to log into a Microbizz solution and on success an access token will be passed to your negotiation script for you to save. This access token will be used to access the users Microbizz solution and therefore should be kept save. The user can disable the token at some point prevent your app access. If this happens a new connection needs to be established.
A connection request will always grant full access to the Microbizz API, so if that is the only thing needed, no hook elements are needed.
The negotiation script
During the connect process your negotiation script will receive a POST consisting of the following fields:
| endpoint | string | The URL to be used for communicating with the Microbizz API. |
|---|---|---|
| contract | string | The Microbizz contract number for the user who connected. |
| accesstoken | string | An accesstoken allowing you access into the users Microbizz solution. |
| challenge | string | A challenge string to prove the identity of your app. |
You should store the first three pieces of information in your application, as this is your access information to Microbizz.
In order to prove the identity of your app, you'll receive a challenge string. In order to solve the challenge, you need to concatenate your secret key to the back of this challenge string and output the SHA1 checksum of the result as the only output of your script. If you doesn't solve the challenge correctly the user will be informed about this and the information received along the challenge will be invalid and cannot be used to access Microbizz.
Example: If your secret app key is SECRETAPPKEY and you receive the challenge 92492AB, you will concatenate this to 92492ABSECRETAPPKEY and calculate the SHA1 checksum of this, which is: 3b71b8a82728aa6cf60f9caf87d48f9ff6558b49, which should be the only output from your script.
Programming endpoints
There are three types of endpoints. Event endpoints, interface endpoints and app interface endpoints. In the chart below you can see every Microbizz hook, the type of endpoint and what parameters are passed to the endpoint.
| Modcode | Hook | Endpoint type | Event / position | Variables |
|---|---|---|---|---|
| calendar | menu | Interface | Adds a menu item in the calendar module. | |
| customer | event_customer_change | Event | Called every time a CRM object is changed in Microbizz. | object: The customer object that was changed as JSON. previousobject: The customer object as it was before the changes. |
| customer | menu | Interface | Adds a menu item in the CRM module. | |
| customer | tab | Interface | Adds a tab below every CRM object. | id: The Microbizz ID of the CRM object. customernumber: The customer number |
| customer | event_person_attach | Event | If a person is attached or detached from a company. trigger this | object: The customerpersonrelation that was changed as JSON. added origin event attached or detached. |
| invoice | event_edi_change | Event | Called every time an EDI is changed in Microbizz | object: The EDI object that was changed, as JSON |
| invoice | event_invoice_line_change | Event | Called every time an invoice line is changed in Microbizz. | object: The invoice line object that was changed as JSON. |
| invoice | event_edi_line_to_productuse | Event | Called every time an EDI line is converted to a product use | ediline: The EDI line object that was converted todoitem: The product use object that was created todo: The todo the line is added to. |
| invoice | event_edi_line_approve | Event | Called every time an EDI line is approved. | |
| invoice | menu | Interface | Adds a menu item in the invoice module. | |
| invoice | tab | Interface | Adds a tab below every invoice. (Only shown on posted invoices). | id: The Microbizz ID of the invoice. invoicenumber: The invoice number. |
| general | event_file_change | Event | Called whenever a file is changed | document: The document descriping the file |
| general | event_file_create | Event | Called whenever a file is created | document: The document descriping the file |
| general | event_note_change | Event | Called whenever a note is changed | message: The message object containing the note thread: The thread object containing the message |
| general | event_note_create | Event | Called whenever a note is created | message: The message object containing the note thread: The thread object containing the message |
| general | event_ftp_export | Event | Called when an frp is exported. | ftpPutter: The ftpExport data. filter: The filter used. |
| general | event_form_answer | Event | Called when a form is answered. | id: The id of the Questionaire object. approved: boolean if form is approved. handle: state of question answer. 1 if first save. answers: Array of the answers. |
| person | menu | Interface | Adds a menu item in the person module. | |
| person | tab | Interface | Adds a tab below every person. | id: The Microbizz ID of the person. idnumber: The ID number of the person. |
| person | event_person_change | Event | Called whenever a person is changed. | id: person id object: array of person data. |
| prodplan | menu | Interface | Adds a menu item in the planning module. | object: array of prodplan data |
| prodplan | event_prodplan_remove | Event | Called whenever a production planning is removed. | |
| registration | menu | Interface | Adds a menu item in the registration module. | |
| registration | event_registration_create | Event | Called when a registration is created. | id: registrationid registration: array containing the registrations data. |
| registration | event_registration_change | Event | Called when a registration is changed. | id: registrationid registration: array containing the registrations data. |
| registration | event_registration_day_change | Event | Called when a worksheet is changed. | dayid: worksheetid uref: userid state: 1-3 (i.e. 'open', 'closed' and 'closed + accepted') |
| report | menu | Interface | Adds a menu item in the report module. | |
| sales | contract_tab | Interface | Adds a tab below every sales contract. | |
| sales | menu | Interface | Adds a menu item in the sales module. | id: The Microbizz ID of the sales contract. number: The contract number. |
| startpage | infobox | Interface | Add the option to have an infobox. | |
| startpage | menu | Interface | Adds a menu item in the start module. | |
| support | menu | Interface | Adds a menu item in the support module. | |
| support | tab | Interface | Adds a tab below every support ticket. | id: The Microbizz ID of the support ticket. number: The ticket number |
| todo | event_product_use_create | Event | Called every time a new product use is created. | object: The productuse object that was added as JSON. |
| todo | event_product_use_change | Event | Called every time a line of product use is changed in Microbizz. | object: The productuse object that was changed as JSON. |
| todo | event_todo_change | Event | Called every time a todo is changed in Microbizz. | object: The todo object that was changed as JSON. previousobject: The todo object as it was before the changes. |
| todo | event_todo_invoice | Event | Called every time the button Send to invoice on a todo object and the todo is invoiced | id: invoice id |
| todo | menu | Interface | Adds a menu item in the task module. | |
| todo | tab | Interface | Adds a tab below every task. | id: The Microbizz ID of the task. number: The task number. |
| tool | event_tool_change | Event | Called every time a tool is changed in Microbizz | object: The tool object that was changed as JSON. previousobject: The tool object as it was before the changes. |
| tool | event_tool_attach_todo | Event | Call whenever a tool is attached to or detached from a task. | object: The tool object action: Either the string "attach" or the string "detach", more possible values may be added later todo: The todo object that was affected |
| tool | event_tool_attach_customer | Event | Call whenever a tool is attached to or detached from a customer. | object: The tool object action: Either the string "attach" or the string "detach", more possible values may be added later customer: The customer object that was affected |
| tool | menu | Interface | Adds a menu item in the equipment module. | |
| tool | tab | Interface | Adds a tab below every piece of equipment. | id: The Microbizz ID of the equipment. serialnumber: The serial number of the equipment. |
| users | menu | Interface | Adds a menu item in the user module. | |
| users | tab | Interface | Adds a tab below every user object. | id: The internal Microbizz ID of the user displayed. usercode: The user code of the user displayed. |
| users | event_user_checkin | Event | Called every time a user checks in on a task or some other object | object: The checkin object |
| users | event_user_checkout | Event | Called every time a user checks out | object: The checkin object |
| workplan | menu | Interface | Adds a menu item in the workplan module. | |
| workplan | event_workplan_change | Event | Called every time a workplan has changed. | object: object as array of current workplan oldobject: object as array of old workplan other: exchange connections for relevant user. |
| appwidget | iframe | App Interface | Called every time the app displays a "column group" that includes this widget | The variables are passed in the GET parameters objecttype: The objecttype of the object where the widget is displayed id: The Microbizz ID of the object |
There is also a "settings" hook for each module:
| Modcode | Hook | Endpoint type | Event / position | Variables |
|---|---|---|---|---|
| Any module which provides a General settings menu item | settings | Settings | Adds an item to the General settings |
Interface endpoint
An interface endpoint is iframed into Microbizz, so the output of your script will be displayed inline in the Microbizz system. All variables are passed as GET variables. In addition to the variables mentioned in the chart above, you'll always receive a variable named sessiontoken which is the sessiontoken of the current Microbizz user. You can use the ValidateSessionToken API command to validate this session token, to ensure that your URL is actually called from the Microbizz system and not spoofed from somewhere else. You should use this call before outputting any information.
Event endpoint
An event endpoint is called by the Microbizz system, and all variables are passed as POST variables. The event endpoint should output a json structure with the following fields:
| status | boolean | True if everything went well, otherwise false. |
|---|---|---|
| error | string | If an error occurred a detailed error message can be relayed in this field. |
If this JSON structure isn't returned, the request is also considered to have failed.
Settings endpoint
An event endpoint is iframed into Microbizz so that the output appears in the General settings of the relevant module.
You have to handle load/save/forms etc yourself. Microbizz doesn't provide a "Save" button.
App interface endpoint
An event endpoint is iframed into the Microbizz App so that the output appears in a "column group". The iframe is added to column groups from within the System module in Microbizz.