For the past year, the Enterprise Collaboration team have been studying and building the capacity to integrate intelligent assistants or bots into SAP Jam Collaboration. It’s been our focus to understand how we can enable developers to build bots that enrich the user’s experience and make them more productive.
This year we saw the first public example of a bot deployed to SAP Jam Collaboration. SAP Learning Hub is an online training and enablement solution that offers easy access to SAP Education content. SAP Learning Hub offers social learning rooms where students can ask questions and learn from each other, these rooms are powered by SAP Jam groups specific to learning topics. The SAP Learning Hub team recently built a chatbot that acts as a smart group moderator which monitors and answers forum questions. Using SAP Cloud Platform, SAP Leonardo Machine Learning, and SAP Jam Collaboration APIs they enhanced customer response times and reduced the load on human moderators to answer frequently asked questions.
In this blog, I’m going to guide developers through understanding what an SAP Jam bot is, and show them how to build one.
What is an SAP Jam Bot?
The key to understanding what bots can do in SAP Jam is to understand that they are just users who are controlled by AI-powered applications instead of real people. They have the same rights as regular users and depending on the sophistication of the AI act like intelligent end users and group moderators. They can be used to automate the tasks you might give to an actual human user.
An SAP Jam bot consists of four key elements:
The Bot App
SAP Jam bot interfaces can integrate with any web application available on the public internet. For the bot to fully interact with SAP Jam, the application needs to be able to call its OData REST API, and it must be able to send webhook calls to a web/HTTP interface for the bot.
Alias User
An alias user account is used to represent the bot inside SAP Jam. The SAP Jam administrators guide describes alias accounts thus:
“An alias user account enables employees to easily identify a point of contact for specific interaction. For example, for new hire employees of a large, global organization, it is easier to contact a user named "HR Helpdesk" with HR related questions than it is to find out the name of the exact person.”
SAP Jam Admin Guide - Alias Accounts
These alias accounts can be driven by actual users, or they can be connected to bots who act on their behalf. Alias accounts have all the same characteristics as other users in SAP Jam. They have profile images, they show up in the directory, they can be @mentioned, they can be invited to groups, and even be group administrators. In almost every way they are just like other users.
Alias User OAuth Token
In order to connect an alias account to a bot, we need to do two things. First, we need to allow the bot application to call the SAP Jam REST API on behalf of the Alias user. The REST API uses OAuth 2.0 for authorization of all calls. The authorization and identity of the alias user are stored in an OAuth 2.0 token for that alias user. Once you have that token and transfer it to the bot you can call the API on behalf of that user.
SAP Jam Collaboration OData REST API reference documentation
Push Notification Subscriptions
The second step in connecting the alias user account to the bot is to connect the user to a push notification subscription (webhook). What this means is that we need to proactively reach out to the bot when things pertaining to the alias user occur in SAP Jam. For example, if someone asks the bot a question, invites them to a group, or @mentions them we need to notify the bot right away so it can respond using the REST API and token mentioned above.
SAP Jam Collaboration Push notifications for webhooks tutorials
In later blog posts, we will walk you through building our bot and writing some code, but for this post, we will just talk about pseudo code and the steps to configure SAP Jam to interact with our Bot.
The Bot
Any web application on the internet running on any cloud platform can interact with SAP Jam as a Bot, but there are some advantages of using SAP platforms and infrastructure. We won’t go into details now but building a Bot on SAP Cloud Platform using Node and Cloud Foundry is a good start. I may even post a Java sample using SAP Cloud Platform on Neo. Most of the Bots I see are generally built on Node so that’s not a bad place to start.
Get an SAP Jam development system
There is a great blog that walks you through getting a development instance to work with. I suggest you visit this blog to get a free developer trial instance of SAP Jam on SAP Cloud Platform.
How to get a developer edition tenant of SAP Jam
Once you have your SAP Jam instance you can follow these instructions to setup up your bot.
Create an OAuth Client
To call the SAP Jam REST API, you first need to create an OAuth Client in the administration console.
Navigate to the cog icon at the top right of your screen. Click on it and then select “Admin”.
On the admin page in the left-hand menu select Integrations, and then select OAuth Clients. On the subsequent page, you will see a link to “Add OAuth Client”.
After clicking on that link, you will be prompted to fill out a form with information about your application. Give it a name and provide it with a URL that references your bot. You can put anything as long as it is a valid URL with an HTTP/s reference. Save the client.
You will want to record the OAuth Client Id. This will be required for your bot to call the REST API along with the OAuth token we will get in the next step.
Create an Alias Account
On the same admin page select “Users” and then “Alias Accounts” in the left-hand menu.
Create a new alias account by pressing the “New Alias Account” button.
Give the alias account a name, a description, and an avatar just like you would your own user account. This will be the persona of your bot. Once you have saved that information scroll down to the API Access section of the account and press “Add OAuth2 Access Token”
You will then be prompted to select the OAuth Client you created in the previous step. Press Ok. You will be presented with the token. This is the OAuth 2.0 access token you will need to call the SAP Jam REST API. Together with the OAuth Client key and the token, this will allow you to call the API on behalf of the alias account we just created.
Create a Push Notification Subscription
Again, on the Admin page in the Integrations section select “Push Notifications”. As the page describes:
Create a new subscription by pressing the “Push Notification Subscription” button.
Fill in the form with the metadata regarding your bot. The Callback URL is the URL your application will accept HTTP requests containing event updates from SAP Jam. For your application to ensure that the requests are coming from your instance of SAP Jam, each webhook will contain the token shown in the screenshot. You should update your bot with this token to ensure you can trust webhook updates.
The next option is to select the scope of the push notification. We provide Group, Alias Account, and Company scope options.
Group scope allows you to select a specified group. All the events that happen in that group can be selected be sent to your bot. For example, you can use this to monitor all the content creation in a specific group regardless of who creates the content. This is great for adding workflow processes to groups.
Company scope webhooks are things that happen outside of groups. There are a limited number of webhooks for this scope but they include things like people updating their profiles and updating their status. These webhooks are great for updating gamification systems on the progress of users updating their profile.
Alias Account scope is the scope which is needed for bot workflows. With Alias account scope, you connect your alias account to the push notification subscription. This allows you to select notifications that are specific to the notifications and content the Alias account has access to. You can configure the subscription so that whenever your bot receives an @mention request, a group invite, or a SAP Jam message they will be notified. Your bot would then use the REST API to respond or accept the group invite.
If a bot is a full member of a group they can also receive all the group content, group notifications, and group forum webhooks for the groups they are members of. Group membership is how you can restrict or open the scope of notifications your bot has access to. The LearningHub bot I mentioned at the beginning of this blog uses this scope.
After you have selected the scope you need to select the specific web hooks your bot wants to listen too. This ensures your bot doesn’t receive updates for events your bot has not been coded to handle.
Here is an example of what the JSON body of one of the webhooks looks like.
Here you can see that the user Hughie posted a new message into an existing message thread with another user. The bot received this event because it is monitoring the “Message_received” webhook. You can also see the verification token attached so we can verify the sender of the webhook is our SAP Jam tenant.
In Review
In a series of upcoming posts, members of the Enterprise collaboration team will post more about building bots for SAP Jam. Here is a sample of some of the topics we plan to cover:
We have been excited to see what our partners and customers have already started to build. We look forward to seeing what the community brings us in the future. If you have any question about bots and SAP Jam please feel free to reach out to me and the Enterprise Collaboration team at SAP to learn more.
This year we saw the first public example of a bot deployed to SAP Jam Collaboration. SAP Learning Hub is an online training and enablement solution that offers easy access to SAP Education content. SAP Learning Hub offers social learning rooms where students can ask questions and learn from each other, these rooms are powered by SAP Jam groups specific to learning topics. The SAP Learning Hub team recently built a chatbot that acts as a smart group moderator which monitors and answers forum questions. Using SAP Cloud Platform, SAP Leonardo Machine Learning, and SAP Jam Collaboration APIs they enhanced customer response times and reduced the load on human moderators to answer frequently asked questions.
In this blog, I’m going to guide developers through understanding what an SAP Jam bot is, and show them how to build one.
What is an SAP Jam Bot?
The key to understanding what bots can do in SAP Jam is to understand that they are just users who are controlled by AI-powered applications instead of real people. They have the same rights as regular users and depending on the sophistication of the AI act like intelligent end users and group moderators. They can be used to automate the tasks you might give to an actual human user.
An SAP Jam bot consists of four key elements:
- A web application acting as a Bot user in SAP Jam
- An Alias user to represent the Bot in SAP Jam
- An OAuth token with which to call the SAP Jam REST API on behalf of the Alias user
- A Push Notification subscription to update the bot when relevant events happen in SAP Jam.
The Bot App
SAP Jam bot interfaces can integrate with any web application available on the public internet. For the bot to fully interact with SAP Jam, the application needs to be able to call its OData REST API, and it must be able to send webhook calls to a web/HTTP interface for the bot.
Alias User
An alias user account is used to represent the bot inside SAP Jam. The SAP Jam administrators guide describes alias accounts thus:
“An alias user account enables employees to easily identify a point of contact for specific interaction. For example, for new hire employees of a large, global organization, it is easier to contact a user named "HR Helpdesk" with HR related questions than it is to find out the name of the exact person.”
SAP Jam Admin Guide - Alias Accounts
These alias accounts can be driven by actual users, or they can be connected to bots who act on their behalf. Alias accounts have all the same characteristics as other users in SAP Jam. They have profile images, they show up in the directory, they can be @mentioned, they can be invited to groups, and even be group administrators. In almost every way they are just like other users.
Alias User OAuth Token
In order to connect an alias account to a bot, we need to do two things. First, we need to allow the bot application to call the SAP Jam REST API on behalf of the Alias user. The REST API uses OAuth 2.0 for authorization of all calls. The authorization and identity of the alias user are stored in an OAuth 2.0 token for that alias user. Once you have that token and transfer it to the bot you can call the API on behalf of that user.
SAP Jam Collaboration OData REST API reference documentation
Push Notification Subscriptions
The second step in connecting the alias user account to the bot is to connect the user to a push notification subscription (webhook). What this means is that we need to proactively reach out to the bot when things pertaining to the alias user occur in SAP Jam. For example, if someone asks the bot a question, invites them to a group, or @mentions them we need to notify the bot right away so it can respond using the REST API and token mentioned above.
SAP Jam Collaboration Push notifications for webhooks tutorials
Building our first Bot – A walk-through
In later blog posts, we will walk you through building our bot and writing some code, but for this post, we will just talk about pseudo code and the steps to configure SAP Jam to interact with our Bot.
The Bot
Any web application on the internet running on any cloud platform can interact with SAP Jam as a Bot, but there are some advantages of using SAP platforms and infrastructure. We won’t go into details now but building a Bot on SAP Cloud Platform using Node and Cloud Foundry is a good start. I may even post a Java sample using SAP Cloud Platform on Neo. Most of the Bots I see are generally built on Node so that’s not a bad place to start.
Get an SAP Jam development system
There is a great blog that walks you through getting a development instance to work with. I suggest you visit this blog to get a free developer trial instance of SAP Jam on SAP Cloud Platform.
How to get a developer edition tenant of SAP Jam
Once you have your SAP Jam instance you can follow these instructions to setup up your bot.
Create an OAuth Client
To call the SAP Jam REST API, you first need to create an OAuth Client in the administration console.
Navigate to the cog icon at the top right of your screen. Click on it and then select “Admin”.
On the admin page in the left-hand menu select Integrations, and then select OAuth Clients. On the subsequent page, you will see a link to “Add OAuth Client”.
After clicking on that link, you will be prompted to fill out a form with information about your application. Give it a name and provide it with a URL that references your bot. You can put anything as long as it is a valid URL with an HTTP/s reference. Save the client.
You will want to record the OAuth Client Id. This will be required for your bot to call the REST API along with the OAuth token we will get in the next step.
Create an Alias Account
On the same admin page select “Users” and then “Alias Accounts” in the left-hand menu.
Create a new alias account by pressing the “New Alias Account” button.
Give the alias account a name, a description, and an avatar just like you would your own user account. This will be the persona of your bot. Once you have saved that information scroll down to the API Access section of the account and press “Add OAuth2 Access Token”
You will then be prompted to select the OAuth Client you created in the previous step. Press Ok. You will be presented with the token. This is the OAuth 2.0 access token you will need to call the SAP Jam REST API. Together with the OAuth Client key and the token, this will allow you to call the API on behalf of the alias account we just created.
Create a Push Notification Subscription
Again, on the Admin page in the Integrations section select “Push Notifications”. As the page describes:
“Push notification subscriptions are a mechanism for capturing events that occur in SAP Jam and sending them to bots or 3rd-party applications.”
Create a new subscription by pressing the “Push Notification Subscription” button.
Fill in the form with the metadata regarding your bot. The Callback URL is the URL your application will accept HTTP requests containing event updates from SAP Jam. For your application to ensure that the requests are coming from your instance of SAP Jam, each webhook will contain the token shown in the screenshot. You should update your bot with this token to ensure you can trust webhook updates.
The next option is to select the scope of the push notification. We provide Group, Alias Account, and Company scope options.
Group scope allows you to select a specified group. All the events that happen in that group can be selected be sent to your bot. For example, you can use this to monitor all the content creation in a specific group regardless of who creates the content. This is great for adding workflow processes to groups.
Company scope webhooks are things that happen outside of groups. There are a limited number of webhooks for this scope but they include things like people updating their profiles and updating their status. These webhooks are great for updating gamification systems on the progress of users updating their profile.
Alias Account scope is the scope which is needed for bot workflows. With Alias account scope, you connect your alias account to the push notification subscription. This allows you to select notifications that are specific to the notifications and content the Alias account has access to. You can configure the subscription so that whenever your bot receives an @mention request, a group invite, or a SAP Jam message they will be notified. Your bot would then use the REST API to respond or accept the group invite.
If a bot is a full member of a group they can also receive all the group content, group notifications, and group forum webhooks for the groups they are members of. Group membership is how you can restrict or open the scope of notifications your bot has access to. The LearningHub bot I mentioned at the beginning of this blog uses this scope.
After you have selected the scope you need to select the specific web hooks your bot wants to listen too. This ensures your bot doesn’t receive updates for events your bot has not been coded to handle.
Here is an example of what the JSON body of one of the webhooks looks like.
{
"@sapjam.hub.verificationToken": "Redacted rl4s3bcVoAUN7EMJrEH1",
"@sapjam.hub.challenge": "XUxfgEs55xwxeWMNXDoxk2",
"value": [
{
"@sapjam.event.categories": [
"message_received"],
"@sapjam.event.timestamp": "2018-02-26T19:35:03Z", "@sapjam.event.actor": {
"@sapjam.event.entityType": "Member", "Id": "meiPP8nn4kMAfxrwOpAcMq",
"FullName": "Hughie",
"Email": ""
},
"@sapjam.event.feedEntry": null,
"@sapjam.event.group": null,
"@sapjam.event.entityType": "Message",
"Id": "qvARzq8L5ptet2A00WUGeH",
"Text": "Detected this intent from your message: get-learning-plan",
"MessageType": "Text",
"MessageThread": {
"@sapjam.event.entityType": "MessageThread",
"Id": "g9qZFRdZnIdBgPkLG4oDqO",
"Subject": null,
"ThreadScope": "single_member"
}
}
]
}Here you can see that the user Hughie posted a new message into an existing message thread with another user. The bot received this event because it is monitoring the “Message_received” webhook. You can also see the verification token attached so we can verify the sender of the webhook is our SAP Jam tenant.
In Review
In a series of upcoming posts, members of the Enterprise collaboration team will post more about building bots for SAP Jam. Here is a sample of some of the topics we plan to cover:
- Business use cases for SAP Jam bots
- Using the SAP Jam message cards to format chat bot output
- SAP Jam messages formatting options
- The SAP Jam Hughbot plugin
- Using Recast to build SAP Jam messages
- Building SAP Jam bot SSO to third-party application
We have been excited to see what our partners and customers have already started to build. We look forward to seeing what the community brings us in the future. If you have any question about bots and SAP Jam please feel free to reach out to me and the Enterprise Collaboration team at SAP to learn more.
- SAP Managed Tags:
3 Comments
