Platform-Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== ConnectorMicrobizz class ======

This connector is designed to connect to the Microbizz system, query the API and display information in Microbizz. 

The integration is designed so one can initiate a link between Microbizz and your platform application, so that your application can read and write data to Microbizz and display information in the Microbizz system.

===== Requirements =====

In order to integrate to Microbizz, you need to receive a public id and a secret token which should be added to the global configuration of Platform.

<code php config.php>
$platform_configuration = array(
    'microbizz_public_id' => 'PUBLIC_ID',
    'microbizz_secret_token' => 'SECRET_TOKEN'
);
</code>

Please be careful not to expose your secret token, as that could make others pose as your application.

===== Making an initial link between the systems =====

The link should be established one time, and will yield an access token which can be used to access Microbizz. This access token is valid forever or until cancelled by the Microbizz system, in which case the link should be established again.

In order to establish a link, you should first build a request, which informs Microbizz about what you intent to do. This is done with the ''buildRequest''-function, which takes an URL and a set of permissions as parameters. The URL is the URL to return to in your system after completing the link, while the permissions is what you intent to do.

A request is always expected to exchange data with Microbizz, so you don't need a special permission for that. Otherwise you can build the permissions with the ''buildPermission'' function.

This function takes four parameters. The first two is Microbizz-specific keywords, which is your intentions, the third is the title you want to appear in Microbizz, where you will display your information and the last is the URL which should be called in your application when Microbizz is requesting content.

<code php>
// Request to add a tab to Microbizz titled "App info" which should display under a user.
$permission = ConnectorMicrobizz::buildPermission('user', 'tab', 'App info', 'https://myapplication.com/info_tab.php');
// Build the final request
$request = ConnectorMicrobizz::buildRequest('https://myapplication.com/configuration_finished.php', array($permission));
</code>

To display a button in your interface to establish the link call:

<code php>
ConnectorMicrobizz::renderConnectInterface($request);
</code>

This will display a button which, when pressed, will connect to Microbizz and request to make the link. When finished the user will be returned to your return-URL.

You can check if the link was established by calling:

<code php>
ConnectorMicrobizz::getAccessToken();
</code>

If this function returns anything but false the link is established.

===== Using the Microbizz API =====

When a link is established (which only needs to be done once) you can query the Microbizz API using the ''query''-function which will return an array with three keys.

^status|Returns true if the command succeeded, otherwise false no matter if it was a connection error or an API error.|
^error|An error text if an error occured.|
^result|The result of the executed command as an array.|

Even though the Microbizz API allows for several commands in the same request, this function only accepts one command at a time.

===== Displaying information in Microbizz =====

Microbizz actually just displays your provided URLs in iframes in order to make your content appear as an integrated part of the system.

As the first line (after the initial include) of your scripts add the following line:

<code php>
ConnectorMicrobizz::handleRequest();
</code>

This command will validate the request against Microbizz, protecting against direct access to the URL and it will furthermore activate the instance from where the link was established, so further code will be executed from that instance.

It will also include a Microbizz-friendly stylesheet to help with obtaining a Microbizz look.