Git 中文文档

BenTen


CUI Chatbot framework (Has out of the box slack-bot support for Jira and Jenkins)


BenTen is a CUI Chatbot framework that provides all the integrations that are necessary for building useful conversational chatbots in a few minutes. It has integrations with NLP engines like Dialogflow, Messaging platforms like Slack, project management tools like Jira and Continuous Integration Tools like Jenkins. It also has support to render messages in various formats like Slack, html (html to image conversion), csv etc...

Benten makes it easy for anybody to build their own personal assistants to take care of mundane tasks.

The framework lets you concentrate on the core functionality you want to build (for example building a conversational chatbot to monitor application health and show it in Slack on demand) rather than worry about integrations with Slack, NLP engines or applications like Jira, Jenkins and the orchestration between these systems.

Story behind the name BenTen


If you're wondering why the name BenTen, you can find an answer here Why the name Benten ?

Features


Jira Feature Command
:--- :---
Create new Jira Story/Bug/Sub-Task create jira story, create jira bug, create jira subtask, create jira story Experience benten jira integration project BENTEN
Show details of a JIRA issue details of issue, details of issue BENTEN-1
Assign issue assign issue BENTEN-1 to @divakarungatla
Search issues assigned to me or created by me my issues, my tickets
Comment on an issue comment on issue, comment on issue BENTEN-1 this is an example comment
Log work for an issue/story log 3h 4m against issue BENTEN-1 this is a comment for logging work
Show subtasks of a story subtasks of story AAA-1234
Transition issue move BENTEN-1 to inprogress
Cycle time for a sprint cycle time of board Benten over last 2 sprints
Velocity of a team based on a sprint velocity of board Benten over last 2 sprints

Note:BenTen uses a headless user which you are going to specify in the benten properties file in the following sections to perform the jira operations. So some features like assign move will need the headless user to be added as admin to you projects. Here is how you do it Add user as admin in Jira.

Jenkins Feature Command
:--- :---
Search for Jenkins job search for jenkins job, search for jenkins job with prefix Purchase
Details of Jenkins job details of jenkins job, details of jenkins job Purchase-Service-Release
Build Jenkins job build jenkins job Purchase-Service-Release

Flickr Feature Command
:--- :---
Search for Photos or Videos flickr 5 photos of cats, flickr videos of dogs
Search Trendy Photos flickr trendy photos, flickr popular photos
Search Camera Brands flickr canon cameras

Weather Feature Command
:--- :---
Weather information in current city How is the weather in San Diego ?

BenTen - Architecture


undefined

Let's set up BenTen


Now that you have experienced the bot, let us set up BenTen with your own slack bot and run against your Jira and Jenkins.

If you are behind a corporate proxy, or especially if your local Maven installation has been configured to point to a repository within your local network, the command below may not work. One workaround is to temporarily disable or rename your Maven settings.xml file, and try again.


Setting up BenTen from binaries (recommended if you want just use existing capabilities and add custom features only specific to your organization)


There is a maven archetype(benten-archetype) that I created that can be used to set up a skeleton project super quick. Run the below command in your terminal.

  1. ``` shell
  2. mvn archetype:generate -DarchetypeGroupId=com.intuit.benten -DarchetypeArtifactId=benten-archetype -DarchetypeVersion=0.1.5 -DgroupId=com.mycompany -DartifactId=benten-starter
  3. cd benten-starter
  4. mvn clean install -Dmaven.test.skip=true
  5. ```

Setting up BenTen from sources (recommended if you want to contribute/add new features or integrations to BenTen )


To set up BenTen from sources follow the below steps

  1. ``` shell
  2. git clone https://github.com/intuit/benten
  3. mvn clean install -Dmaven.test.skip=true
  4. ```

To use BenTen in your existing spring project include the below dependencies in your projects pom.xml and refer to Setting up to initialize BenTen.


  1. ``` xml
  2. <dependency>
  3.     <groupId>com.intuit.benten</groupId>
  4.     <artifactId>benten-core</artifactId>
  5.     <version>0.1.5</version>
  6. </dependency>
  7. ```

Include Jira, Jenkins, Weather and Flickr bolts


  1. ``` xml
  2. <dependency>
  3.     <groupId>com.intuit.benten</groupId>
  4.     <artifactId>benten-jira-bolt</artifactId>
  5.     <version>0.1.5</version>
  6. </dependency>
  7. <dependency>
  8.     <groupId>com.intuit.benten</groupId>
  9.     <artifactId>benten-jenkins-bolt</artifactId>
  10.     <version>0.1.5</version>
  11. </dependency>
  12. <dependency>
  13.     <groupId>com.intuit.benten</groupId>
  14.     <artifactId>benten-flickr-bolt</artifactId>
  15.     <version>0.1.5</version>
  16. </dependency>
  17.     <groupId>com.intuit.benten</groupId>  
  18.     <artifactId>benten-weather-bolt</artifactId>
  19.     <version>0.1.5</version>
  20. </dependency>
  21. ```

Create a slack team and slackbot(You can skip this section if you already have a slack bot API token)


Follow the below steps to create a slack team and then a slack bot. You can skip this step if you already have a team and are the admin.

Creating Slack team


Open https://slack.com/
Provide your email ID. Select Create New workspace.
Check your email and enter the code to verify your email.
Provide your name and set a password
Add some details to your team in the next page
Provide a company name
Team URL should be unique - Also remember this URL - this is what is used to login to your slack instance
Agree with the terms
Skip the invite step
You are up and running with your own instance of Slack.

Now that team is created, let us create a slack bot

Creating Slack bot


Open your {team-URL}/apps (the one you created above). Ex: https://test-visual.slack.com/apps
Search for bot in the search bar and select bots
In the bots landing page click on Add configuration
Provide a bot name. Ex: divakar-bot and click on Add Bot integration
In the Setup instruction page: Copy and store the API Token. Ex: xoxb-22672546-n1X9APk3D0tfksr81NJj6VAM
Save the integration

Create your own Dialog Flow Agent


You might have noticed the conversation interface of BenTen. Benten uses Dialog Flow to build the conversations. You can read more about Dialog flow at https://dialogflow.com/docs/getting-started/basics.

Let us set up your own dialog flow agent. Download the agent zip file from here benten-agent-v2

Follow the instructions in this page Create-BenTen-Agent-in-Dialog-flow to create the agent.

Follow the instructions in this page OAuth Setup For Dialogflow Agent to setup OAuth for the agent.

At the end of it you should have your own dialogflow Project ID with OAuth setup complete.

NOTE: The dialogflow client in Benten will not work unless the OAuth setup is complete.

Now open benten.properties

  1. ``` shell
  2. cd benten-starter
  3. vi src/main/resources/benten.properties
  4. ```

In line #10 change the value of benten.ai.projectId with your Project ID from above

Start BenTen


  1. ``` shell
  2. cd benten-starter
  3. mvn clean install -Dmaven.test.skip=true
  4. vi src/main/resources/benten.properties
  5. ```

In line #11 replace <slackbot token> with your bot token from bot creation step above Creating Slack bot

  1. ``` shell
  2. mvn spring-boot:run
  3. ```

Now if you see your bot in Slack it should be active! Type hi to see it working. Type help jira or create jira story and you can see responses.

If you want to run benten on docker then install docker on your machine.

Execute below steps in the terminal.

  1. ``` shell
  2. cd benten-starter
  3. docker build -f Dockerfile -t benten .
  4. docker container run -it --publish 8081:8080 benten
  5. ```

Point BenTen to your own Jira instance


Remember, at this point benten is still running against the karate mocks that come as part of the BenTen code/artifacts. Now let us point it to you  Jira instance. Follow the below steps

  1. ``` shell
  2. cd benten-starter
  3. vi src/main/resources/benten.properties
  4. ```

In line #16 change benten.jira.baseurl url to point to your own jira instance instead of the localhost. Also change benten.jira.username and benten.jira.password accordingly. BenTen uses these credentials to connect to Jira. Save the changes.

  1. ``` shell
  2. cd benten-starter
  3. vi src/main/resources/benten.properties
  4. ```

Restart your application

  1. ``` sh
  2. mvn clean install -Dmaven.test.skip=true
  3. mvn spring-boot:run

  5. ```

Now try the jira commands from your slack-bot and it should work against your Jira!

If you need to use a proxy when you are on a corporate network, add JVM proxy params to the run command:

  1. ``` sh
  2. mvn spring-boot:run -Dhttp.proxyHost=<proxy-host> -Dhttp.proxyPort=<proxy-port>

  4. ```

Point BenTen to your own Jenkins instance


Similar to Jira make changes for Jenkins as well in benten.properties.

  1. ``` shell
  2. cd benten-starter
  3. vi src/main/resources/benten.properties
  4. ```

In line #18 change benten.jenkins.baseurl url to point to your own jenkins instance instead of the localhost. Also change benten.jenkins.username and benten.jenkins.password accordingly. BenTen uses these credentials to connect to Jira. Save the changes.

Restart your application

  1. ``` sh
  2. mvn clean install -Dmaven.test.skip=true
  3. mvn spring-boot:run

  5. ```

Type jenkins in your bot and try any of the operations to see them work against your jenkins.

Point BenTen to your own Flickr instance


Make changes for Flickr in benten.properties.

Generate your Flickr API key and secret key

In line #25,26 change benten.flickr.apikey and benten.flickr.secret accordingly. BenTen uses these keys to connect to the Flickr API. Save the changes.

Restart your application

  1. ``` sh
  2. mvn clean install -Dmaven.test.skip=true
  3. mvn spring-boot:run

  5. ```

Configure BenTen to Open Weather Map


Sign up for Open weather map api's and get an api token

  1. ``` shell
  2. cd benten-starter
  3. vi src/main/resources/benten.properties
  4. ```

In Line #26, change benten.weather.token to the api token  generated by open weather api.

Restart your application

  1. ``` sh
  2. mvn clean install -Dmaven.test.skip=true
  3. mvn spring-boot:run

  5. ```

Let's get to Action! (Adding a new ActionHandler)


Let us build a feature in BenTen now. Each feature is called an action in BenTen. Remember! the beauty of BenTen is that you need to concentrate only on the core logic. Let us see how.

We will build an action which will ping a service for n number of times and display the results in the slack-bot after every time it pings the application.

First let us build the conversation. Open your agent that you created in this section. Follow this wiki Creating BenTen Example Conversation in Dialogflow

Create a new package com.example in benten-starter.

  1. ``` shell
  2. cd benten-starter
  3. mkdir com/example
  4. ```

Download BentenExampleAction.java and copy it to the com.example package. The contents of the file are explained below!


Restart your application.

  1. ``` sh
  2. mvn clean install -Dmaven.test.skip=true
  3. mvn spring-boot:run

  5. ```

Open your slack bot. Type ping benten for 5 times and you should be able to see the below output

undefined

If you reached this point it might have stuck you that what you can build using BenTen is only limited by your thoughts! Get creative!