Quick-start Guides

 This section is intended to give you in a nutshell what you need to build an integration/app with BoondManager.

Basic concepts

Interacting with BoondManager's data without creating an App

If your need is to interact (retrieving, creating, editing, deleting data) with BoondManager data without having any User Interface interaction within BoondManager, then our APIs are the perfect answer!

They enable you to send requests from another infrastructure (your servers, another apps servers, ...) in order to do something in BoondManager (without any manual interaction).

Your service that accesses our API needs to run as a backend service within your infrastructure.

Examples:

  • Push candidate from your website into BoondManager candidate's module
  • External data warehouse which need to extract all your database periodically

If you comply with the previous description then you don't have to worry about the "App creation" sections and you only need to focus on the following articles:

However, if your need is either:

  • to display a User Interface within BoondManager
  • to trigger some Actions when some BoondManagers event occurs (e.g. data creation/edition/deletion)
  • to restrict access to specific APIs, IPs or customers
  • to monetize your development within our store or share it with other customers

then you'll have to create an App as described in the following sections. It can have a UI integrated with BoondManager but it also can, simply, allow you to access more advanced configurations.

What is an App in BoondManager?

An App is the best solution to enhance the user experience with additional features. It is  a self-hosted application that requires a dedicated view within BoondManager. This view is rendered by our application within an Iframe.

It requests our API servers and runs as a backend service within your infrastructure.

Examples:

BoondManager API

Our API is accessible using the domain: https://ui.boondmanager.com/api 

 

 

Now that you're more confortable with this, let's see how you can get started with an BoondManager embedded App.

 

Getting started with BoondManager Apps development

Creating an editor record

Providing an editor record allows to identify the provider of each App in our store.

Administrators only!

To create your own, you will need Administrator access:

Editor Space - Editor Information

All fields are not mandatory, but we recommend that you provide as much information as possible as this information will be visible along your App's details in our store.

Declaring your App

To declare your app, you'll need to:

Mandatory fields

All fields are not mandatory but we need, at least, the following fields:

  • Name
  • App code
  • App url

Once you save, App's Key is generated. It is your App's unique identifier that is needed for the App's installation and subsequent API calls:

 

Having an App icon helps it stand out and be memorable, we recommend that you take advantage of the feature and add one for you App.

 

Here is a detailed description of each field in the form:

Field Description
  Name   The display name of your App. Make it stand out :)
  Title   A short description displayed alongside the name in the Marketplace or My Apps
  Category

  It characterizes your App according to the categories we identified and support. Every option, apart from Others (the default choice) provides your App with additional.

  Check the section dedicated to this topic here.

  Website   Your App's website. Our users will be redirected to this URL
  Testimonies   If you set up a Testimonials page, you can put the URL here
  Terms of service   If you need specific terms of service, you can put a URL to the page here
  App code

  Your App unique code. It can only contain non spaced, un-capitalized letters. It will be provided automatically after saving your App's details.

  App reference   Your App's unique identifier generated after the form is saved
  App url   This field holds the technical URL provided by your developers. It is the root URL that we will use to install, uninstall, configure and call the App.
  App' configuration page

 This field allows to declare that the App has a configuration page. We will create an access to this page by call <App url>/configuration

  Visibility

   An App is private by default i-e only the users belonging to you company can see and use it. Making an App public i-e available outside you organization, we will need to go through a validation process. Please contact us if you have this need.

You can launch the validation process using the Publish button available on your App's page.

Token security for X-Jwt-App authentication

Describes the type of security for X-Jwt-App token:

  • Permanent token: Can be used for private App
  • Temporary token: Mandatory for public App
  API allowed

  This field allows to restrict the APIs accessible by an App's user or someone having access to the authentication token. Setting this field will block any attempt to access unauthorized API even in GOD mode.

  When publishing an App to the public store this field is mandatory.

  Description   A more detailed description of your application that will be displayed to the users
  Price   The fee that you will be charging for using or installing your App. It is displayed to the users.
  Add accesses buttons to the app   Describes the location of you App's access buttons in a view by specifying:
  • the view: the page in which the App's button will be displayed
  • the tab: the tab hosting the button
  • a title: the button's title
  • a function: the endpoint (App's URL/function) that will be called when a user click on the App's button
   Add pages where display the app   Describes the location of you App's access buttons in the iFrame by specifying
  • the view: the page in which the App's button will be displayed
  • the tab: the tab hosting the button
  • a scrolling: indicates if a scrolling bar is displayable on the App's iFrame
  • a height: the height of the App's iFrame in pixels
  • a width: the width of the App's iFrame in percentage
  • a function: the endpoint (App's URL/function) that will be called when the App's iFrame is displayed
  Add events triggering hooks to the app   Describes the trigger that will display your App:
  • the view: the page in which the App's button will be displayed
  • the event: the event that will display your App
  • a function: the endpoint (App's URL/function) that will be called when the event is triggered
Start building

You can see an example of a basic App implementation of a simple Hello App in the Examples. Any App has to provide specific endpoints via a Rest API that answer to HTTP requests. It will allow you to to install, configure and uninstall the App from BoondManager:

  • your-App-URL/install: POST requests from the App's Admin page
  • your-App-URL/configure: a GET request from within the App's iFrame
  • your-App-URL/uninstall: DELETE requests from the App's Admin page

Once you are comfortable with the code from the Hello App, you can start implementing your own. In the next sections, we will go deeper into what parameters each endpoint expects.

 

This application was built to work straight away assuming your server's URL rewriting rules are set up correctly. If needed, check this page for pointers.

Install your App

To install your App, you'll need to:

If you built your App to require a code to be installed, you will be prompted to enter it in a pop-up window. Customers usually require an installation code when their App is public but they still want to restrict access to it.

code_produit

Clicking on Confirm will launch the App’s installation process.

When the installation is done, your BoondManager Admin can activate the App for every user (see the section 'Activating the App' in the Examples)

Installation deep dive

An App’s installation process boils down to providing you with a token that will be used in your App’s API calls. It is a 4 steps process:

  • We make a POST request to your server with the installationCode. It will be empty if none was chosen.
  • We receive a confirmation of success or failure as a response.
  • We make a POST request to your server with the appToken that will be needed for all your future API calls. This token will need to be stored on your infrastructure.
  • We receive a confirmation of success or failure as a response. 

app_install.png

Request's detailed body attribute

  • Every request body has a unique attribute signedRequest:a JSON object, in which the detailed attributes below are encoded.
  • The object expected to returned to our server as a response also needs an encoded signedRequest attribute.

This attribute is the concatenation of a HMAC SHA-256 signature, dot character and a base64url_encoded JSON object. Check this section to 

Here is a snippet in PHP showing how we can decode it:

defined('rest_key') || define('rest_key', your_app_key_here);
        function signedRequest_decode($signed_request) {
            list($encoded_signature, $payload) = explode('.', $signed_request, 2);
            if(base64_url_decode($encoded_signature) == hash_hmac('sha256', $payload, rest_key))
                return $data = json_decode(base64_url_decode($payload), true);
            else
                return false;
        }
        
        function base64_url_decode($input) {return base64_decode(strtr($input, '-_', '+/'));}
      

 

The following showcases the attributes of the successive requests and responses we exchange with your App's server during the installation.

POST Request with the installation code

Attribute Description Type Mandatory
  clientToken  Unique client token string  Yes 
  installationCode

  Installation code.

  Can be empty if your App does not need to check this code.

string Yes
  issuedAt

  Date formatted:

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
string  Yes

Confirmation response

The response is a JSON object with the following attributes:

Attribute Description Type Mandatory
  result   true if success, otherwise false boolean  Yes
  expirationDate

  Date formatted:

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}

  Not used if your App is meant to be always available.

string No 
  errorMessage   Error message if (result = false) string  No 

POST Request with the App token

Attribute Description Type Mandatory
  clientToken   Unique client token string  Yes
  clientName   Client's name string  Yes
  appToken   The App's Token string   Yes
  refreshToken

  The App's Refresh Token.

  Not used if Security Token is permanent.

  string        No
  createdAt

  The App's Token creation date.

  Date formatted:

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}

  Not used if Security Token is permanent.

  string       No
  expiresIn

  The App's Token expiration time in seconds.

  Not used if Security Token is permanent.

  integer       No
  issuedAt 

  Date formatted:

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
string  Yes 
  expirationDate

  Date formatted:

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}

  Not used if your App is meant to be always available.

string  No 

Confirmation response

The response is a JSON object with the following attributes:

Attribute Description Type Mandatory 
  result   true if success, otherwise false boolean Yes
  redirectToConfiguration
  •   true if we must redirect to a Configuration page
  •   false or undefined otherwise
boolean No
  visibility

  App's visibility for managers and resources.

  The values allowed are :

  • allowedManagers : Default value if empty
  • allManagers
  • allowedManagersAndResources
  • allManagersAndResources
string No
  errorMessage   Error message if (result = false)

string

No

Uninstall your App

To uninstall your App, you'll need to:

You will be prompted with a confirmation window. Once you confirmed, uninstalling an App boils down to deleting the App's Token. the process is 2 steps:

  • Requesting your App's host to allow uninstalling the App.
  • Your server confirms the operation.

We will send a DELETE request to the /uninstall end-point. The body is encoded as we did for the installation.

Request for uninstalling the App

Attribute Description Type Mandatory
  clientToken    Unique client token string   Yes
  issuedAt

  Date formatted:

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
string  Yes 

Confirmation response

The response is a JSON object with the following attributes:

Attribute Description Type Mandatory
  result

   The App will be uninstalled whatever the value of result

boolean  Yes
  errorMessage   Error message if (result = false) string  No 
Go further

Please have a look at the following articles to help you go further with your App developments:

  • App's categories
  • App's usage
  • Hello App example
  • Publish your App: we allow customers to publish their Apps on our Marketplace. Theses Apps have to go through a validation process when we review the App. The prerequisite to this step is that the field Allowed API need to be set. To start the validation process use the Publish button next to Install.

 

We hope this article has been helpful to you and we invite you to let us now voting for it (below).

If you have any question, feel free to contact our support.

Boondmanager-Mascot-Desk-lg.png

Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 1 sur 4

Commentaires

0 commentaire

Cet article n'accepte pas de commentaires.