Skip to main content
Skip table of contents

Making a Microbizz app

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:

  1. Obtain a set of Microbizz App keys.
  2. Make a program that can make a connection to Microbizz.
  3. 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: 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.

publicidstringHere you should put your application key.
negotiateurlstringThe complete URL to your negotiation script.
returnurlstringThe user will be returned to this URL when finished connecting.
hooksarrayA request of one or more hooks into the Microbizz system.

Hook elements are formed like this:

modcodestringA module code to identify a part of the Microbizz system.
hookstringA hook keyword to identify what you want to "hook".
titlestringA human readable title of your hook.
urlstringThe complete URL to the endpoint at your system which will be servicing this hook.

Example 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:

endpointstringThe URL to be used for communicating with the Microbizz API.
contractstringThe Microbizz contract number for the user who connected.
accesstokenstringAn accesstoken allowing you access into the users Microbizz solution.
challengestringA 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.

ModcodeHookEndpoint typeEvent / positionVariables
calendarmenuInterfaceAdds a menu item in the calendar module.
customerevent_customer_changeEventCalled 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.

customermenuInterfaceAdds a menu item in the CRM module.

customertabInterfaceAdds a tab below every CRM object.

id: The Microbizz ID of the CRM object.

customernumber: The customer number

invoiceevent_edi_changeEventCalled every time an EDI is changed in Microbizzobject: The EDI object that was changed, as JSON
invoiceevent_invoice_line_changeEventCalled every time an invoice line is changed in Microbizz.object: The invoice line object that was changed as JSON.
invoiceevent_edi_line_to_productuseEventCalled 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.

invoiceevent_edi_line_approveEventCalled every time an EDI line is approved.
invoicemenuInterfaceAdds a menu item in the invoice module.
invoicetabInterfaceAdds a tab below every invoice. (Only shown on posted invoices).

id: The Microbizz ID of the invoice.

invoicenumber: The invoice number.

generalevent_file_changeEventCalled whenever a file is changeddocument: The document descriping the file
generalevent_file_createEventCalled whenever a file is createddocument: The document descriping the file
generalevent_note_changeEventCalled whenever a note is changed

message: The message object containing the note

thread: The thread object containing the message

generalevent_note_createEventCalled whenever a note is created

message: The message object containing the note

thread: The thread object containing the message

generalevent_ftp_exportEventCalled when an frp is exported.

ftpPutter: The ftpExport data.

filter: The filter used.

generalevent_form_answerEventCalled 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.

personmenuInterfaceAdds a menu item in the person module.
persontabInterfaceAdds a tab below every person.

id: The Microbizz ID of the person.

idnumber: The ID number of the person.

personevent_person_changeEventCalled whenever a person is changed.

id: person id

object: array of person data.

prodplanmenuInterfaceAdds a menu item in the planning module.object: array of prodplan data
prodplanevent_prodplan_removeEventCalled whenever a production planning is removed.
registrationmenuInterfaceAdds a menu item in the registration module.
registrationevent_registration_createEventCalled when a registration is created.

id: registrationid

registration: array containing the registrations data.

registrationevent_registration_changeEventCalled when a registration is changed.

id: registrationid

registration: array containing the registrations data.

reportmenuInterfaceAdds a menu item in the report module.
salescontract_tabInterfaceAdds a tab below every sales contract.
salesmenuInterfaceAdds a menu item in the sales module.

id: The Microbizz ID of the sales contract.

number: The contract number.

startpageinfoboxInterfaceAdd the option to have an infobox.
startpagemenuInterfaceAdds a menu item in the start module.
supportmenuInterfaceAdds a menu item in the support module.
supporttabInterfaceAdds a tab below every support ticket.

id: The Microbizz ID of the support ticket.

number: The ticket number

todoevent_product_use_createEventCalled every time a new product use is created.object: The productuse object that was added as JSON.
todoevent_product_use_changeEventCalled every time a line of product use is changed in Microbizz.object: The productuse object that was changed as JSON.
todoevent_todo_changeEventCalled 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.

todoevent_todo_invoiceEventCalled every time a todo object is set to be invoiced.

id: invoice id

todomenuInterfaceAdds a menu item in the task module.
todotabInterfaceAdds a tab below every task.

id: The Microbizz ID of the task.

number: The task number.

toolevent_tool_changeEventCalled 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.

toolevent_tool_attach_todoEventCall 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

toolmenuInterfaceAdds a menu item in the equipment module.
tooltabInterfaceAdds a tab below every piece of equipment.

id: The Microbizz ID of the equipment.

serialnumber: The serial number of the equipment.

usersmenuInterfaceAdds a menu item in the user module.
userstabInterfaceAdds a tab below every user object.

id: The internal Microbizz ID of the user displayed.

usercode: The user code of the user displayed.

usersevent_user_checkinEventCalled every time a user checks in on a task or some other objectobject: The checkin object
usersevent_user_checkoutEventCalled every time a user checks outobject: The checkin object
workplanmenuInterfaceAdds a menu item in the workplan module.
workplanevent_workplan_changeEventCalled 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.

appwidgetiframeApp InterfaceCalled 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

sessiontoken:  A ssesion token that may be used for accessing the MIcrobizz API

There is also a "settings" hook for each module:

ModcodeHookEndpoint typeEvent / positionVariables
Any module which provides a General settings menu itemsettingsSettingsAdds 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:

statusbooleanTrue if everything went well, otherwise false.
errorstringIf 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.

JavaScript errors detected

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

If this problem persists, please contact our support.