zhongwei/gh-secondsky-sap-skills-skills-sap-btp-build-work-zone-advanced
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:54:49 +08:00
commit 9d01254182
21 changed files with 3697 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
references/chatbots.md Normal file
View File

@@ -0,0 +1,297 @@
# Chatbot Integration Guide
> **⚠️ DEPRECATION NOTICE**: SAP Conversational AI entered maintenance/sunset mode as of January 2023. Functionality may be limited or deprecated. Verify current support status before implementing custom chatbots. See [SAP Product Availability Matrix](https://support.sap.com/en/release-upgrade-maintenance/maintenance-information/product-availability-matrix.html) for lifecycle details. Consider SAP Build Apps or other alternatives for new implementations.
Complete guide for integrating and configuring chatbots in SAP Build Work Zone, advanced edition.
**Source**: [https://github.com/SAP-docs/sap-btp-build-work-zone-advanced/tree/main/docs/50-Chatbots](https://github.com/SAP-docs/sap-btp-build-work-zone-advanced/tree/main/docs/50-Chatbots)
## Table of Contents
- [Overview](#overview)
- [Built-in Capabilities](#built-in-capabilities)
- [Chatbot Types](#chatbot-types)
- [Implementation Process](#implementation-process)
- [Webhook Configuration](#webhook-configuration)
- [Chatbot Actions](#chatbot-actions)
- [Rendering Cards with Chatbots](#rendering-cards-with-chatbots)
- [SAP Conversational AI Integration](#sap-conversational-ai-integration)
- [Chatbot Launcher](#chatbot-launcher)
- [Fallback Handling](#fallback-handling)
- [Troubleshooting](#troubleshooting)
---
## Overview
Chatbots help users accomplish tasks through conversational interaction. They support custom training, actions, and card rendering within SAP Build Work Zone.
## Built-in Capabilities
Default chatbot features include:
- Workspace creation
- Leave request processing
- Business news delivery
- Content searching
- Entertainment (jokes, weather updates)
---
## Chatbot Types
### SAP Build Work Zone Chatbot (Recommended)
Pre-built chatbots with built-in functionalities:
| Variant | Features |
|---------|----------|
| Full-featured | All capabilities enabled |
| Workspace Creation | Workspace management only |
| Business News | News delivery only |
| Search | Content search only |
| Leave Requests | Leave management only |
| Smart Talk | Conversational features |
### Custom Chatbots
Build independent chatbots using SAP Conversational AI platform:
- URL: [https://cai.tools.sap/](https://cai.tools.sap/)
- Custom training and intents
- Organization-specific actions
> **Note**: SAP Conversational AI is in maintenance mode since January 2023. Verify support status before starting new implementations.
---
## Implementation Process
### Step 1: Fork Chatbot Repository
Development begins by copying a base chatbot repository:
- Creates independent branch for customization
- Can fork entire bots or specific intents only
### Step 2: OAuth Registration
Authorize chatbot to access APIs:
1. Navigate to Administration Console
2. Go to External Integrations > OAuth Clients
3. Register client credentials
4. Configure required scopes
### Step 3: Alias Account Setup
Create system user account for chatbot:
1. Go to User Management > Alias Accounts
2. Create new alias account
3. Configure permissions
4. Add OAuth2 Access Token
5. Link token to chatbot
### Step 4: Configure Push Notifications
Set up event-triggered notifications:
| Category | Events |
|----------|--------|
| Alias Account | Account-related events |
| Content | Content creation/modification |
| Workspace | Workspace activities |
| Forum | Discussion events |
---
## Webhook Configuration
Webhooks enable chatbots to invoke SAP Build Work Zone services.
### Webhook URL Format
```
[https://<host-url>/api/v2/ai/webhook](https://<host-url>/api/v2/ai/webhook)
```
Example: `[https://dwpdev1.sapjam-integration.com/api/v2/ai/webhook`](https://dwpdev1.sapjam-integration.com/api/v2/ai/webhook`)
### Authorization
- Add OAuth token from Alias Account in Headers tab
- Token must have appropriate scopes for desired actions
### Available Template Variables
| Variable | Description |
|----------|-------------|
| `{{participant_data.jamId}}` | Current user's Jam/Work Zone ID |
| `{{participant_data.email}}` | Current user's email address |
| `{{conversation_id}}` | Current conversation identifier |
### Payload Structure
All webhook payloads require three mandatory components:
```json
{
"action": "perform_actions",
"context": {
"senderId": "{{participant_data.jamId}}"
},
"parameters": {
// Action-specific parameters
}
}
```
---
## Chatbot Actions
### Supported Actions
| Action | Purpose |
|--------|---------|
| `perform_actions` | Execute platform actions |
| `ui5_card` | Render UI Integration Cards |
| `create_workspace` | Create new workspace |
| `get_workspace_templates` | Retrieve available templates |
### Create Workspace Action
```json
{
"action": "perform_actions",
"context": {
"senderId": "{{participant_data.jamId}}"
},
"parameters": {
"actionName": "create_workspace",
"name": "Workspace Name",
"is_private": false,
"template": "template_id"
}
}
```
| Parameter | Required | Description |
|-----------|----------|-------------|
| actionName | Yes | Fixed: "create_workspace" |
| name | Yes | AI-derived from user input |
| is_private | No | Privacy setting |
| template | No | Template ID to use |
### Get Workspace Templates Action
```json
{
"action": "perform_actions",
"context": {
"senderId": "{{participant_data.jamId}}"
},
"parameters": {
"actionName": "get_workspace_templates"
}
}
```
---
## Rendering Cards with Chatbots
Chatbots can render UI Integration Cards for enhanced user experiences.
### Supported Card Types
- Leave request cards
- Business News cards
- Search result cards
- Custom cards
### Card Setup Process
1. **Upload Card**: Administration Console → UI Integration → Cards & Widgets → Upload Card
2. **Get Card ID**: Copy unique card identifier from Administration Console
3. **Configure Webhook**: Add card ID to chatbot payload
### Card Rendering Payload
```json
{
"action": "ui5_card",
"context": {
"senderId": "{{participant_data.jamId}}"
},
"parameters": {
"cardId": "sap.dwp.test.card.searchResult",
"widgetType": "sapCard"
}
}
```
| Parameter | Required | Values |
|-----------|----------|--------|
| cardId | Yes | Unique card identifier |
| widgetType | No | "sapCard" or "sapWidget" (default) |
---
## SAP Conversational AI Integration
> **Note**: SAP Conversational AI entered maintenance mode in January 2023. This section is provided for existing implementations only.
### Connector Setup
1. Access SAP Conversational AI platform
2. Use built-in "SAP Jam Collaboration" connector
3. Configure connection to SAP Build Work Zone
### Configuration Steps
1. Go to Build > [Your Bot] > Webhook Configuration
2. Enter webhook URL
3. Add OAuth token in Headers
4. Configure payload in Body tab
### Configuration Location
Administration Console > External Integrations > Chatbot Configuration
---
## Chatbot Launcher
### Enabling Chatbot
1. Configure chatbot in Administration Console
2. Enable Chatbot Launcher feature
3. Chatbot icon appears in bottom-right corner
### User Access
- Available on most pages (except Applications page)
- Multiple bots can be configured
- Users select preferred bot from list
### Interface Controls
| Control | Function |
|---------|----------|
| Switch | Change between configured bots |
| Fullscreen | Toggle fullscreen mode |
| Close | Close chatbot window |
| Send | Submit message (Ctrl+Enter / Cmd+Enter) |
---
## Fallback Handling
When chatbot cannot understand a request:
- Returns fallback message
- Indicates incomprehension
- Suggests alternative phrasing
---
**Documentation Links**:
- Chatbots: [https://help.sap.com/docs/build-work-zone-advanced-edition](https://help.sap.com/docs/build-work-zone-advanced-edition)
- SAP Conversational AI: [https://cai.tools.sap/](https://cai.tools.sap/) (sunset/maintenance mode since Jan 2023)
- GitHub: [https://github.com/SAP-docs/sap-btp-build-work-zone-advanced/tree/main/docs/50-Chatbots](https://github.com/SAP-docs/sap-btp-build-work-zone-advanced/tree/main/docs/50-Chatbots)