diff --git a/README.md b/README.md index ba6a310b..035c2598 100644 --- a/README.md +++ b/README.md @@ -1,183 +1,173 @@ -[![FINOS - Active](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-active.svg)](https://community.finos.org/docs/governance/Software-Projects/stages/active) -[![codecov](https://codecov.io/gh/finos/spring-bot/branch/spring-bot-develop/graph/badge.svg?token=CSa0aaqYD0)](https://codecov.io/gh/finos/spring-bot) -![License](https://img.shields.io/github/license/finos/spring-bot) -![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg) -[![javadoc](https://javadoc.io/badge2/org.finos.springbot/chat-workflow/javadoc.svg)](https://javadoc.io/doc/org.finos.springbot/chat-workflow) -[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5948/badge)](https://bestpractices.coreinfrastructure.org/projects/5948) - -| Version | Number | Status | -| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| Spring Bot (Spring Boot V4) | [![Maven Central](https://img.shields.io/maven-central/v/org.finos.springbot/spring-bot)](https://central.sonatype.com/search?q=org.finos.springbot&smo=true) | ![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg) | -| Spring Bot (Spring Boot V3) | [![Maven Central](https://img.shields.io/maven-central/v/org.finos.springbot/spring-bot?versionPrefix=10)](https://central.sonatype.com/search?q=org.finos.springbot&smo=true) | ![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg) | -| Spring Bot (Spring Boot V2) | [![Maven Central](https://img.shields.io/maven-central/v/org.finos.springbot/spring-bot?versionPrefix=9)](https://central.sonatype.com/search?q=org.finos.springbot&smo=true) | ![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg) | -| Symphony Java Toolkit | [![Maven Central](https://img.shields.io/maven-central/v/org.finos.symphony.toolkit/symphony-java-toolkit)](https://central.sonatype.com/search?q=org.finos.symphony.toolkit&smo=true) | ![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg?branch=symphony-java-toolkit-master) | - -![Spring Bot Logo](logo.png) - -# Spring Bot - -Spring Bot is a set of [Spring Boot](https://spring.io/projects/spring-boot) starters designed for building chat bots in Java & Kotlin. - -## What Is It? - -- Spring Bot provides a simple annotation-based way to create chat bots. -- It currently supports Symphony and Microsoft Teams. -- It allows you to build your chatbot using annotations, binding messages to methods in a similar way to [Spring Web MVC](https://docs.spring.io/spring-framework/docs/6.0.x/reference/html/web.html#spring-web) -- [READ THE FINOS CASE STUDY HERE](https://www.finos.org/deutsche-bank-spring-bot-case-study) - -## Why Is This Important? - -πŸ§‘πŸ½β€πŸ€β€πŸ§‘πŸ½ **Multiple Platforms** - -Like it or not, most of us find ourselves working in environments with _multiple chat platforms_. As bot developers, we need to be able to reach users irrespective of which platform they are on. - -β›… **Work at a higher level** - -Developers of chat-bots are not well-supported with Open-Source tooling. Too much effort gets spent on low-level message-handling, which could easily be done by a library. - -πŸ”’ **Avoid Lock-In** - -Most bot development tools are commercial. If you build bots with them you are locked into paying license fees forever. For example, the Microsoft Bot Framework support multiple chat platforms at the expense of locking you into the Azure ecosystem. - -## How Does It Work? - -This is best described at [springbot.finos.org](https://springbot.finos.org). This takes you through the process of building several example bots from scratch. - -## What Are The Benefits? - -### βœ”οΈ Build Bots that run on multiple platforms - -> By using Spring Bot's abstractions, you can target both Symphony and Microsoft Teams. Depending on demand (or contributions) further platforms may be supported in the future. In the tutorials we show how to build a [claim processing bot](https://springbot.finos.org/getting-started.html) which runs a workflow concurrently on Teams and Symphony. - -### βœ”οΈFocus On Business Logic - -> Spring Bot handles marshalling from/to the underlying message formats on your platform. - -### βœ”οΈ Advanced Templating - -> Templates are automatically generated for any Java objects (POJOs) that you want to send to the chat platform. This allows users to read/edit objects and send them back to your bot. Additionally, templates are fully customizable on a per-platform basis, currently using Freemarker and Thymeleaf. - -### βœ”οΈAnnotations Make It Super-Easy - -> As the [tutorials](https://springbot.finos.org) show, you just drop a few annotations into your application to enable it to read and send chat messages. - -### βœ”οΈ A Mature Ecosystem - -> By building bots in a mature ecosystem like Java, you avoid all of the usual issues with no-code and low-code environments. Java is a mature language with every conceivable library, a wealth of Stack-Overflow QA's and a convincing DevOps/Deployment story (Java runs anywhere). - -### βœ”οΈ Avoid The Lock-In Trap - -> Most low-code / no-code platforms are a trap: they are looking to lock-in customers and revenue streams by persuading you to build your business with them as a dependency. Spring Bot is open-source so this is literally a non-issue. - -## Watch It In Action - -[![Short 3 minute intro](https://img.youtube.com/vi/TyaGdGmqeGo/hqdefault.jpg)](https://youtu.be/TyaGdGmqeGo) - -## Plenty Of Example Bots To Learn From - -This project contains various example bots that were (originally) written at Deutsche Bank in response to real use-cases. However, we felt they were general enough to warrant Open-Sourcing and including as code to work from. - -πŸ‘ All of these bots work on Microsoft Teams and Symphony, and are deployed into maven central as executable jars. - -### πŸ€– Poll Bot - -A bot for running polls in a Symphony/Teams chat room. πŸ‘ _Production Ready_ - -- [View the README](tools/poll-bot/README.md) - -### πŸ€– News (RSS) Bot - -A bot for feeding news into a Symphony/Teams chat room. πŸ‘ _Production Ready_ - -- [View the README](tools/rss-bot/README.md) - -### πŸ€– Reminder Bot - -Reads the contents of a room and creates reminders based on future events mentioned therein. πŸ‘ _Production Ready_ - -- [View the README](tools/reminder-bot/README.md) - -## Plenty of Tutorials / Demo Code - -Inside the `/demos` directory you can see three example bots: - -- `demo-bot` : The "Hello World" of Spring Bot -- `todo-bot` : Runs a simple todo-list inside a chat room on Teams or Symphony. -- `room-bot` : A room broadcasting bot, that shows how to use the chat dropdown, and address messages across Teams and Symphony. -- `claim-bot`: An example of an expense-claim workflow running across Teams and Symphony concurrently. -- `custom-help-bot`: Shows you how you can override built-in beans (like the `HelpController`) to change the functionality of Spring Bot. - -Tutorials for building these and the reference guide are found here: [Spring Bot](https://springbot.finos.org) - -# License - -Copyright 2022 FINOS - -Distributed under the Apache License, Version 2.0. - -SPDX-License-Identifier: Apache-2.0 - -# Vulnerabilities / Security - -Please see our [Security Policy](SECURITY.md). - -# How To Contribute - -We are always looking for helpful contributors! You can check out the [Good First Issues](https://github.com/finos/spring-bot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or our [Contributing Guidelines](CONTRIBUTING.md) page for more details. - -We have a [weekly Spring Bot project meeting](https://calendar.google.com/calendar/u/0/embed?src=finos.org_fac8mo1rfc6ehscg0d80fi8jig@group.calendar.google.com&ctz=America/New_York) which you can attend. Minutes are [held as issues](https://github.com/finos/spring-bot/issues). - -# Roadmap - -The spring bot roadmap is a number of tagged issues that we are working on _next_. - -You can view the roadmap issues [here](https://github.com/finos/spring-bot/issues?q=is%3Aissue+is%3Aopen+label%3Aroadmap). - -# For Maintainers - -## Branches - -There are two main branches: - -- `spring-bot-master`: new code for the multi-platform Symphony / Microsoft Teams bot builder -- `symphony-java-toolkit-master`: legacy code for when this project only supported symphony. - -## Releasing This Project - -In order to do a release: - -1. Changes.md - -- Update this file to include details of the release. - -2. On Releaser's machine: - -``` -# on spring-bot-master branch -mvn clean test -mvn versions:set -DnewVersion=.. -DartifactId=\* -DgroupId=\* -mvn -DskipTests clean test source:jar javadoc:javadoc deploy -P symphony-release -mvn versions:set -DnewVersion=..-SNAPSHOT -DartifactId=\* -DgroupId=\* -# then PR spring-bot-master branch with the new version number -``` -OR - -``` -#create your version tag and push that tag on spring-bot-master branch -mvn clean test -mvn versions:set -DnewVersion=.. -DartifactId=\* -DgroupId=\* -git tag .. -git push origin .. -mvn versions:set -DnewVersion=..-SNAPSHOT -DartifactId=\* -DgroupId= -``` - -3. SECURITY.md - -- Update this with new version numbers if needed. - -4. On `oss.sonatype.org` - -- Close the Staging Repository -- Release it. - -5. Perform release on github with same number +[![FINOS - Graduated](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-graduated.svg)](https://community.finos.org/docs/governance/lifecycle-stages/graduated) +[![codecov](https://codecov.io/gh/finos/spring-bot/branch/spring-bot-develop/graph/badge.svg?token=CSa0aaqYD0)](https://codecov.io/gh/finos/spring-bot) +![License](https://img.shields.io/github/license/finos/spring-bot) +![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg) +[![javadoc](https://javadoc.io/badge2/org.finos.springbot/chat-workflow/javadoc.svg)](https://javadoc.io/doc/org.finos.springbot/chat-workflow) +[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5948/badge)](https://bestpractices.coreinfrastructure.org/projects/5948) + +| Version | Number | Status | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| Spring Bot (Spring Boot V4) | [![Maven Central](https://img.shields.io/maven-central/v/org.finos.springbot/spring-bot)](https://central.sonatype.com/search?q=org.finos.springbot&smo=true) | ![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg) | +| Spring Bot (Spring Boot V3) | [![Maven Central](https://img.shields.io/maven-central/v/org.finos.springbot/spring-bot?versionPrefix=10)](https://central.sonatype.com/search?q=org.finos.springbot&smo=true) | ![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg) | +| Spring Bot (Spring Boot V2) | [![Maven Central](https://img.shields.io/maven-central/v/org.finos.springbot/spring-bot?versionPrefix=9)](https://central.sonatype.com/search?q=org.finos.springbot&smo=true) | ![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg) | +| Symphony Java Toolkit | [![Maven Central](https://img.shields.io/maven-central/v/org.finos.symphony.toolkit/symphony-java-toolkit)](https://central.sonatype.com/search?q=org.finos.symphony.toolkit&smo=true) | ![build](https://github.com/finos/spring-bot/actions/workflows/build.yml/badge.svg?branch=symphony-java-toolkit-master) | + +![Spring Bot Logo](logo.png) + +# Spring Bot + +Spring Bot is a set of [Spring Boot](https://spring.io/projects/spring-boot) starters designed for building chat bots in Java & Kotlin. + +## What Is It? + +- Spring Bot provides a simple annotation-based way to create chat bots. +- It currently supports Symphony and Microsoft Teams. +- It allows you to build your chatbot using annotations, binding messages to methods in a similar way to [Spring Web MVC](https://docs.spring.io/spring-framework/docs/6.0.x/reference/html/web.html#spring-web) +- [READ THE FINOS CASE STUDY HERE](https://www.finos.org/deutsche-bank-spring-bot-case-study) + +## Why Is This Important? + +πŸ§‘πŸ½β€πŸ€β€πŸ§‘πŸ½ **Multiple Platforms** + +Like it or not, most of us find ourselves working in environments with _multiple chat platforms_. As bot developers, we need to be able to reach users irrespective of which platform they are on. + +β›… **Work at a higher level** + +Developers of chat-bots are not well-supported with Open-Source tooling. Too much effort gets spent on low-level message-handling, which could easily be done by a library. + +πŸ”’ **Avoid Lock-In** + +Most bot development tools are commercial. If you build bots with them you are locked into paying license fees forever. For example, the Microsoft Bot Framework support multiple chat platforms at the expense of locking you into the Azure ecosystem. + +## How Does It Work? + +This is best described at [springbot.finos.org](https://springbot.finos.org). This takes you through the process of building several example bots from scratch. + +## What Are The Benefits? + +### βœ”οΈ Build Bots that run on multiple platforms + +> By using Spring Bot's abstractions, you can target both Symphony and Microsoft Teams. Depending on demand (or contributions) further platforms may be supported in the future. In the tutorials we show how to build a [claim processing bot](https://springbot.finos.org/getting-started.html) which runs a workflow concurrently on Teams and Symphony. + +### βœ”οΈFocus On Business Logic + +> Spring Bot handles marshalling from/to the underlying message formats on your platform. + +### βœ”οΈ Advanced Templating + +> Templates are automatically generated for any Java objects (POJOs) that you want to send to the chat platform. This allows users to read/edit objects and send them back to your bot. Additionally, templates are fully customizable on a per-platform basis, currently using Freemarker and Thymeleaf. + +### βœ”οΈAnnotations Make It Super-Easy + +> As the [tutorials](https://springbot.finos.org) show, you just drop a few annotations into your application to enable it to read and send chat messages. + +### βœ”οΈ A Mature Ecosystem + +> By building bots in a mature ecosystem like Java, you avoid all of the usual issues with no-code and low-code environments. Java is a mature language with every conceivable library, a wealth of Stack-Overflow QA's and a convincing DevOps/Deployment story (Java runs anywhere). + +### βœ”οΈ Avoid The Lock-In Trap + +> Most low-code / no-code platforms are a trap: they are looking to lock-in customers and revenue streams by persuading you to build your business with them as a dependency. Spring Bot is open-source so this is literally a non-issue. + +## Watch It In Action + +[![Short 3 minute intro](https://img.youtube.com/vi/TyaGdGmqeGo/hqdefault.jpg)](https://youtu.be/TyaGdGmqeGo) + +## Plenty Of Example Bots To Learn From + +This project contains various example bots that were (originally) written at Deutsche Bank in response to real use-cases. However, we felt they were general enough to warrant Open-Sourcing and including as code to work from. + +πŸ‘ All of these bots work on Microsoft Teams and Symphony, and are deployed into maven central as executable jars. + +### πŸ€– Poll Bot + +A bot for running polls in a Symphony/Teams chat room. πŸ‘ _Production Ready_ + +- [View the README](tools/poll-bot/README.md) + +### πŸ€– News (RSS) Bot + +A bot for feeding news into a Symphony/Teams chat room. πŸ‘ _Production Ready_ + +- [View the README](tools/rss-bot/README.md) + +### πŸ€– Reminder Bot + +Reads the contents of a room and creates reminders based on future events mentioned therein. πŸ‘ _Production Ready_ + +- [View the README](tools/reminder-bot/README.md) + +## Plenty of Tutorials / Demo Code + +Inside the `/demos` directory you can see three example bots: + +- `demo-bot` : The "Hello World" of Spring Bot +- `todo-bot` : Runs a simple todo-list inside a chat room on Teams or Symphony. +- `room-bot` : A room broadcasting bot, that shows how to use the chat dropdown, and address messages across Teams and Symphony. +- `claim-bot`: An example of an expense-claim workflow running across Teams and Symphony concurrently. +- `custom-help-bot`: Shows you how you can override built-in beans (like the `HelpController`) to change the functionality of Spring Bot. + +Tutorials for building these and the reference guide are found here: [Spring Bot](https://springbot.finos.org) + +# License + +Copyright 2022 FINOS + +Distributed under the Apache License, Version 2.0. + +SPDX-License-Identifier: Apache-2.0 + +# Vulnerabilities / Security + +Please see our [Security Policy](SECURITY.md). + +# How To Contribute + +We are always looking for helpful contributors! You can check out the [Good First Issues](https://github.com/finos/spring-bot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or our [Contributing Guidelines](CONTRIBUTING.md) page for more details. + +We have a [weekly Spring Bot project meeting](https://calendar.google.com/calendar/u/0/embed?src=finos.org_fac8mo1rfc6ehscg0d80fi8jig@group.calendar.google.com&ctz=America/New_York) which you can attend. Minutes are [held as issues](https://github.com/finos/spring-bot/issues). + +# Roadmap + +The spring bot roadmap is a number of tagged issues that we are working on _next_. + +You can view the roadmap issues [here](https://github.com/finos/spring-bot/issues?q=is%3Aissue+is%3Aopen+label%3Aroadmap). + +# For Maintainers + +## Branches + +There are two main branches: + +- `spring-bot-master`: new code for the multi-platform Symphony / Microsoft Teams bot builder +- `symphony-java-toolkit-master`: legacy code for when this project only supported symphony. + +## Releasing This Project + +In order to do a release: + +1. Changes.md + +- Update this file to include details of the release. + +2. On Releaser's machine: + +``` +# on spring-bot-master branch +mvn clean test +mvn versions:set -DnewVersion=.. -DartifactId=\* -DgroupId=\* +mvn -DskipTests clean test source:jar javadoc:javadoc deploy -P symphony-release +mvn versions:set -DnewVersion=..-SNAPSHOT -DartifactId=\* -DgroupId=\* +# then PR spring-bot-master branch with the new version number +``` + +3. SECURITY.md + +- Update this with new version numbers if needed. + +4. On `oss.sonatype.org` + +- Close the Staging Repository +- Release it. + +5. Perform release on github with same number