NAV Navbar

WHAT IS FLOWFACT?

FLOWFACT is a platform-product which provides software as a service (saas) to the customer.

The goal of FLOWFACT is to provide software which enables the customer to automate his marketing and sales process by providing different applications that support those processes.

The variety of applications will grow continously and provide different solutions that help the customer to improve his marketing and sales tasks.

To get the best experience using the product, it might be necessary to customize the product itself or applications which are part of the core- or extension-features.

Therefore, this technical guide should provide you with all informations needed for customizing the product as a whole or parts of it.

The Core Structure of FLOWFACT

As already mentioned, FLOWFACT is a platform-based solution, which means that the product consists of multiple apps that are either written by the FLOWFACT-Team or authorized partners.

Basic Overview

The biggest part in this structure is taken by the schemas that work as a blueprint for a specific set of entities. Schemas can also be part of a schema-group which work as a top-level identifier for a specific schema-set. Right now there are no must-have fields that can be defined in a schema-group so you can understand a schema-group as a folder for schemas which makes categorzing schemas possible. Schema-groups also enable the Search-API to iterate through multiple schemas at the same time. A good example of schema-groups can be "estates" for schemas like "house_purchase" "house_rent" and other similar schemas that represent an estate-entity. All functionalities in the platform are built around those schemas and/or schema-groups.

Flowfact provides some basic editions that contain basic schemas, flywheels and kanbans.

Those informations can all be customized to fit the specific needs of the customer.

To understand how this works, we’ll take a look into how the structure looks like in an image:

Wasn't able to load picture

As you can see in the picture, every part of the core-structure (entities,views,layout,integrations,kanban,flywheel) are dependent of the schema which represents the data-structure on a technical level.

Since there are much new words and a complex structure in this screen let's take a look at them with a more structured point of view.

Data-Structure

Wasn't able to load picture

The Data-Structure of FLOWFACT consists of schema-groups,schemas and entities. The Data-Structure defines which Fields and Values are present in the System and how the values should be read.

View-Structure

Wasn't able to load picture

The View-Structure of FLOWFACT consists of views and widgets. This section defines how a schema should be displayed in the client. You can define which fields should be shown in the client, how they should be shown and you can create different views for a schema. For example you can create card-,list-,default-,mapviews and many more.

Automation-Structure

Wasn't able to load picture

The Automation-Structure of FLOWFACT consists of Kanbans and Flywheels. This section is created with an important purpose that FLOWFACT tries to accomplish: Mapping the Customer Journey of multiple Target Groups and try to automate as much of that journey as possible. Therefore it would be a great help to understand the logic of Flywheels and Kanbans.

How to use the FLOWFACT-API

What is an API?

API means „Application Programming Interface“ and it provides an interface that enables a developer to use specified resources to interact with the Software that the System provides.

What is needed to use the FLOWFACT-API

If you want to customize a FLOWFACT-system, you need authenticate against the services that you want to use. For that you’ll need a cognito-token. To get this token, you need to make an API-Call where you have to provide the userplatform-token of the account.

Get the Userplatform-token of an account

We prepared some images to guide you through the necessary steps in the software to get your userplatform-token:

First of all you have to navigate to the portals-settings in your account.

Wasn't able to load picture

Wasn't able to load picture

When you are in your portals-settings you have to go to your wordpress-connector (if you don't have one you need to create it!)

Wasn't able to load picture

Wasn't able to load picture

The userplatform-token is present in the top-right section of your wordpress-connector.

Wasn't able to load picture

Get a Token to authenticate against the FLOWFACT-API

The following call allows to pass a userplatform token and to create a cognitotoken. This token is valid for approx. 30 min and must be refreshed.

HTTP Request

Resource

GET https://api.production.cloudios.flowfact-prod.cloud/admin-token-service /stable/public/adminUser/authenticate

Header Type Default Description
token String - The userplatform-token that you got in the above step

Example Header:

"token":" d65e8119-6577-4806-XXXX-XXXXXXXXXXXX"

Example Response (shortened because it is long):

"eyJraWQiOiIrSjVYZHE3ejRTb ... CbKVwJUfzP7aa OqS9fijNgAOlREmldvigKhsLuw"

It is used for authentication against all services that are provided by FLOWFACT.

API-Responses

The FLOWFACT-API usually sends response to API-calls as JSON-Objects or with a String. The response is also shown in the right side.

If you don't know what JSON-Objects are or need to lookup the syntax you can make use of the Wikipedia-Article

Where to find the API-Calls

We created a repository which provides you with the most recent Postman-Collection that represents the most used-api calls. The Calls are filled with placeholders that are marked by curly braces. Example: {{cognitoToken}} means that the cognitoToken should replace this placeholder.

To be able to read this Collection you need to install Postman on your device (It is free!). You can Download Postman easily: Postman-API-Client

The Collection can be downloaded from our open GitHub-repository:

Repository-Link

When you have Downloaded the JSON-File for Postman you simply need to import the JSON into your Postman to see the FLOWFACT-API Postman-Collection.

How to Import The Collection

The import of the Postman-Collection into Postman is pretty simple. The Images below offer a Step-by-Step Guide to import the Collection into your Postman-API-Client:

  1. Click on the Import-Button in your Postman-Client Wasn't able to load picture

  2. Click on Choose Files to choose a Collection that you want to Import. Wasn't able to load picture

  3. Choose the FLOWFACT-API Postman-Collection and Open it. Wasn't able to load picture

If you can't find the right API-Call

If there are functionalities that you may want to use with the API that are not listed in the collection simply send an email to feedback@flowfact.de and we will look into your problem and will offer the right solution for your use-case.

Customizing FLOWFACT

Create a custom edition for FLOWFACT

First of all it is necessary to understand what an edition is. An edition consists of different things that define a part of your workspace. For example the Commercial edition contains the schemas and views that are needed to create commercial estates and use them in flowfact correctly. Each edition is a bundle.

Let's create a custom edition as a sample together to get an understanding of how it works. In this case, let's create a custom edition for a pet-shop.

First of all we create the folder that represents the edition. Name the folder like the edition your going to create. In our case "petshop". To declare that this folder is a flowfact-edition we need to create an empty ".bundle" file. This file indicates that this folder is an edition and doesn't need to have any content.

After that we create a details.json file in the folder. The details.json file defines who the creator of the edition is, how the edition is named and contains a description for the edition.

The pet-shop will sell pets and foods for them. Since we want to track our customer-relation for the things that we sell we'll need to create a bom.json. In this file we define that this edition requires that the edition "CRM" is installed. We also define that customers will be able to install that edition manually.

After that we create a folder which is called "schemas". This folder will contain the pets and the food as schemas that we have in our system. For each schema we create a folder which is named like the schema we want to create. In our case we create a folder "pets" and a folder "pet_foods" more about how a schema is structured can be found here: structure of schemas.

Know the definition of the schemas can start. First of all let's define which values the pets that we want to create in the system will have.

We need to think about which fields we need, how we want to name them, and which value type they should store. For our pets it will look like this :

Fieldname Type Description internal name
ID text The id of the entity identifier
Name text Name of the pet name
Type List For example dog,cat,mouse type
Age Number Age of the pet age
Birthdate Date Birthdate of the pet birthdate
Size Unit - Number Size of the pet size
Healthcheck Checkbox If the pet is healthchecked healthcheck
NewOwner Schema-Link to contact The new Owner of the pet newowner
Sold Checkbox If the pet is already sold sold
Picture Media - Image Picture of the pet picture
Youtube Link Link For some pets we will make a short video to present them. ytlink
Documents Media - Documents Things like selling contract documents
Description Textarea Detailed description to the pet description

The internal name is necessary to define in a way that is good to remember, because we need it to define how our entities will be displayed in the client.

The schema.json can be found here.

As for the Food that we're going to sell as a petshop we create a "pet_foods" folder and in there a schema.json for it with the following values:

Fieldname Type Description internal name
ID text The id of the entity identifier
Name text Name of the pet food name
Type List For example dog,cat,mouse - food type
Expiration Date Date Expiration Date of the food expiration
Price Unit - Number Price of the food price
Stock Checkbox If the food is in stock stock
Deliverer Schema-Link to contact The deliverer deliverer
Picture Media - Image Picture of the pet picture
Purchase Link Link Link to purchase more of the food. pclink
Description Textarea Detailed description to the pet description

The schema.json can be found here.

So we created the schemas for our pets and the food that we're going to sell. But at the moment, we have no way defined of how we want to display the entities that will be created based on those schemas. To create a possibility that the entities can be displayed in the client, we need to create views that the client uses to display the data.

There are 4 different Views that the client currently uses to display data:

You should at least create those 4 Views for every schema in your edition that you want to display in the client.

To keep our example short at this point i'll link how the view.json files for the pets schema will look like :

I've also created the same files for the pet_foods schema. In the end of this Section i'll also present a link to a Github page which contains the PetShop-Edition as a boilerplate project to create new editions.

It is also possible to define more things for our schemas like widgets, and integrations but those will be covered later.

The next step for our edition should be creating new Flywheels and Kanbans that can be used for the schemas. In our sample we'll create a Pets-Flywheel only which consists of 3 Kanbans:

The Akquisition Kanban,The CareTaking Kanban and the Selling Kanban. Each Kanban consists of its own phases. Kanbans and Flywheels have there own folder which exists outside of the schema folder. So we need to go back to our main folder (where the details.json is located) and create a new folder "kanbans" and a new folder "flywheels".

As i already said, our Flywheel will consist of 3 kanbans, so we create 3 json files inside the kanban folder which look like those 3:

Each children object in the kanban files represents one step in the kanban, so it's pretty simple.

After we created the kanban files we need to create the flywheel file which now references to the names of the kanbans that it consists of (the order is important here!).

flywheel-1

Create those files for your edition and you have created your first edition!

Now you need to Zip the folder that contains all data and push it to FLOWFACT via the Bundle-Upload API. Since this API is not documented at the moment but will follow shortly send a mail to besnik.celaj@flowfact.de and i'll upload your edition.

Create a custom Interactive Expose Template

An interactive-exposé template consists of four different file types:

Filetype Description
Json Defines the values that are mapped into the interactive-exposé and settings for the template.
Html Defines the components that are used. It is possible to use the values that are declared in the json file with placeholders here.
CSS Defines the styling of the Html-Components
Javascript Enables the possibility to use custom JS-Code inside the interactive-exposé

A defaultmapping.json is required for a custom interactive-exposé. It defines the default that is used for this interactive-exposé template. It is also possible to add a mapping file for each schema individually. If you want to define a specific mapping that is used for the flat_rent schema for example, you can create a flat_rent.json. The name of the json must exactly be like the schema-name of the entity that should receive a different mapping.

Key Description
maxStageCount The count of stages that the template has.
ratingSettings Settings about the rating-system that flowfact uses.
settings Settings for the interactive-exposé template.
advancedStageConfigurations advanced configurational settings for the stages
initialAgreement Informations that are shown in the agreement that is shown before the content of the interactive-exposé can be seen.
stageConfigurations configurations for the stages.
additionalData additional information for this interactive-exposé template
sections Defines the sections of the interactive-exposé template in the order they are displayed.

The json file:

The json file for the interactive-exposé template defines the mapping that is used for the selected schema or the default mapping that is used for every schema. It also contains informations about the template (for example how many stages the template has and so on).

Example json file

The html file:

The Html files contain the components that the interactive-exposé each component has it's own html-file and the html-file has to be named like the component. For example content.html. If you don't create html components the components that are defined in the json file will be shown in a default style. Within the html components you have the possibility to use placeholders that enable you to use the values that are defined in the json-mapping in your own components.

Example html file

The css file

The css file is used to style the components (those that are customly created but also those, that are used as default components that flowfact provide.)

Example css file

The js file

Currently there is no example of a js-file for the interactive-exposé available.

After the files are created you need to upload the template-files to the interactive-exposé service via the following ressource:

Create an interactive-exposé template

Create a custom Applikation-Widget that can be displayed in the client

Understanding how a Custom-Widget works in the Client is the first important Step to be able to create a Widget. The communication between the FF-Client and the Custom-Widget that will be shown in the application is realized through a library that is called Postrobot.

Let's first of all look at the following picture (Comments are in German right know, they will be translated to english at a later time.)

Image couldn't be displayed!

As you can see in the Picture the process of Adding a widget into the Client technically starts with an initial call that the FLOWFACT-Client will send to the Widget that should be included. In this call the Widget will get the necessary API-Tokens as well as the Material-UI Theme of FLOWFACT and environment variables. After that the Widget will say that it is ready to be displayed by sending a ready-call with the input "true".

After that the Client will send the information about the selected data in the Client so the Widget knows in which context it has been called. After that the Widget can send resize calls with it's new Size as parameter (this prevents a second scrollbar because of the fact that the iFrame is added to the site).

Right know, to add a Widget to the Client there are multiple preparations that need to be done. Because of that it is necessary to get in contact with FLOWFACT to prepare everything to make you able to create a widget in a development-account.

The structure of the informations that are provided/needed by the FLOWFACT Client are the following:

Help

If the information that you are looking for is not provided here or you are struggling to find the right solution for your problem you can get in contact with our Productmanagement Team by sending an email to feedback@flowfact.de

Errors

The FLOWFACT API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. You may have entered a wrong parameter.
401 Unauthorized -- Your API key is wrong. Except for the authentication-call every other call that is not called with /public/ will need a cognito-token that needs to be provided.
403 Forbidden -- You have no rights to access this resource. If you should have the rights, maybe you have provided a wrong cognitoToken in the header.
404 Not Found -- The resource that you are trying to access does not exist.
405 Method Not Allowed -- You tried to access a ressource with the wrong REST-Method. Example: You tried to create an entity with a GET instead of using POST
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.