{"id":25970954,"url":"https://github.com/boomerang-io/flow.services","last_synced_at":"2025-03-04T23:29:10.509Z","repository":{"id":36956072,"uuid":"282254283","full_name":"boomerang-io/flow.services","owner":"boomerang-io","description":"Monorepo holding the RESTful APIs for Boomerang Flow, a no-code, cloud-native workflow automation tool. Built in Java using Sprint Boot","archived":false,"fork":false,"pushed_at":"2025-03-04T02:46:15.000Z","size":4167,"stargazers_count":7,"open_issues_count":8,"forks_count":8,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-04T03:27:00.685Z","etag":null,"topics":["automation","boomerang","dag","java","spring-boot","workflow"],"latest_commit_sha":null,"homepage":"https://useboomerang.io","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boomerang-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-24T15:25:03.000Z","updated_at":"2025-03-04T02:46:18.000Z","dependencies_parsed_at":"2024-06-04T21:08:02.774Z","dependency_job_id":"c6b02f2b-814e-4ad8-828f-d1fef3568df0","html_url":"https://github.com/boomerang-io/flow.services","commit_stats":null,"previous_names":["boomerang-io/flow.services"],"tags_count":1231,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boomerang-io%2Fflow.services","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boomerang-io%2Fflow.services/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boomerang-io%2Fflow.services/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boomerang-io%2Fflow.services/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boomerang-io","download_url":"https://codeload.github.com/boomerang-io/flow.services/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241937961,"owners_count":20045392,"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":["automation","boomerang","dag","java","spring-boot","workflow"],"created_at":"2025-03-04T23:29:09.852Z","updated_at":"2025-03-04T23:29:10.499Z","avatar_url":"https://github.com/boomerang-io.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Boomerang Flow Services Monorepo\n\nWelcome to the Boomerang Flow Services Monorepo! This repository is the powerhouse behind the Boomerang Flow Workflow\nservices that enable the creation and execution of workflows as Directed Acyclic Graphs (DAGs).\n\nThe [Flow service](./service-flow) provides v2 RESTful APIs for the CRUD operations backing the front-end and direct\nconsumption with:\ncomprehensive User \u0026 Team Management, relationship graph\nbetween objects, authentication and authorisation, scheduling engine and so on.\n\nThe [Engine service](./service-engine) is the backbone providing the execution of the workflows as Directed Acyclic\nGraphs (DAGs).\n\nThe [Handler service](./service-handler) is the service that listens to events and executes the appropriate tasks. The\nHandler that comes with Boomerang Flow by default is the Tekon Handler and executes the Tasks using Tekton on\nKubernetes. Additional implementations can be added, such as running tasks on IBM Code Engine or Azure Container Apps,\netc\n\n```mermaid\ngraph LR\n    A[External Requests] --\u003e|HTTP| B[Flow Service]\n    B --\u003e|HTTP| C[Engine Service]\n    C --\u003e|Events| D[Handler 1]\n    C --\u003e|Events| E[Handler 2]\n    C --\u003e|Events| F[Handler n]\n```\n\n## v3 to v4 Change Log\n\nThere has been an entire code base refactor from v3 to v4 for the engine. We suggest you read the following information\nto understand the full breadth of changes\n\n- [Model changes and v3 to v4 model comparison](https://github.com/boomerang-io/roadmap/issues/368)\n- [Distributed async architecture change](https://github.com/boomerang-io/architecture/tree/feat-v4)\n\n## Dependencies\n\nWith dependencies like CloudEvents and Quartz, this service ensures\nreliable event consumption and scheduled job execution.\n\n### Prerequisites\n\n1. Java 21\n2. Spring Boot 3\n3. Maven\n\n### CloudEvents\n\nThis service listen and consumes CloudEvents.\n\n### Quartz\n\nThe Java Quartz library is used for running scheduled jobs via mongoDB and underpins the Schedule trigger.\n\nThe following links will help provide guidance in development\n\n- http://www.quartz-scheduler.org/documentation/quartz-2.2.2/tutorials/tutorial-lesson-04.html\n- http://www.quartz-scheduler.org/documentation/2.4.0-SNAPSHOT/cookbook/UpdateTrigger.html\n- https://github.com/StackAbuse/spring-boot-quartz/blob/master/src/main/java/com/stackabuse/service/SchedulerJobService.java\n- https://stackabuse.com/guide-to-quartz-with-spring-boot-job-scheduling-and-automation/\n\n## Packaging\n\nWhen ready to package the service(s) as a container, the tags will trigger the appropriate GitHub Action using the\nformat `\u003csvc\u003e/\u003csemver\u003e`:\n\n- Engine Service: tag = `engine/1.0.0-beta.111`\n- Flow Service: tag = `flow/4.0.1`\n\n## Developing and Testing Locally\n\n### Pre-requisits\n\nThis service connects to MongoDB and requires Task Templates and indexes loaded through the Flow Loader. You can run\nthese locally, or alternatively connect to a remote MongoDB service.\n\n### Run Local MongoDB w Docker\n\n```\ndocker run --name local-mongo -d mongo:latest\n```\n\n### Load Boomerang Flow Data\n\n```\ndocker run -e JAVA_OPTS=\"-Dspring.data.mongodb.uri=mongodb://localhost:27017/boomerang -Dflow.mongo.collection.prefix=flow -Dspring.profiles.active=flow\" --network host --platform linux/amd64 boomerangio/flow-loader:latest\n```\n\n### Development via Spring\n\n1. Clone the repository\n2. Run `mvn clean install` to build the project\n3. Run `mvn spring-boot:run` to start the application\n\n### Development via Docker\n\n```\ndocker buildx build --platform=linux/amd64 -f ./service-engine/Dockerfile -t flow-engine:latest .\ndocker run -e JAVA_OPTS=\"-Dspring.data.mongodb.uri=mongodb://localhost:27017/boomerang -Dflow.mongo.collection.prefix=flow -Dspring.profiles.active=flow\" --platform=linux/amd64 flow-engine:latest\n```\n\n## Design Details\n\n### Parameters and Results\n\nThe implementation is based on Tekton Params and Results.\n\nThere is limited support\nfor [Tekton Propagated Object Parameters](https://tekton.dev/docs/pipelines/taskruns/#propagated-object-parameters) in\nthat Tekton requires you to provide the Spec for the JSON Object if you are going to reference child elements. We do not\nhave this constraint, we essentially take the path from what is provided after `params.\u003cparam-name\u003e`.\n\n### Locks\n\nFor distributed locking, we use this [distributed lock](https://github.com/alturkovic/distributed-lock) project with the\nMongo implementation.\n\nThe implementation in `LockManagerImpl.java` relies on the TTL Index for Retries having been added via\nthe `flow.loader`.\n\n## Error Handling\n\nThe following provides design and reference information about the status codes and error messages.\n\n### Response Format\n\nThe format can be seen in `io.boomerang.error.ErrorDetail.java`\n\n| Field     | Description                                                                                                          |\n|-----------|----------------------------------------------------------------------------------------------------------------------|\n| timestamp | UTC timestamp of when the error occurred                                                                             | \n| code      | unique identifier (int) that can be read and understood that detect and handle errors programmatically.              |\n| reason    | unique identifier (string) that can be used to quickly identify and search for more information regarding the error. |\n| message   | a description of the error intended for a human and an end user to provide context.                                  |\n| status    | HTTP Status Code \u0026 Message                                                                                           |\n| cause     | Optional present if `flow.error.include-cause=true` config property is provided                                      |\n\n```json\n{\n  \"timestamp\": \"2023-01-31T00:15:12.672+00:00\",\n  \"code\": 1001\n  \"reason\": \"QUERY_INVALID_FILTERS\",\n  \"message\": \"Invalid query filters(status) have been provided.\",\n  \"status\": \"400 BAD_REQUEST\",\n  \"cause\": null\n}\n```\n\n### Implementation\n\nThe implementation allows for known and custom exceptions in the code.\n\nKnown codes are indexed in the `io.boomerang.error.BoomerangError.java` with the message text in `messages.properties`.\nAlternatively, a custom exception can be thrown in the code however this will lose the benefit of localization (\n_future_)\n\n## Feature Flags\n\n### Security\n\nSecurity is enabled / disabled through the `flow.authorization.enabled` flag in the application.properties\n\nThe following classes are conditionally loaded based on this flag\n\n| Class                                                      | Condition |\n|------------------------------------------------------------|-----------|\n| AuthenticationFilter                                       | true      |\n| InterceptorConfig (and by association SecurityInterceptor) | true      |\n| SecurityConfiguration                                      | true      |\n| SecurityDisabledConfiguration                              | false     |\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboomerang-io%2Fflow.services","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboomerang-io%2Fflow.services","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboomerang-io%2Fflow.services/lists"}