bhumit / watsonworkspacegif-20171130161700502

Created for toolchain: https://console.bluemix.net/devops/toolchains/392f1264-a66b-4167-a716-efcc2e14eff1?env_id=ibm%3Ayp%3Aus-south

IBM Watson Workspace Gif App

This app allows users to post gifs in space. Just type @gif plus a word or phrase (such as @gif awesome) and Gif app will post a random GIF that matches. The Gif app also supports slash commands. It also parses giphy.com links embedded in a message. The uses IBM Watson Workspace Bot Framework and IBM Watson Workspace SDK.

Try it out

Quick Start with IBM Cloud

Let's get started! The steps below will outline the process from getting the app running within IBM Cloud to enable the app to post within a space based on the keyword trigger or slash commands.

Before jumping in, try accessing the links below to make sure you have access to Workspace, the developer experience for Watson Work Services, and IBM Cloud.

• Watson Workspace
• Watson Work Services
• IBM Cloud

Deploy to IBM Cloud

First, let's get this app up and running on IBM Cloud. This will provide us with a publicly accessible endpoint that we can register with Watson Work Services to get events pushed to. To deploy to IBM Cloud, you can simply click the button below. This will create your own IBM Cloud DevOps toolchain in addition to deploying the app. As part of the toolchain, IBM Cloud will create a fork of this Github repository in your own github.com account for source control and a pipeline for building, testing, and deployment.

Once you've clicked the button, you'll get prompted with the following screens:

1. Define your App name, Region, Organization and Space.

Most of the time you can keep the default values, but if you have multiple accounts/organizations/spaces in IBM Cloud, please make note of the values here to make sure the app is deployed where you'd like it to be.

Note: If you haven't previously authenticated github.com with IBM Cloud, do the following:

Click on Authorize. This will redirect you to github.com OAuth authentication.

Click on Authorize IBM-Bluemix to continue. This will complete you authorization with Github and allow IBM DevOps toolchain access to your Github account. You can later revoke this access, if needed.

Click the Create button at the bottom of the screen to continue to the next step.

2. Once deployment and configuration has begun, you will be sent to the DevOps toolchain dashboard for your app:

This will show you each of the "tools" that are provided in the tool chain.

• The Issues block will take you to your own Github repository for this app. It will bring you to the issues section of this repository.
• The Github block will also take you to the Github repository. This repository can be used like any git repository, included with the ability to automatically run the pipeline for any git push.
• The Eclipse Orion Web IDE will take you to Eclipse's web-based editor, with the project connected to the git repository referenced above.
• The Delivery Pipeline block will bring you to IBM Cloud's pipeline dashboard, which outlines each stage configured for the pipeline.

3. Click on the Delivery Pipeline block to see the current status of the deployment.

   When the deployment is done, the deploy stage will appear as below, with a green Stage Passed confirmation box.

   

   Note: It may take a minute or two to deploy.

4. After the app is done deploying, click on the box under Last Execution Result to navigate to the deployed app.

   

5. The Last Execution Result block will take you to the App dashboard for the newly deployed app.

This dashboard shows the status of the app, the URL to access the app and provides the ability to interact with the app ( set environment variables, view logs, etc).

Take note of the app name at the top. The app name is used to construct the URL for the running app: https://<appname>.mybluemix.net.

For example, in the screenshot above, the URL would be: https://watsonworkspacegif-20170805194040469-random-keyword.mybluemix.net

Now let's register this app in Watson Work Services!

Register app with Watson Work Services

An app must be registered with Watson Work Services in order to interact with the platform. The registration process provides the app with an id, secret and enables the app to request certain capabilities, such as listening to events in the system.

To register an app, navigate to the Watson Work Services developer experience: https://developer.watsonwork.ibm.com.

1. Once logged in, select the Your Apps link at the top right.

2. From here, you should see a button to Create new app, as well as a list of apps if you have already created some.

3. Click on Create new app.

   

   Provide any App name and Description that you'd like for your app and then click Create. This name will show up in Watson Work Services as the display name for your app.

4. Once registered, you will be presented with the id and secret for the app.

   Copy both the id and secret for later use.

5. After copying the id and secret, you will be sent to the App Dashboard for the newly registered Watson Work Services app.

This dashboard contains all of the information for your app, as well configuration options for listening to events, enabling your app to run as a user, and much more!

Listen to events in Watson Work Services

Now that your app is registered with Watson Work Services, we can enable it with a variety of different capabilities.

For now we're going to focus on Listen to Events to set our app up to retrieve messages from Watson Work Services.

1. Click on the Listen to Events tab on the side menu in your Apps Dashboard.

2. Click on Add an outbound webhook.

• Provide any Webhook Name that you would like. This name won't be displayed anywhere.

• For the Webhook URL, provide the following URL, based on the app name that was copied above from IBM Cloud.

  • Webhook URL: <appname>.mybluemix.net/webhooks/<app-id>.

    • Example: watsonworkspacegif-20171126165435919-noninsistent-grandee.mybluemix.net/0f5596a4-34f5-46d0-8a0f-6b0d85169f04.

    The form includes the https://, so no need to include that in the input box.

• For the Events section, check the message-created and message-annotation-added option.

3. Once you click Save, a confirmation dialog will appear with your Webhook Secret. Copy this secret. We will need it for configuring our IBM Cloud app.

   

   Note: Even though we have saved the webhook, the webhook is not enabled until we update our app to use the webhook secret. We will come back to the Listen to Events panel to enable it after updating these values in IBM Cloud.

4. Click on the Add an Action tab on the side menu in your Apps Dashboard.

   

5. Click on Add an action.

   

   • Provide any Name that you would like. This name won't be displayed anywhere.
   • For the Description, enter the description you would like to be displayed.
   • Click on the Configure command to continue.

   

   • For Command, enter a keyword which users will invoke.
   • Provide any Hint that you would like to be displayed to the user.
   • Click on the Configure webhook to continue.

   

   • We will use the previously created webhook for listening to actionSeleted events
   • From the drop down, select already created webhook. For example, gif hook or whatever you named it during creation.
   • Click on the Summary to continue.

   

   • Verify the details you have entered so far.
   • Click on the Add Your Action to successfully add action to the app.

   

   • A confirmation dialog will appear with your newly updated webhook details.

6. Navigate back to you IBM Cloud app dashboard to input the ids and secrets. In your IBM Cloud app dashboard, navigate to Runtime on the side menu, and then the Environment variables tab.

7. Add the following environment variables:

• Name: APP_ID, Value: Id copied from app registration success dialog
• Name: APP_SECRET, Value: Secret copied from app registration success dialog
• Name: WEBHOOK_SECRET, Value: Secret copied from webhook registration

Click Save and the app will automatically restart.

8. Once the app has restarted. Navigate back to the Listen to Events page for your app in the Watson Work Services developer experience. Select the Enable button on your webhook.

The button should then turn to Disable if enablement of the webhook was a success.

Now your app is connected to Watson Work Services, and can both post messages and listen to message-created and message-annotation-added events! Let's try it out.

Try out your app in Workspace

After the app is registered and configured to listen to events, we can try it out by adding it to a space in Workspace.

1. Open Watson Workspace in a new tab.

2. Create a new space to add the app to. You can click on the Create a Space button or the + icon next to the Spaces title.

3. Click on the space name at the top to go to the Space Settings panel. From here you can click on the Apps link on the left to view apps to add.

4. Click on the app to add it to the space.

5. Now we can try to interact with the app. First let's send a message to see if the app can echo it back. The app is configured to listen for @gif <keyword | giphy link>. It also parses giphy link in the message, so pasting a giphy.com link would also trigger the app to fetch the gif and post it back in the space.

   Attempt to send in @gif nice job. The app should respond.

   

6. You can also interact the with the app via /commands. The app is registered to listen on /gif keyword | giphy link. Attempt to trigger via /gif awesome

   

Now we have an app that integrates with IBM Watson Workspace & Giphy.com.

Running locally

1. Open a command line (terminal) and change directory to the watsonworkspace-gif directory.
2. Install dependencies by running npm install.
3. Create a .env file per the dotenv instructions in Local Development documentation.
4. Run npm run-script dev from a command line.
5. Copy the URL seen in the Use 'https://cdf9d82f.ngrok.io/<APP_ID>' as your webhook URL in Watson Workspace message for later use.
6. Click the Create new app button on the Developer Apps page.
7. Enter the App Name and the Description of App.
8. Click Create.
9. The next dialog will give you the App ID and App secret. You need to save these values to the respective environment variables in the .env file called APP_ID and APP_SECRET.
10. Click on the Listen to Events link.
11. Click on the Add an outbout webhook button.
12. Give the webhook a name (any name will do) and select any of the events. The message-created and message-annotation-added events are particularly useful.
13. In the Webhook URL text box, specify the URL for your app you copied previously. For example, https://cdf9d82f.ngrok.io/a7cfbdac-cdab-3d6f-ae13-0654b6b8e880.
14. Copy the Webhook secret from the resulting dialog to the WEBHOOK_SECRET property in the .env file.
15. Make a change to index.js and save. This causes the app to restart and load the updated .env file.
16. Back in you browser, select the Enable button to complete the process.
17. Follow the instructions in Share App to add the app to a space.
18. Go write some code!