/sap-btp-build-work-zone-advanced

SAP Build Work Zone API Reference

Complete API reference for SCIM, OData, and Webhook APIs in SAP Build Work Zone, advanced edition.

Source: https://github.com/SAP-docs/sap-btp-build-work-zone-advanced

Table of Contents

• API Documentation Resources
• SCIM API
  • Overview
  • Rate Limits
  • Response Headers
  • Content Type
  • User Filtering
  • SCIM Operations
  • User Lists
  • Maintenance Windows
• OData API
  • Overview
  • Authentication
  • Key Endpoints
  • Query Options
  • Business Records
• Webhooks
  • Overview
  • Webhook URL Format
  • Configuration
  • Event Types
  • Payload Structure
• Chatbot API
  • Available Template Variables
  • Webhook Actions
  • Create Workspace Example
  • Render Card Example
• Authentication
  • OAuth 2.0 Setup
  • Token Request
  • API Request
• Alias Accounts

API Documentation Resources

SCIM API

Overview {#overview-scim}

SAP Build Work Zone implements SCIM 2.0 for user provisioning.

Endpoint: /api/v1/scim

Authentication: 2-legged OAuth using "Workzone API Client"

Rate Limits

Response Headers

Content Type

All POST/PUT requests require:

Content-Type: application/json

User Filtering

Supported filter: SCIM.userName eq <value>

SCIM Operations

User Lists

Maintenance Windows

During maintenance, API returns:

HTTP 503 Service Unavailable

OData API

Overview {#overview-odata}

SAP Build Work Zone uses OData v2 protocol with support for OData v4 query syntax (e.g., advanced $filter, $select expressions).

Protocol: OData v2 (with v4 query operator extensions)

Format: XML (AtomPub) or JSON

Base URL: /api/v1/OData

Authentication {#authentication}

Same OAuth flow as SCIM API.

Key Endpoints

Query Options

Business Records

Configure OData annotations to display external business records:

1. Create OData metadata file with annotations
2. Register in Administration Console
3. Configure display annotations
4. Map to business record types

Webhooks

Overview {#overview-webhooks}

Track platform events and send notifications to external applications.

Webhook URL Format

https://<host-url>/api/v2/ai/webhook

Configuration

1. Register webhook URL in Administration Console
2. Configure events to monitor
3. Set authentication tokens
4. Test webhook delivery

Event Types

Payload Structure

{
  "action": "perform_actions",
  "context": {
    "senderId": "user_id"
  },
  "parameters": {
    // Event-specific parameters
  }
}

Chatbot API

Available Template Variables

When configuring chatbot webhooks, the following template variables are available:

Webhook Actions

Create Workspace Example

{
  "action": "perform_actions",
  "context": { "senderId": "{{participant_data.jamId}}" },
  "parameters": {
    "actionName": "create_workspace",
    "name": "Workspace Name",
    "is_private": false
  }
}

Render Card Example

{
  "action": "ui5_card",
  "context": { "senderId": "{{participant_data.jamId}}" },
  "parameters": {
    "cardId": "sap.card.id",
    "widgetType": "sapCard"
  }
}

Authentication {#authentication-main}

OAuth 2.0 Setup

1. Create OAuth client in Administration Console
2. Configure client credentials grant
3. Obtain access token
4. Include in Authorization header

Token Request

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={client_id}
&client_secret={client_secret}

API Request

GET /api/v1/OData/Groups
Authorization: Bearer {access_token}

Alias Accounts

For system-level API access:

1. Create alias account in Administration Console
2. Navigate to API Access section
3. Add OAuth2 Access Token
4. Select OAuth client
5. Use token for automated API calls

Documentation Links:

• SAP API Hub: https://api.sap.com/
• OData Docs: https://jam2.sapjam.com/work_zone/ODataDocs/ui
• Webhook Reference: https://jam2.sapjam.com/work_zone/ODataDocs/webhook_reference
• SAP Help Portal: https://help.sap.com/docs/build-work-zone-advanced-edition