App-Development

The Flexxter AppStore provides the possibility to connect external cloud services to flexxter by displaying unique tiles for these services within a user’s project. The user can browse all apps in the app store and “install” an app within their flexxter account. An installed app will be used for all company’s employees.

In the following we will discuss the general concept of flexxter project apps. These apps generaly get no access to the user’s data except from a hashed version of the project’s id and a hashed version of the project’s root id.

These apps rather focus on enhancing a user’s projects with additional data and services from external apps such as Plakatquadrat, Google Drive, Dropbox etc.

A user can “install” an App within his / her company’s flexxter account. This process will add a new tile to the user’s projects' sidebar:

Every user with a registered account in flexxter can enable developer capabilities for their account. Just go to Settings → Account and activate your Developer Account:

If you cannot see the developer’s tile in your settings, just write an email to developer@flexxter.de so that our team can unlock that feature for you!

For your developer account you have to provide the following information in order to publish apps:

Your company’s name
Your company’s website (you can also link to an app specific page)
A link to your company’s terms of use
A link to your company’s privacy document
An email which we can use to contact you

Each app can be used to display simple data to the user in the app’s tile as well as trigger “actions” that can either transfer data to your backend, open a popup window in flexxter or redirect the user to external urls.

Whenever you create a new app in flexxter, a secret token will be generated. This token will be sent with every request so that you can identify if the request is really coming from flexxter. The token is passed as either a GET or a POST parameter to your server (name: “dev_secret”).

So you can just check if the “dev-secret” was sent with a certain request and compare that one to the secret which is displayed in your developer settings in flexxter.

Installation Workflow

When a user decides to “install” an app on his account, the installation workflow between the external service and flexxter works as follows:

First the user clicks on an install button and accepts your company’s terms of use and your privacy document. After that the user will be redirected to your app’s specific authentication url.

auth_url:

method: GET
sent params: appid, company_secret, (dev_secret)

The appid represents your unique app’s id to help your backend identify the app the user is trying to connect to his account on your service. The company_secret is an anonymous identificator for the company trying to connect to your service. You can use this token to store a link between the user’s account in your service and the user’s flexxter account.

On the page the user is redirected to, you should authenticate the user for your service and generate a short living authentication code that will be used by flexxter to exchange it against a refresh_token as well as an access_token. After generating that token you should redirect the user to https://www.flexxter.de/AddIns/AppInstalled/php and include the following data in your request:

Where company_secret is the same string the flexxter backend transfered to your auth_url, and the app id is your app’s unique id. You also have to send the previously generated code.

If you have not specified an exchange url for your app, this code will be used to authenticate the user for all requests in the future. Yet it is recommended that you follow the OAuth 2.0 workflow and define an exhcange url to exchange the code against a refresh_token and an access_token.

If you specify an exchange_url for your app this endpoint will be used from the flexxter backend to exchange your transferred short living code against a long living refresh_token and a short living access_token. Therefore the flexxter backend will make a request to your exchange_url immediately after the user installed the app.

Your server should return a valid json string which contains the following:

{
  "company_secret": *token*,
  "appid": *appid*,
  "auth_token": *short living auth token*,
  "refresh_token": *long living refresh token*,
  "lifetime": *lifetime of auth_token in seconds
}

Flexxter will then store the auth_token as well as the refresh_token. The refresh_token is used to refresh the auth_token as soon as it expired and the user tries to make a request to the GetState endpoint or to the Action endpoint.

To refresh the expired auth_token, the flexxter backend will send a new request to the exchange_url which contains a parameter “refresh_token” instead of the parameter “exchange_token”. Whenever your exchange endpoint gets the refresh_token as a POST parameter it should use the sent refresh_token to refresh the auth_token and return that one in the response field.

App-State Workflow

Once the app is “installed”, the app’s tile is shown in each of the user’s projects in the sidebar. The tile consists of the following elements:

The content of the tile is structured in “blocks”. Each block can consist of the following elements:

row:
This element contains a “label” and “text” to display data in the given row as shown above
half-row:
This element is nearly the same as the “row” element but it consists of two labels and two text elements that are shown next to one another.
action:
This element is a button containing an icon, a text and an action id. When the user clicks the button the action id, the project’s id and the root project’s id (both hashed) are sent to the external service’s action_url.
tile_list:
This element contains a list of small tiles. Each tile contains of an icon, a text, a color and an action.
Then the user clicks on the tile the project’s id as well as the root project’s id will be sent to the action url along with the specified action-id.

To display the element a request to the app’s get_state_url is automatically performed each time the user opens a project in flexxter.

This endpoint should return a json string containing Block Data which is structured as follows:

{
  "blocks": [
    {
      "type": "row",
      "label": "Informationen",
      "text": "Hier finden Sie Infos."
    },
    {
      "type": "half",
      "first_label": "left row",
      "second_label": "right row",
      "first_text": "left text",
      "second_text": "right text"
    },
    {
      "type": "action",
      "icon": "check",
      "text": "click here",
      "id": "get-user-state-data"
    },
    {
      "type": "tile_list",
      "tiles": [
        {
          "color": "ff0000",
          "text": "test tile",
          "icon": "check",
          "action_id": "test_tile_action"
        }
      ]
    }
  ]
}

Once the user clicks a button (defined by using the action block element) the hashed project’s id and the hashed project’s root id is passed to the action_url specified in the app. Additionaly the id given in the block element is also passed to the url.

The data returned from an action url can contain error and success messages but also definitions for a popup that can again contain actions or an url to redirect the user to.

In the following we will define these action_result_data in more detail:

Definition of action_result_data:

Success Messages

Returning a success message, which is displayed as a toast element to the user

JSON:

{
  "type": "success",
  "text": "Willkommen bei Rocket🚀"
}

Visual:

Error Messages

Returning an error message:

JSON:

Popups

You can also display a popup for the user, in which the user can enter more information.

A popup can consist of the following elements:

Headline (required)
Info text (required)
input fields (text, select)
action buttons

When the user clicks on the action button the data is passed via POST the action url specified in the app. Each element’s id will be transferred as well as the values the user entered in the according element. The action url can again return new action data that result in a popup, an error message or a success message. When the action’s id is left empty (last action in above example), a click on the button will just result in closing the popup.

Additionaly you can use prefill the textboxes with data from the current project. To fill a textbox for example with the project’s address you can use the following JSON:

The following values can be used for the data attribute:

data	Description

data	Description
title	the project’s title
from	the project’s from date formatted like DD.MM.YYYY
to	the project’s to date formatted like DD.MM.YYYY
zip	the project’s zip code
address	the project’s address
email	the logged in user’s email address

Redirect URLs

Another action that you can trigger is a redirect to any url. You just have to provide a redirect url to do so:

Before the redirect takes place, the user will be asked if she wants to be redirected to the given url. Only if the user confirms this, she will be redirected.

The redirect will open a new window with the given url. If the user uses the flexxter app for android or iOS, the url will open in a new browser window.