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.
customers	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.
customers	menu	Interface	Adds a menu item in the CRM module.
customers	tab	Interface	Adds a tab below every CRM object.	id: The Microbizz ID of the CRM object. customernumber: The customer number
customers	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 0: todo id
todo	event_todo_invoicelines	Event	Called every time the button Send to invoice on a todo object and the todo is invoiced. To be used when no invoice integration has been set up.	todoid: The Microbizz ID of the task.
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.