getting started with watson workspace & work services

Hands-on Lab Session 1579 My First Conversation Bot – Making Watson Workspace & Work Services work for ME! Paul Godby, CSP & ISV Ecosystems

Duration: 45 minutes

Session 1579, My First Conversation Bot

of 15

IBM Connect

© Copyright IBM Corporation 2017

IBM, the IBM logo and ibm.com are trademarks of International Business Machines Corp., registered

in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or

other companies. A current list of IBM trademarks is available on the Web at “Copyright and

trademark information” at www.ibm.com/legal/copytrade.shtml.

This document is current as of the initial date of publication and may be changed by IBM at any time.

The information contained in these materials is provided for informational purposes only, and is

provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any

damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these

materials is intended to, nor shall have the effect of, creating any warranties or representations from

IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license

agreement governing the use of IBM software. References in these materials to IBM products,

programs, or services do not imply that they will be available in all countries in which IBM operates.

This information is based on current IBM product plans and strategy, which are subject to change by

IBM without notice. Product release dates and/or capabilities referenced in these materials may change

at any time at IBM’s sole discretion based on market opportunities or other factors, and are not

intended to be a commitment to future product or feature availability in any way.


of 15

IBM Connect

Table of Contents

Overview 4

Create an IBM Bluemix account 4

Review Watson Work samples in GitHub 5

Deploy the sample application to Bluemix 7

Register the sample with Watson Workspace 9

Create a webhook for the sample application 10

Update environment variables in Bluemix 11

Enable the application’s webhook 13

Add the application to a space 14

Test the application 15


of 15

IBM Connect

Overview In this lab, you will be introduced to IBM Watson Workspace & Work Services application development. You will learn how to deploy a Watson Work sample from GitHub to IBM Bluemix and then add the application to Watson Workspace. This will give you a better understanding of the processes required for building your own bots. After completing this lab, you will have the knowledge and experience necessary to begin building your own bots. You can use these tools to integrate virtually any type of bot or service into a space. For example, you could build a new application using the IBM Watson Conversation service to provide Q/A functionality to a space. The possibilities are endless! A hands-on lab for the IBM Watson Conversation service can be found here.

Create an IBM Bluemix account IBM Bluemix is a platform-as-a-service (PaaS) offering that allows you to create your own application mashups using a variety of runtimes and services. Before you can begin building cloud and cognitive applications, you will need to create your own Bluemix account. A free 30-day trial is provided. If you already have an IBM Bluemix account, you can skip this section.

1. In a web browser, navigate to the following URL:

https://www.bluemix.net/

2. In the upper right portion of the page, click Sign Up.

3. You will be taken to the account creation page. On this page, you can review the terms of the trial and review the Bluemix privacy policy. Fill out the form and click Create Account. If you do not already have an IBMid, this process will create one automatically for you.

4. After you submit your registration, you will receive an e-mail from the IBM Bluemix team confirming your new account.

5. That’s it! You now have a free 30-day trial on IBM Bluemix!

http://www.ibm.com/watson/developercloud/conversation.html

http://www.slideshare.net/pgodby/ibm-watson-conversation-nodejs

https://www.bluemix.net/


of 15

IBM Connect

Review Watson Work samples in GitHub IBM Watson Work Services provide you with a set of APIs that are designed to help people get work done. You can make use of these services to build out your own application.

We also have an application built on our platform, called Watson Workspace. You can integrate and connect your application to Watson Workspace through our services.

Sample applications are available on GitHub so you can see Watson Work Services in action, explore the code, and learn how to build your own.

6. In a web browser, navigate to the following URL:

https://github.com/watsonwork

7. As you can see, there are several sample applications to choose from. When you build your own application, you can review the code in GitHub to learn how to provide similar functionality in your own projects. Review the descriptions for each of the provided samples.

8. Click on the watsonwork-echo sample to be taken to its GitHub repository.

9. On the overview page, read through the summary of the sample. You will notice that it provides detailed instructions on how to deploy and use the sample application. You will be following similar steps as you work through this lab document.

https://github.com/watsonwork


of 15

IBM Connect

10. Scroll back to the top of the page and click on the src folder followed by the file named app.js. Since this sample is a Node.js application, this is the file that provides the starting point for the code and the subsequent application logic.

11. Since this lab is intended to be an introduction to Watson Work development, we won’t go over every line of code in the application. Instead, we’ll focus on the some of the key configuration and functionality found in the code. Review the following lines of code.

Lines Description

20 – 50 A function that will echo any chat messages containing “hello” or

“hey” back to the space they were sent to

27: verify this is a “message-created” webhook event

34-38: parse the message body for “hello” or “hey”

41-49: call the “send” function to send a response

53 – 89 A function that will send a message back to a space

54: utilize the “request” module to send the response

55: the REST API URL to use

56-58: add the authorization header

62-79: specify a color, title, text, and an actor

118 – 144 Set up the Express application

120: generate the OAuth token (review oauth.js to see

how the token was generated)

130: listen for HTTP POST requests at URI “/echo”

142: call the “echo” function to respond to a request


of 15

IBM Connect

Lines Description

147 – 186 The entry / start point for the application

150-151: obtain Watson Workspace space credentials

from Bluemix environment variables. More on this later!

12. Now that the code review is finished, scroll to the top of the page and return to the application overview by clicking the watsonwork-echo link in the breadcrumb trail.

13. Continue to the next section.

Deploy the sample application to Bluemix The Deploy to Bluemix button is an efficient way to share your public Git-sourced app so that other people can experiment with the code and deploy it to IBM Bluemix. The button requires minimal configuration and you can insert it anywhere that supports markup. Anyone who clicks the button creates a cloned copy of the code in a new Git repository so that your original app remains unaffected.

14. Scroll down to the Try it out section and click the Deploy to Bluemix button.

15. If you are not already signed in to Bluemix, click Log In.

16. To deploy the sample to Bluemix, fill out the form as follows:

Field Value

App Name << leave current value >>

Region IBM Bluemix US South

Organization << choose organization >>

Space << choose space >>


of 15

IBM Connect

17. Click Deploy and wait for all operations to finish.

18. Once the sample application has been successfully deployed to Bluemix, you will see some options to View your app or to Edit Code. The Edit Code button will take you to the IBM Bluemix DevOps Services and let you modify your application logic using an IDE in your web browser. Cool stuff!

19. At the top of the page, click Dashboard.

20. In the Cloud Foundry Apps section, locate your new application and take note of its deployed URL. You will need this value in the next section. Leave the browser open and continue with the lab.


of 15

IBM Connect

Register the sample with Watson Workspace

You will need to register your sample application to create your App Identity so that you can get your code working with Watson Work Services. This will generate the IDs and secrets that you will need to configure and use for authorization purposes in the sample application.

21. In a new browser tab, navigate to the following URL:

https://workspace.ibm.com/developer

22. If you see the Go to Watson Work Services button, click it to sign in with your IBMid.

23. Scroll down and click the Register your app now button.

24. Click the Create new app button.

25. Fill out the form as follows:

Field Value

App Name Echo1579-<<your initials>>

Description of App IBM Connect sample

26. Click Create.

27. A pop-up window will appear with the details of your new App registration. Click Copy to copy your App secret to the clipboard. You should then paste it into a text editor until it is needed. Click Got it.

https://workspace.ibm.com/developer


of 15

IBM Connect

Create a webhook for the sample application

Webhooks allow your application to listen to events that occur in a space. You will need to register the webhook and provide a callback URL for IBM Watson Work Services to call. Your application will be provided information about the event and then will send the appropriate response to the originating space.

28. Now that your application is registered, the details for the application should still be open in the browser. In the navigation menu on the left,

click Listen to events.

29. On the right, click Add an outbound webhook.

30. In the Edit event listener window, fill out the form as follows. As you’ll recall, you can find the Deployed URL for your sample Bluemix application in the Bluemix Dashboard. During the code review, you also learned that the application will be listening for HTTP POST requests on route “/echo”.

Field Value

Webhook Name echo

Callback URL: The Deployed URL of your Bluemix

application followed by URI “/echo”

Events Select the following:

message-created


of 15

IBM Connect

31. Click Save.

32. A pop-up window will appear with the details of your new webhook registration. Do not close this window until you have completed the following section!!! If you do, you will lose the webhook secret and will need to delete and recreate the webhook.

Update environment variables in Bluemix

Like all Cloud Foundry-based cloud platform environments, IBM Bluemix uses JSON environment variables to provide information about applications, services, and the Bluemix environment itself. These system-provided environment variables allow applications and services that run in the Bluemix environment to retrieve the information they need.

33. Return to the browser tab that contains the Bluemix Dashboard.

34. In the Cloud Foundry Apps section, click on the row for your sample

application. You will be taken to its Overview page.

35. In the navigation menu on the left, choose Runtime.

36. At the top of this page, click the Environment Variables tab.


of 15

IBM Connect

37. At the bottom of this page, under the User defined section, use the Add/Save buttons to add the following environment variables to your application. You can find the appropriate values in the pop-up window that should still be opened in one of your other browser tabs. The App secret will be the value you copied into a text editor.

Environment Variable Value

ECHO_APP_ID << the app id >>

ECHO_APP_SECRET << the app secret >>

ECHO_WEBHOOK_SECRET << the webhook secret >>

38. In the upper right corner of this page, click the Start button to launch the application.

39. Wait until your application has fully started.

40. Leave all browser tabs open and proceed to the next section.


of 15

IBM Connect

Enable the application’s webhook

As you learned in a previous section, a Watson Work Services webhook allows your application to listen to events that occur in a space. Now that you have a sample application up and running in Bluemix, you will need to go back and enable the webhook. You were instructed to start your Bluemix application before performing this step because Watson Work Services will perform a DNS check when enabling a webhook. If the platform can’t access the provided callback URL, you won’t be allowed to enable a webhook.

41. Return to the browser tab with your Watson Work Services App. If your webhook registration pop-up window is still open, you can now close it.

42. On the right, under the Listen to events section, you should see your new webhook. Click the Enable button.

If you encounter errors, go back to your Bluemix Dashboard and verify the sample application is running. Restart it if necessary.

43. At the time this lab was written, you won’t see a confirmation if this process completes successfully. Instead, you will see the text on the button change to “Disable”.


of 15

IBM Connect

Add the application to a space

In Watson Work Services a space is the place where people come together to collaborate. It represents the container for the people who are collaborating, and it contains the resources people use to engage in collaboration - for example a space holds the conversation, which is where people exchange messages.

44. In a new browser tab, navigate to the following URL:

https://workspace.ibm.com/

45. In the top left corner of the page, create a new Space by clicking the plus sign (+). (You might need to log in with your IBMid first.)

46. In the first part of the wizard, just leave “You” as a member and click Name Your Space at the bottom of the page. Give your test space the name “Examples” and click Create.

47. Review the welcome message and click the Settings link that is provided. In the future, you can click the name of the space at the top of the page to return to the settings.

48. In the Space Settings, choose Apps from the menu on the left.

https://workspace.ibm.com/


of 15

IBM Connect

49. Hover over your sample application and click Add to Space

50. In the top right corner of the page, click the X to close the settings and return to the space.

Test the application

It’s time to perform some tests! As with any application, it’s important to take a deep breath and cross your fingers when you press the ENTER key during the initial testing phase. If you fail to do this, the application might not work.

51. At the bottom of the page, locate the UI element that says “Type something”. Enter the following messages and wait for the response from your sample application running in Bluemix. As you’ll recall, it will only echo if it receives text containing “hello” or “hey”.

Hello, my name is <<your name>>

This lab is fantastic

Hey, I learned a lot from this lab session. Thanks!

52. You’re done! You are now officially a Watson Work developer!

getting started with watson workspace & work services

Software