Skip to content

Latest commit

 

History

History
179 lines (117 loc) · 8.61 KB

README.md

File metadata and controls

179 lines (117 loc) · 8.61 KB
Raw

formsflow.ai API

FormsFlow API CI Python Flask postgres Imports: isort Code style: black linting: pylint

formsflow.ai has built this adaptive tier for correlating form management, BPM and analytics together.

The goal of the REST API is to provide access to all relevant interfaces of the system. It is built using Python 🐍 .

Table of Content

  1. Prerequisites
  2. Solution Setup
  3. API Documentation
  4. Unit Testing
  5. Migration Script for existing users (For listing existing forms for clients)

Prerequisites

  • For docker based installation Docker need to be installed.
  • Admin access to Keycloak server and ensure audience(camunda-rest-api) is setup in Keycloak-bpm server.

Solution Setup

Installation

If you are interested in contributing to the project, you can install through docker or locally.

It's recommended to download dev-packages to follow Python coding standards for project like PEP8 if you are interested in contributing to project. You installing dev-packages using pip as follows:

python3 -m pip install -r requirements/dev.txt

Keycloak Setup

No specific client creation is required. Audience has been added for clients forms-flow-web and forms-flow-bpm.

Environment Configuration

  • Make sure you have a Docker machine up and running.
  • Make sure your current working directory is "forms-flow-ai/forms-flow-api".
  • Rename the file sample.env to .env.
  • Modify the environment variables in the newly created .env file if needed. Environment variables are given in the table below,
  • NOTE : {your-ip-address} given inside the .env file should be changed to your host system IP address. Please take special care to identify the correct IP address if your system has multiple network cards

ℹ️ Variables with trailing 🚩 in below table should be updated in the .env file

Variable name Meaning Possible values Default value
INSIGHT_API_URL🚩 The forms-flow-analytics Api base end-point http://{your-ip-address}:7000
INSIGHT_API_KEY 🚩 The forms-flow-analytics admin API key Get the api key from forms-flow-analytics (REDASH) by following the 'Get the Redash API Key' steps from [here](../forms-flow-analytics/README.md#get-the-redash-api-key)
FORMSFLOW_API_DB_USER formsflow database postgres user Used on installation to create the database.Choose your own postgres
FORMSFLOW_API_DB_PASSWORD formsflow database postgres password Used on installation to create the database.Choose your own changeme
FORMSFLOW_API_DB_NAME formsflow database name Used on installation to create the database.Choose your own FORMSFLOW_API_DB
FORMSFLOW_API_DB_URL JDBC DB Connection URL for formsflow postgresql://postgres:changeme@forms-flow-webapi-db:5432/webapi
KEYCLOAK_URL🚩 URL to your Keycloak server http://{your-ip-address}:8080
KEYCLOAK_URL_REALM The Keycloak realm to use eg. forms-flow-ai forms-flow-ai
KEYCLOAK_BPM_CLIENT_ID Client ID for Camunda to register with Keycloak eg. forms-flow-bpm forms-flow-bpm
KEYCLOAK_BPM_CLIENT_SECRET Client Secret of Camunda client in realm eg. 22ce6557-6b86-4cf4-ac3b-42338c7b1ac12 e4bdbd25-1467-4f7f-b993-bc4b1944c943

To generate a new keycloak client seceret by yourself follow the steps from here
KEYCLOAK_WEB_CLIENT_ID Client ID for formsflow to register with Keycloak eg. forms-flow-web forms-flow-web
BPM_API_URL🚩 Camunda Rest API URL http://{your-ip-address}:8000/camunda
FORMSFLOW_API_URL🚩 formsflow.ai Rest API URL http://{your-ip-address}:5000
FORMSFLOW_API_CORS_ORIGINS formsflow.ai Rest API allowed origins, for allowing multiple origins you can separate host address using a comma seperated string or use * to allow all origins eg:host1, host2, host3 *

NOTE : Default realm is forms-flow-ai

Running the Application

  • forms-flow-api service uses port 5000, make sure the port is available.

  • cd {Your Directory}/forms-flow-ai/forms-flow-api

  • Run docker-compose up -d to start.

NOTE: Use --build command with the start command to reflect any future .env changes eg : docker-compose up --build -d

To Stop the Application

  • Run docker-compose stop to stop.

Verify the Application Status

The application should be up and available for use at port defaulted to 5000 in http://localhost:5000/

  • Access the /checkpoint endpoint for a Health Check on API to see it's up and running.
GET http://localhost:5000/checkpoint

RESPONSE

{
    "message": "Welcome to formsflow.ai API"
}
  • Get the access token
POST {Keycloak URL}/auth/realms/<realm>/protocol/openid-connect/token

Body:
grant_type: client_credentials
client_secret: {set client token}
client_id: forms-flow-bpm

Headers:
Content-Type : application/x-www-form-urlencoded
  • Access the /task endpoint and verify response. Ensure Bearer token is passed along
GET http://localhost:5000/task

Headers:
Content-Type : application/json
Authorization: Bearer {access token}

API Documentation

The API docs can be accessed by checking the / root endpoint.

image

Further documentation and associated postman collection for API endpoint can found in the docs folder

Unit Testing

We have implemented unit tests with pytest.

  • Test cases are provided in the tests folder.
  • Run the tests by ensuring appropriate test environment variables are setup in the .env file.
  • Using the make command, run the tests by running make test.

Things to note when writing tests:

  • Isolated: Each test should be an introvert, working in their own isolated bubble. You should never have to think about what other tests have put in the database.
  • Tests functions should contain always app, client, session

Migration Script for existing users

To display existing forms and applications for clients and reviewers, it is necessary to migrate the current Camunda authorizations. Additionally, to transfer existing task filters from forms-flow-bpm to forms-flow-api

Follow the steps below:

Run a bash script inside the forms-flow-api. If you need to run this script in the instance or server, such as a Kubernetes cluster or Nginx, you have to access the Docker container of the FormsFlow web API and execute the bash script called migration.sh.

Commands to execute:

  • To migrate forms: migration.sh form
  • To migrate applications: migration.sh application
  • To migrate filter: migration.sh filter
    • In multi-tenant environment: migration.sh filter <tenant-key>

Alternatively, if you are setting up the environment locally and running the Docker container locally, you can get inside the FormsFlow web API container and run preferred command.

In the case of running the web API with Flask locally, you should activate the virtual environment and run the bash script within it. You can create the virtual environment by following the instructions provided in the Makefile inside the forms-flow-api.

References for Testing in Python