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:

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

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_invoice_change	Event	Called every time an invoice is changed in Microbizz.	object: The Invoice object that was changed, as JSON
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
xnet	iframe	Interface	The user can add this page to the extranet	person_id: Id of the person accessing the page customer_id: Id of the customer to which this person belongs.

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

Modcode	Hook	Endpoint type	Event / position	Variables

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.

Technical documentation