{"id":25650685,"url":"https://github.com/flow-build/workflow-api","last_synced_at":"2025-06-25T10:36:56.270Z","repository":{"id":38290092,"uuid":"248001805","full_name":"flow-build/workflow-api","owner":"flow-build","description":null,"archived":false,"fork":false,"pushed_at":"2023-08-17T14:08:37.000Z","size":4156,"stargazers_count":9,"open_issues_count":0,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-17T20:18:53.071Z","etag":null,"topics":["docker"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flow-build.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-03-17T15:13:22.000Z","updated_at":"2025-04-17T00:16:32.000Z","dependencies_parsed_at":"2025-04-15T19:42:26.371Z","dependency_job_id":"beacf95b-84db-402b-b2d8-7bb86929f05c","html_url":"https://github.com/flow-build/workflow-api","commit_stats":null,"previous_names":["flow-build/workflow"],"tags_count":81,"template":false,"template_full_name":null,"purl":"pkg:github/flow-build/workflow-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-build%2Fworkflow-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-build%2Fworkflow-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-build%2Fworkflow-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-build%2Fworkflow-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flow-build","download_url":"https://codeload.github.com/flow-build/workflow-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-build%2Fworkflow-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260433869,"owners_count":23008431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker"],"created_at":"2025-02-23T15:17:48.292Z","updated_at":"2025-06-25T10:36:56.223Z","avatar_url":"https://github.com/flow-build.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Workflow API\n\n## Dependencies:\n\n```\nnode -v\nv18.12\n\nnpm -v\n9.2.0\n```\n\n## Environment variables\n\nAdd a .env file with the following variables:\n\n- NODE_ENV (suggested value = docker)\n- KOA_LOG_LEVEL (error, warn, _info_, http, verbose, debug, silly)\n- PORT (default=_3000_)\n\n### DATABASE CONNECTION\n\n- KNEX_ENV (text, docker, dockerLocal, _prod_)\n- POSTGRES_PORT\n- POSTGRES_HOST\n- POSTGRES_DATABASE\n- POSTGRES_USER\n- POSTGRES_PASSWORD\n- DB_MAX_POOL_CONNECTION (default=10)\n\n### TOKEN CONFIGURATION\n\nThe default configuration is set to use a own generated JWT token.\nIf an external token is to be used, the JWT\\_ variables need to be passed.\n\n- JWT_KEY (default=_1234_)\n- JWT_ALG (default=_HS256_, if set to RS256, the application will convert the JWT_KEY to a public certificate.)\n- JWT_PASSTHROUGH (boolean, default=_true_)\n- JWT*EXTRA_KEYS (\\_optional*, defines extra properties from token payload that should be sent to process' actor_data)\n- JWT_PATH_ACTOR_ID (default=_actor_id_, specifies the path to the actor id in the token payload)\n- JWT_PATH_CLAIMS (default=_claims_. Claims value should always be an array)\n- JWT*PATH_SESSION_ID (\\_optional*, default=_session_id_)\n\n### MQTT CONFIGURATION\n\n- MQTT (bool)\n- MQTT_HOST\n- MQTT_PORT\n- MQTT_PATH\n- MQTT_PROTOCOL\n- MQTT*USERNAME (\\_optional*, required for wss connections)\n- MQTT*PASSWORD (\\_optional*, required for wss connections)\n- MQTT_NAMESPACE (if present, this string will the prepended to any topic published)\n\n### AMQP CONFIGURATION\n\n- AMQP (bool)\n- BROKER_HOST\n- BROKER_QUEUE\n- BROKER_USERNAME\n- BROKER_PASSWORD\n\n### KAFKA CONFIGURATION\n\n- KAFKA (bool)\n- KAFKA_BOOTSTRAP_SERVER\n- KAFKA_SEC_PROTOCOL\n- KAFKA_SASL_MECHANISMS\n- KAFKA_CLUSTER_API_KEY\n- KAFKA_API_SECRET\n- KAFKA_SESSION_TIMEOUT\n\n### EVENT Nodes CONFIGURATION (also WEM CONFIGURATION)\n\n- WORKFLOW_EVENTS_BROKER (Values: KAFKA|MQTT|AMQP. If not defined, it won't send)\n- WORKFLOW_EVENTS_NAMESPACE\n\n### CHOOSING BROKERS TO USE (AMQP OR MQTT)\n\n- ACTIVITY_MANAGER_BROKER\n- PROCESS_STATE_BROKER\n- ENGINE_LOGS_BROKER\n\n### ACTIVITY_MANAGER CONFIGURATION\n\n- ACTIVITY_MANAGER_SEND_ONLY_ON_CREATION (bool)\n\n### ENGINE CONFIGURATION\n\n- ENGINE_LOG_LEVEL (default=_error_)\n- ENGINE_HEARTBEAT (_true_/false string, turns on-off engine heartbeat)\n- HEART_BEAT (integer, default=1000, interval between beats in ms)\n- PUBLISH_STATE_EVENTS (_true_/false string, enables states to be published to message broker)\n- PUBLISH_ENGINE_LOGS (_true_/false string, enables engine logs to be published to message broker)\n- PUBLISH_SERVER_LOGS (_true_/false string, enables api logs to be published to message broker)\n- MAX_STEP_NUMBER (integer, maximum number of steps for a process)\n- MAX_CONTENT_LENGTH (integer, max content length for response on http node calls)\n- MAX_BODY_LENGTH (integer, max body length for response on BasicAuth nodes)\n- HTTP_TIMEOUT (integer, timeout in ms for BasicAuth nodes)\n- TIMER_BATCH (integer, default=_40_)\n- ORPHAN_BATCH (integer, default=_40_)\n\n#### TIMER CONFIGURATION\n\nTimer management can be handled outside the heartbeat, by a external Timer Worker running timers using an Redis Queue using bullMQ.\nTo enable this option, the engine must be configured to publish timers on the queue thru 3 variables that configures the bullMQ.\n\n- TIMER_QUEUE (string)\n- TIMER_HOST (URL)\n- TIMER_PORT\n\n### HEALTHCHECK\n\nHealthcheck route (GET / or GET /healthcheck), by default, checks the router and db connection.\nThe server can be configured to evaluate the number of ready timers (timers expired but not yet triggered) to access engine health.\nThis setting should not be enabled if the timers area being handled by the timer worker.\n\n- MAX*READY_TIMERS (\\_optional*, integer, defines the amount of ready timers before the server is declared unhealthy)\n\n### MONITORING\n\n- OTEL_ENABLED (bool, activates Open Telemetry config)\n- OTEL_SERVICE_NAME (string)\n- OTEL_COLLECTOR_URL\n\n#### NEW RELIC CONFIGURATION\n\n- NEW_RELIC_ENABLED (bool, activates New Relic config for direct or OTEL Monitoring.)\n- NEW_RELIC_API_KEY (required if New Relic is enabled)\n- NEW_RELIC_NO_CONFIG_FILE (recommended=_true_)\n- NEW_RELIC_LOG (recommended=_stdout_)\n- NEW_RELIC_LOG_ENABLED (recommended=_true_)\n- NEW_RELIC_LOG_LEVEL (recommended=_info_)\n- NEW_RELIC_DISTRIBUTEC_TRACING_ENABLED (recommended=_true_)\n- NEW_RELIC_APPLICATION_LOGGING_ENABLED (recommended=_true_)\n- NEW_RELIC_APP_NAME\n\n### POSTMAN\n\nFor Newman test runs\n\n- POSTMAN_API_KEY\n- POSTMAN_TEST_COLLECTION\n- POSTMAN_ENVIRONMENT\n\n## Run the project on docker:\n\nTo run docker, just run\n\n```\ndocker-compose up\n```\n\nMake sure ports 3000 and 5432 are free to use on your localhost.\n\nTo run the tests, you may use the command below:\n\n```\ndocker-compose run -T app ./scripts/run_tests.sh\n```\n\nFor Windows users, comment the script command from the docker-compose.yml and use the bash one.\n\n## Exploring and executing the API\n\nTo explore all possible routes, go to http://localhost:3000/swagger\n\nIf you change the base url, change it as well in the openapi3.yaml file.\n\nIf you wish to use a third-party program, such as Insomnia or Postman, just import the openapi3.yaml file and all the routes will be shown. If you use Postman, I would recommend changing the Folder organization to Tags after selecting the file to be imported.\n\n## Logging\n\nThere are 2 sources of logs: engine and the API itself. Both uses winston library to manage formats and transports.\n\nThe events emitted by the engine can by logged by the engine itself or managed by the API app.\n\nYou can set the log level from the engine using the ENGINE_LOG_LEVEL variable. At the time you cannot turn them completely off.\n\nThe log levels use the scale below:\n\nsilly -\u003e debug -\u003e verbose -\u003e http -\u003e info -\u003e warn -\u003e error\n\nThe API app uses the same log levels, but they are managed by the KOA_LOG_LEVEL variable and has a default value of info.\n\nNotice that at default configuration, error events are logged twice.\n\nEngine events will also be sent to a `/logs` topic to mqtt if the both MQTT and PUBLISH_ENGINE_LOGS are set to true.\n\n## MQTT\n\nThe default compose will set up a postgres database, an hive MQTT server and the app itself.\n\nDuring app initialization, is the MQTT is true, the flowbuild will try to connect to the MQTT server.\n\nBe sure to provide the following parameters as environment variables\n\n- MQTT_HOST (`localhost` if you a running on docker)\n- MQTT_PORT (8000)\n- MQTT_PATH (/mqtt)\n\nThe following topics will be used:\n\n- `/logs` for engine logs\n- `/process/:processId/state` for each process state created\n- `/process/:processId/am/create` for each activity_manager created\n- `/actor/:actorId/am/create` for each activity_manager created, if an actor_id property exists in activity_manager input\n- `/session/:sessionId/am/create` for each activity_manager created, if an session_id property exists in activity_manager input\n\n## Tests\n\nYou can run unit tests by running `npm run tests`.\n\nIf you would like to test the routes itself, you can use Newman to do that, by running the command.\n\n```bash\nnewman run postman \\newman\\tests.postman_collection.json -e postman\\newman\\local_environment.json\n```\n\n## Bibliography\n\n### how to prepare for windows\n\n[how to install docker on windows](https://docs.docker.com/docker-for-windows/install/)\n[hot to install wsl2](https://docs.microsoft.com/pt-br/windows/wsl/install-win10)\n\n### how to prepare for linux\n\n[how to install docker on linux distros](https://docs.docker.com/engine/install/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflow-build%2Fworkflow-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflow-build%2Fworkflow-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflow-build%2Fworkflow-api/lists"}