{"id":13631016,"url":"https://github.com/bpmnServer/bpmn-server","last_synced_at":"2025-04-17T17:32:18.599Z","repository":{"id":40280012,"uuid":"266181578","full_name":"bpmnServer/bpmn-server","owner":"bpmnServer","description":"BPMN 2.0 server for Node.js , providing modeling, execution, persistence and monitoring for Workflow. along with sample UI. Intended to be developers workbench for BPMN 2.0","archived":false,"fork":false,"pushed_at":"2025-04-12T03:09:19.000Z","size":16527,"stargazers_count":202,"open_issues_count":6,"forks_count":49,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-12T04:23:38.600Z","etag":null,"topics":["bpmn","bpmn-engine","bpmn-js","nodejs","typescript","workflow"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/bpmnServer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-22T18:33:26.000Z","updated_at":"2025-04-12T03:09:22.000Z","dependencies_parsed_at":"2023-10-17T06:47:44.472Z","dependency_job_id":"5720cea2-fb56-4247-8ba4-c4afdfcbbd38","html_url":"https://github.com/bpmnServer/bpmn-server","commit_stats":{"total_commits":213,"total_committers":6,"mean_commits":35.5,"dds":"0.22065727699530513","last_synced_commit":"fa73ee21b446dcc4bf66a96a37e246974474b503"},"previous_names":["bpmnserver/bpmn-server","ralphhanna/bpmn-server"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpmnServer%2Fbpmn-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpmnServer%2Fbpmn-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpmnServer%2Fbpmn-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpmnServer%2Fbpmn-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bpmnServer","download_url":"https://codeload.github.com/bpmnServer/bpmn-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249360063,"owners_count":21257165,"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":["bpmn","bpmn-engine","bpmn-js","nodejs","typescript","workflow"],"created_at":"2024-08-01T22:02:07.308Z","updated_at":"2025-04-17T17:32:18.592Z","avatar_url":"https://github.com/bpmnServer.png","language":"TypeScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Overview Home\n\n`bpmn-server` is a BPMN-based workflow engine that integrates easily into your Node.js app. It supports built-in state persistence, variable management, and concurrency across clusters—ideal for long-running processes, durable services, and scheduled tasks.\n\n## Architecture Overview\n\nThe following diagram illustrates the core components of `bpmn-server` and how they interact:\n\n![Architecture Diagram](https://bpmnserver.github.io/docs/images/architecture-diagram.png)\n\n- **Modeler**: Front-end UI for designing BPMN models using bpmn.io.\n- **bpmn-server Core**: Executes BPMN workflows, manages state, and interfaces with external services.\n- **Datastore**: Persists workflow state, variables, and history (MongoDB by default).\n- **Application Layer**: Your Node.js app that integrates with the server, handles user authentication, and invokes workflows.\n\n## Quick Start\n\n### Using the Demo Project\n\n```sh\n# 1. Clone the demo app\n$ git clone https://github.com/bpmnServer/bpmn-web.git\n$ cd bpmn-web\n\n# 2. Install dependencies\n$ npm install\n\n# 3. Run setup to create default install files\n$ npm run setup\n\n# 4. Edit `.env` file.\n\n# 5. Run setup to create database and models\n$ npm run setup\n\n# 6. Start the server\n$ npm run start\n```\n\nOpen your browser to [http://localhost:3000](http://localhost:3000) to launch the demo.\n\n### Programmatic Usage Example\n\n```js\nconst { BPMNServer, DefaultAppDelegate } = require('bpmn-server');\nconst { configuration } = require('./configuration');\n\nconst server = new BPMNServer(configuration, new DefaultAppDelegate());\n\nconst processName = 'invoice';\nconst inputData = { amount: 1200 };\n\n(async () =\u003e {\n    const result = await server.engine.start(processName, inputData);\n    console.log('Process started with instance id:', result.instance.id);\n})();\n```\n\nFor more advanced examples, see the [API documentation](https://bpmnserver.github.io/docs/api).\n\n---\n\n## Modeling\n\n`bpmn-server` provides a modeling tool based on `bpmn.io` with a customized property panel, eliminating the need to manually edit BPMN files.\n\n![](https://bpmnserver.github.io/docs/images/Modeler.png)\n\nYou can also import BPMN models from other tools.\n\nEach model is defined in a BPMN XML file and consists of various elements. An `element` can be a `node` (such as events, tasks, or gateways) or a `flow`.\n\nModels are managed by `bpmn-server` and can be queried using the [Model API](https://bpmnserver.github.io/docs/api/interfaces/IAPIModel).\n\nAll BPMN 2.0 elements are supported. [See Modeling Support](https://bpmnserver.github.io/docs/examples)\n\n## Execution\n\n`bpmn-server` is primarily an execution engine for BPMN models.\n\nEach time a model is started, an `instance` is created. For every `element` that is executed, an `item` is generated.\n\nExecution follows the BPMN model logic and supports extensions such as scripting and application context access.\n\nDuring execution, both Model Listeners and Application Listeners are invoked.\n\nAccess the execution engine via the [Engine API](https://bpmnserver.github.io/docs/api/interfaces/IAPIEngine).\n\n- [Invoking the Execution Engine](https://bpmnserver.github.io/docs/invokation)\n- [Execution Behavior](https://bpmnserver.github.io/docs/execution)\n\n## Datastore\n\nExecution data, including instances and their elements, are persisted to a datastore (MongoDB by default).\n\nYou can query this data through the [Data API](https://bpmnserver.github.io/docs/api/interfaces/IAPIData).\n\n- [Data Management Documentation](https://bpmnserver.github.io/docs/data)\n\n## User Management and Security\n\n`bpmn-server` delegates authentication to the front-end application, which must pass user information via the API.\n\n1. Model designers can define `assignee`, `candidateUsers`, and `candidateUserGroups` using static strings or JavaScript expressions.\n2. The front-end must provide a `userService` implementation.\n3. `bpmn-server` enforces security rules based on the current user.\n\nThe `bpmn-web` demo application demonstrates full user management using Passport and MongoDB.\n\n- [Security Documentation](https://bpmnserver.github.io/docs/security)\n\n## Demo Web Application\n\n\u003cdetails\u003e\n\u003csummary\u003eExplore the `bpmn-web` demo application.\u003c/summary\u003e\n\nFeatures include:\n\n- Persistent modeling tool (based on `bpmn.io`)\n- Property panel supporting all `bpmn-server` features\n- Execution with input forms for defined fields\n\n![](https://bpmnserver.github.io/docs/images/inputFields.png)\n\n- Task and workflow lists\n- Instance detail view\n\n![](https://bpmnserver.github.io/docs//images/instance-details1.png)\n\n- Model specification viewer\n\n![](https://bpmnserver.github.io/docs//images/instance-details2.png)\n\u003c/details\u003e\n\n## Live Demo\n\nA live demo is available at: [https://bpmn.omniworkflow.com](https://bpmn.omniworkflow.com)\n\n## Installation\n\nThis package requires Node.js and MongoDB.\n\nIf MongoDB is not installed, you can [create a free cloud account](http://bit.ly/cyd-atlas) or [install it locally](https://www.mongodb.com/docs/manual/installation/).\n\n### 1. Clone the repository\n```sh\ngit clone https://github.com/bpmnServer/bpmn-web.git\n```\n\n### 2. Install dependencies\n```sh\nnpm install\n```\n\n### 3. Set up the app\n```sh\nnpm run setup\n```\n\nEdit the `.env` file to configure MongoDB:\n```env\nMONGO_DB_URL=mongodb://0.0.0.0:27017/bpmn\n```\n\nRun setup again to create DB objects:\n```sh\nnpm run setup\n```\n\n### 4. Start the server\n```sh\nnpm run start\n```\n\nConsole output:\n```text\nbpmn-server WebApp.ts version 1.4.0\nMongoDB URL mongodb://0.0.0.0:27017/bpmn\ndb connection open\nApp is running at http://localhost:3000 in development mode\nPress CTRL-C to stop\n```\n\n## Docker Installation\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall `bpmn-server` and dependencies with Docker.\u003c/summary\u003e\n\n### 1. Create a project folder\n\n### 2. Add a `docker-compose.yml` file:\n```yaml\nversion: \"3.7\"\nname: bpmn-server\nservices:\n  bpmn-web:\n    image: ralphhanna/bpmn-web\n    command: sh -c \"\n        npm run setup \u0026\u0026\n        npm run start\"\n    ports:\n      - 3000:3000\n    volumes:\n      - 'app:/app'\n    depends_on:\n      - mongo\n\n  mongo:\n    image: mongo\n    ports:\n      - 27017:27017\n    volumes:\n      - mongodb:/data/db\n\nvolumes:\n  mongodb:\n    driver: local\n    driver_opts:\n      type: 'none'\n      o: 'bind'\n      device: './mongodb_volume'\n\n  app:\n    driver: local\n    driver_opts:\n      type: 'none'\n      o: 'bind'\n      device: './bpmn_server_volume'\n```\n\n### 3. Start the container\n```sh\ndocker compose up -d\n```\n\u003c/details\u003e\n\n## Command Line Interface\n\n\u003cdetails\u003e\n\u003csummary\u003eUse `bpmn-server` via CLI for common operations.\u003c/summary\u003e\n\n```sh\nnpm run cli\n\nserver started..\nCommands:\n  q     quit\n  s     start process\n  lo    list outstanding items\n  li    list items\n  l     list instances for a process\n  di    display instance information\n  i     invoke task\n  sgl   signal task\n  msg   message task\n  d     delete instances\n  lm    list models\n  lme   list model elements\n  ck    check locked instances\n  re    recover hung processes\n  lu    list users\n  spw   set user password\n  ?     show this help menu\n```\n\u003c/details\u003e\n\n## Updating to Latest Release\n```sh\nnpm update bpmn-server\n```\n\n## Application Integration\n\n`bpmn-server` is designed to be embedded into your application. [See customization guide](https://bpmnserver.github.io/docs/customization)\n\n## Documentation\n\n- [Invoking Workflows](https://bpmnserver.github.io/docs/invokation)\n- [Execution](https://bpmnserver.github.io/docs/execution)\n- [Scripting](https://bpmnserver.github.io/docs/scripting)\n- [Security](https://bpmnserver.github.io/docs/security)\n- [Data](https://bpmnserver.github.io/docs/data)\n  - [Input/Output](https://bpmnserver.github.io/docs/data#input-output-data)\n  - [Data Query](https://bpmnserver.github.io/docs/data#dataQuery)\n- [Examples](https://bpmnserver.github.io/docs/examples)\n- [API Summary](https://bpmnserver.github.io/docs/api-summary)\n- [API Reference](https://bpmnserver.github.io/docs/api)\n- [Setup](https://bpmnserver.github.io/docs/setup)\n- [Application Integration](https://bpmnserver.github.io/docs/customization)\n\n## License\n\nLicensed under the MIT License.\n\n## Acknowledgments\n\n`bpmn-server` builds upon [bpmn-io/bpmn-moddle](https://github.com/bpmn-io/bpmn-moddle) by [bpmn.io](http://bpmn.io), and is inspired by [bpmn-engine](https://github.com/paed01/bpmn-engine).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FbpmnServer%2Fbpmn-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FbpmnServer%2Fbpmn-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FbpmnServer%2Fbpmn-server/lists"}