Difference between revisions of "LingoBot MS Team Setup"

From Lingoport Wiki
Jump to: navigation, search
(Setup ngrok)
(Create a Microsoft Teams app package)
 
(14 intermediate revisions by one other user not shown)
Line 14: Line 14:
 
addr: 5001
 
addr: 5001
   
* Run commands to start the ngrok service
+
* As a root user (not jenkins), run the commands to start the ngrok service
<code> sudo systemctl enable ngrok.service
+
sudo systemctl enable ngrok.service
sudo systemctl start ngrok.service
+
sudo systemctl start ngrok.service
sudo systemctl status ngrok.service
+
sudo systemctl status ngrok.service
  +
If the status does not show '''active (running)''', then there is a problem.
</code>
 
   
* Return to [https://ngrok.com/ ngrok] page and click '''Status''' from the left list, store the HTTPS URL for later use.
+
* Return to the [https://ngrok.com/ ngrok] page and click '''Status''' from the left list. Store the HTTPS URL for later use. If the page does not show any tunnels online, refresh the page.
   
 
== Microsoft Bot Registration==
 
== Microsoft Bot Registration==
Line 28: Line 28:
 
* On this page, you can set a custom icon for the bot under the "'''Upload custom icon'''" section. You can download the following icon [[File:Lingoport logo small.jpeg|30px]] and upload it, upload your own custom icon, or simply leave it blank.
 
* On this page, you can set a custom icon for the bot under the "'''Upload custom icon'''" section. You can download the following icon [[File:Lingoport logo small.jpeg|30px]] and upload it, upload your own custom icon, or simply leave it blank.
   
* In the Display name field, enter the name that you would like LingoBot to respond to.
+
* In the '''Display name''' field, enter the name that you would like LingoBot to respond to.
 
** By default, we recommend simply calling it "'''lingobot'''", however you're welcome to name it whatever you would like.
 
** By default, we recommend simply calling it "'''lingobot'''", however you're welcome to name it whatever you would like.
 
** If you do choose to call it something other than "lingobot", make sure that you set the '''LINGOBOT_NAME''' variable in the configuration file to whatever name you chose.
 
** If you do choose to call it something other than "lingobot", make sure that you set the '''LINGOBOT_NAME''' variable in the configuration file to whatever name you chose.
 
*** Example: <code>export LINGOBOT_NAME=lingobot-123</code>
 
*** Example: <code>export LINGOBOT_NAME=lingobot-123</code>
   
* Click Create Microsoft App ID and password. Store the created app id and app password for use later.
+
* Click '''Create Microsoft App ID and password'''. You may be prompted to login into your MS Teams account first. Store the created app id and app password for use later.
   
* Copy the created app id and past it into the LingoBot configuration file
+
* Copy the created app id and paste it into the LingoBot configuration file
 
('''/var/lib/jenkins/lingoport/lingobot-<x.y>/config/lingobot_config.sh''') next to the '''BOTBUILDER_APP_ID''' variable declaration.
 
('''/var/lib/jenkins/lingoport/lingobot-<x.y>/config/lingobot_config.sh''') next to the '''BOTBUILDER_APP_ID''' variable declaration.
   
Line 52: Line 52:
 
export BOTBUILDER_APP_PASSWORD='wdS50{cphgeDCTKZO073{]#'
 
export BOTBUILDER_APP_PASSWORD='wdS50{cphgeDCTKZO073{]#'
   
* Copy and paste the URL generated by ngrok to Messaging endpoint field, and add /api/messages to the end.
+
* Copy and paste the URL generated by ngrok to '''Messaging endpoint''' field on the Botframework Registration page, and add /api/messages to the end.
   
 
Example:
 
Example:
 
https://87406e76.ngrok.io/api/messages
 
https://87406e76.ngrok.io/api/messages
   
  +
* Fill in the '''Paste your app ID below to continue''' field using the App ID.
* Once this is done, scroll down to the bottom of the page and click "'''Register'''" to complete.
 
   
  +
* Once this is done, scroll down to the bottom of the page, agree to the terms of service, and click "'''Register'''" to complete.
* On the new opened My bots page, you will find your just created bot, under Connect to channels field, the Web Chat has been added as default. Click MS Teams icon under "'''Add a featured channel'''" to add MS Teams channel. And Save your changes.
 
  +
  +
* On the new opened '''My bots''' page, you will find your just created bot, under '''Connect to channels''' field, the Web Chat has been added as default. Click MS Teams icon under "'''Add a featured channel'''" to add MS Teams channel. And '''Save''' your changes.
   
 
== Create a Microsoft Teams app package ==
 
== Create a Microsoft Teams app package ==
Line 65: Line 67:
 
* Installing App Studio for Microsoft Teams follow steps on [https://docs.microsoft.com/en-us/microsoftteams/platform/get-started/get-started-app-studio this] page.
 
* Installing App Studio for Microsoft Teams follow steps on [https://docs.microsoft.com/en-us/microsoftteams/platform/get-started/get-started-app-studio this] page.
   
* Once you are in App Studio, click on the Manifest editor tab. Click Create a new app.
+
* Once you are in App Studio, click on the '''Manifest editor''' tab. Click '''Create a new app'''.
   
* Complete the App details section. This includes things such as the app’s name, description, and visual branding. You can automatically generate a GUID for your app and provide URLs for your privacy statement and terms of use.
+
* Complete the '''App details''' section. This includes things such as the app’s name, description, and visual branding. You can automatically generate a GUID for your app and provide URLs for your privacy statement and terms of use.
   
* Click bot section, set up a bot then click Existing bot tab, type in your bot name and Select from one of your existing bots, then choose the bot you just created above.
+
* Click '''Bots''' section, set up a bot then click '''Existing bot''' tab, type in your bot name and '''Select from one of your existing bots''', then choose the bot you just created above.
   
* Copy and paste the URL to Messaging endpoints and make sure it match the value you just set at bot Register page.
+
* Copy and paste the URL to Messaging endpoints and make sure it matches the value you just set at bot Register page.
   
 
Example:
 
Example:
 
https://87406e76.ngrok.io/api/messages
 
https://87406e76.ngrok.io/api/messages
   
  +
* Click "Add" button under Commands section to add new commands
* Create a Microsoft Teams app package (.zip) to upload in Teams. Click Test and distribute under Finish section, and click Download button to download the package file.
 
  +
  +
Example:
  +
Command text: list projects
  +
Help text: Displays list of active projects
  +
Scope: Team
  +
  +
* Create a Microsoft Teams app package (.zip) to upload in Teams. Click '''Test and distribute''' under the '''Finish''' section, and click '''Download''' button to download the package file.
   
* Click Store button (left down at the Teams), click Upload a custom app (at left bottom). And upload the package file just created above.
+
* Click the '''Store''' button (left down at the Teams), click '''Upload a custom app''' (at bottom left). And upload the package file just created above.
   
   

Latest revision as of 21:52, 5 December 2018

This portion of the installation guide only applies if the collaboration environment you will be using is MS Teams. If you will be using either Flowdock or Cisco Spark or Slack, please skip to the corresponding setup instructions.

Setup ngrok

  • Navigate to the ngrok page and sign up a free account. Click Auth from the left list, and copy your Tunnel Authtoken.
  • Copy the Tunnel Authtoken and past it into the LingoBot configuration file

(/var/lib/jenkins/lingoport/lingobot-<x.y>/config/config.yml) next to the authtoken variable declaration.

Example:

authtoken: 2nde8yqeH8wLiBkv848BW_2Mm39SdudjQJmJ7xxxxxx
tunnels:
   default:
       proto: http
       addr: 5001
  • As a root user (not jenkins), run the commands to start the ngrok service
 sudo systemctl enable ngrok.service
 sudo systemctl start ngrok.service 
 sudo systemctl status ngrok.service

If the status does not show active (running), then there is a problem.

  • Return to the ngrok page and click Status from the left list. Store the HTTPS URL for later use. If the page does not show any tunnels online, refresh the page.

Microsoft Bot Registration

  • Navigate to the Bot Registration Page page. Create a Botframework Registration by completing the Bot Registration Page.
  • On this page, you can set a custom icon for the bot under the "Upload custom icon" section. You can download the following icon Lingoport logo small.jpeg and upload it, upload your own custom icon, or simply leave it blank.
  • In the Display name field, enter the name that you would like LingoBot to respond to.
    • By default, we recommend simply calling it "lingobot", however you're welcome to name it whatever you would like.
    • If you do choose to call it something other than "lingobot", make sure that you set the LINGOBOT_NAME variable in the configuration file to whatever name you chose.
      • Example: export LINGOBOT_NAME=lingobot-123
  • Click Create Microsoft App ID and password. You may be prompted to login into your MS Teams account first. Store the created app id and app password for use later.
  • Copy the created app id and paste it into the LingoBot configuration file

(/var/lib/jenkins/lingoport/lingobot-<x.y>/config/lingobot_config.sh) next to the BOTBUILDER_APP_ID variable declaration.

Example:

export BOTBUILDER_APP_ID=e8911192-eca4-4f37-8284-616f3339f0e6

Furthermore, make sure the LINGOBOT_ADAPTER variable is set to botframework.

Example:

export LINGOBOT_ADAPTER=botframework
  • Copy the created app password and past it into the LingoBot configuration file

(/var/lib/jenkins/lingoport/lingobot-<x.y>/config/lingobot_config.sh) next to the BOTBUILDER_APP_PASSWORD variable declaration.

Example:

export BOTBUILDER_APP_PASSWORD='wdS50{cphgeDCTKZO073{]#'
  • Copy and paste the URL generated by ngrok to Messaging endpoint field on the Botframework Registration page, and add /api/messages to the end.

Example:

 https://87406e76.ngrok.io/api/messages
  • Fill in the Paste your app ID below to continue field using the App ID.
  • Once this is done, scroll down to the bottom of the page, agree to the terms of service, and click "Register" to complete.
  • On the new opened My bots page, you will find your just created bot, under Connect to channels field, the Web Chat has been added as default. Click MS Teams icon under "Add a featured channel" to add MS Teams channel. And Save your changes.

Create a Microsoft Teams app package

  • Installing App Studio for Microsoft Teams follow steps on this page.
  • Once you are in App Studio, click on the Manifest editor tab. Click Create a new app.
  • Complete the App details section. This includes things such as the app’s name, description, and visual branding. You can automatically generate a GUID for your app and provide URLs for your privacy statement and terms of use.
  • Click Bots section, set up a bot then click Existing bot tab, type in your bot name and Select from one of your existing bots, then choose the bot you just created above.
  • Copy and paste the URL to Messaging endpoints and make sure it matches the value you just set at bot Register page.

Example:

 https://87406e76.ngrok.io/api/messages
  • Click "Add" button under Commands section to add new commands

Example:

 Command text: list projects
 Help text: Displays list of active projects
 Scope: Team
  • Create a Microsoft Teams app package (.zip) to upload in Teams. Click Test and distribute under the Finish section, and click Download button to download the package file.
  • Click the Store button (left down at the Teams), click Upload a custom app (at bottom left). And upload the package file just created above.


Once this is complete, the bot is now configured and ready to be installed! Follow the instructions below on running the installation script to finish the installation process.

Skip to the next step: Running The Installation Script