Integration Engine Documentation

Overview

What is Integration Engine?

The Integration Engine is a comprehensive Spring Boot application that provides advanced OAuth2 and Basic Auth token management with automated refresh capabilities, logging, and flexible configuration options. It enables seamless integration between different systems and APIs with maximum security and performance.

Client Management

Centralized management of OAuth2, Basic Auth, and Bearer Token clients with reusable configurations and flexible settings.

OAuth2 Support

Full OAuth2 implementation with automatic token management, refresh, and multiple grant type support.

Fresh Token Per Call

Advanced feature to get new tokens for every API call, ensuring maximum security for sensitive applications.

Comprehensive Logging

All token activities logged with retry tracking, statistics, and detailed monitoring capabilities.

Health Monitoring

Built-in health checks, statistics, and real-time monitoring for optimal performance and reliability.

RESTful APIs

Complete RESTful API for frontend integration with comprehensive endpoint coverage.

Key Features

OAuth2 Token Management - Complete OAuth2 flow support
Basic Auth Token Management - Username/password authentication
Automated Token Refresh - Background scheduler with configurable intervals
Fresh Token Per Call - Option to get new tokens for every API call
Comprehensive Logging - All token activities logged with retry tracking
Flexible Configuration - Per-client settings with global overrides
Health Monitoring - Built-in health checks and statistics
RESTful APIs - Complete API for frontend integration

Integration Architecture

1

2

3

4

5

Frontend App → Integration Engine → Database → OAuth2 Providers

Quick Start

Getting Started

Follow these steps to quickly set up and start using the Integration Engine with your first client configuration.

1. Start the Application

# Build the application
mvn clean package -DskipTests

# Run the application
java -jar target/integration-engine-1.0.0.jar

2. Verify Health

curl http://localhost:8080/integration-engine/health

3. Create a Client

curl -X POST "http://localhost:8080/integration-engine/api/clients/create?clientName=my-client&clientType=oauth2&clientDescription=My%20OAuth2%20Client"

4. Configure OAuth2

curl -X POST "http://localhost:8080/integration-engine/api/clients/oauth2-config" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "my-client",
    "oauth2ClientId": "your-client-id",
    "oauth2ClientSecret": "your-client-secret",
    "oauth2TokenUrl": "https://api.example.com/oauth/token",
    "oauth2GrantType": "client_credentials",
    "oauth2AutoRefresh": true,
    "oauth2RefreshBeforeExpiry": 300
  }'

5. Test Token Retrieval

# Get a valid token
curl -X GET "http://localhost:8080/integration-engine/api/clients/my-client/oauth2-token/valid"

# Check token statistics
curl -X GET "http://localhost:8080/integration-engine/api/clients/my-client/oauth2-token/statistics"

Important Notes

Ensure your database is running and accessible
Update the OAuth2 configuration with your actual credentials
Check the application logs for any errors
Verify the health endpoint returns "UP" status

Health & Status

Real-time Monitoring

The Integration Engine provides comprehensive health monitoring and status checking capabilities to ensure optimal performance and reliability.

Health Check Endpoints

Endpoint	Method	Description	Response
`/health`	GET	Basic health check	Service status and version
`/health/detailed`	GET	Detailed health information	Database status, configuration details

Health Check Response

Basic Health Check Response:

{
  "service": "Integration Engine",
  "version": "1.0.0",
  "status": "UP",
  "timestamp": "2025-07-18T12:46:27.666663"
}

Detailed Health Check Response:

{
  "status": "UP",
  "details": {
    "service": "Integration Engine",
    "version": "1.0.0",
    "database": "UP",
    "databaseUrl": "jdbc:postgresql://...",
    "timestamp": "2025-07-18T12:56:02.882676"
  }
}

Health Monitoring Features

Service Status

Real-time service availability
Version information
Uptime monitoring
Status indicators

Database Health

Database connectivity status
Connection pool monitoring
Query performance metrics
Error tracking

Frontend Integration

The frontend automatically performs health checks and displays status information:

Automatic Health Checks: Performed on application startup
Status Display: Visual indicators in the UI
Error Handling: Graceful degradation when services are down
Detailed Information: Access to comprehensive health data

Client Management

Key Feature

Client Management allows you to create and manage authentication clients that can be reused across multiple integrations. This eliminates the need to configure OAuth2 settings for each individual integration.

Client Types

OAuth2

Full OAuth2 implementation with support for all major grant types including Client Credentials, Authorization Code, Password Grant, and Implicit Flow.

Basic Auth

Simple username/password authentication for APIs that use Basic Authentication headers.

Bearer Token

Static token authentication for APIs that use Bearer token authorization.

Creating a Client

Step-by-Step Process:

Navigate to Client Management from the main UI
Click Create New Client
Enter client details:
- Client Name: Unique identifier for the client
- Client Type: OAuth2, Basic Auth, or Bearer Token
- Description: Optional description for the client
Click Create Client

OAuth2 Configuration

For OAuth2 clients, you can configure the following settings:

Setting	Description	Required
OAuth2 Client ID	Client identifier from the OAuth2 provider	Yes
OAuth2 Client Secret	Client secret from the OAuth2 provider	Yes
Token URL	URL for obtaining access tokens	Yes
Authorization URL	URL for user authorization (Authorization Code flow)	Conditional
Redirect URI	Callback URL for authorization code flow	Conditional
Grant Type	OAuth2 grant type (client_credentials, authorization_code, password, implicit)	Yes
Scopes	Comma-separated list of OAuth2 scopes	No

Token Management

The system automatically manages OAuth2 tokens with the following features:

Automatic Token Refresh: Tokens are refreshed before expiry
Token Persistence: Tokens are stored securely in the database
Token Validation: Automatic validation of token validity
Error Handling: Graceful handling of token refresh failures

OAuth2 Authentication

Important

OAuth2 authentication is now managed at the client level. Create OAuth2 clients in the Client Management section and select them when configuring integrations.

Supported Grant Types

Client Credentials

Server-to-server authentication using client ID and secret. No user interaction required.

Use case: API-to-API communication

Authorization Code

User authorization flow with redirect to authorization server and callback handling.

Use case: Web applications with user login

Password Grant

Direct username/password authentication with the OAuth2 provider.

Use case: Legacy applications, trusted clients

Implicit Flow

Simplified flow for client-side applications with direct token response.

Use case: Single-page applications

OAuth2 Flow

1

2

3

4

Client Config → Token Request → Token Storage → API Calls

Token Lifecycle

Token Management Process:

Token Acquisition: System requests token from OAuth2 provider
Token Storage: Token is securely stored in database
Token Usage: Token is used for API requests
Token Refresh: Token is automatically refreshed before expiry
Error Recovery: Failed tokens trigger re-authentication

Basic Authentication

Enhanced Basic Auth Support

Basic Authentication now includes comprehensive token management, auto-refresh capabilities, and detailed monitoring features.

Basic Auth Configuration

Setting	Description	Required
Username	API username for authentication	Yes
Password	API password for authentication	Yes
Token URL	URL for obtaining access tokens	Yes
Grant Type	OAuth2 grant type (usually 'password')	Yes
Scope	Comma-separated list of scopes	No
Auto Refresh	Automatically refresh tokens before expiry	No
Refresh Before Expiry	Seconds before expiry to refresh token	No
Persist Tokens	Store tokens in database for persistence	No

Basic Auth APIs

Endpoint	Method	Description
`/api/clients/basic-auth-config`	POST	Save Basic Auth configuration
`/api/clients/{clientName}/basic-auth-config`	GET	Get Basic Auth configuration
`/api/clients/{clientName}/basic-auth-token`	GET	Get Basic Auth token
`/api/clients/{clientName}/basic-auth-token/valid`	GET	Get valid token with auto-refresh
`/api/clients/{clientName}/basic-auth-token/manual`	POST	Manually save token
`/api/clients/{clientName}/basic-auth-token/refresh`	POST	Refresh Basic Auth token
`/api/clients/{clientName}/basic-auth-token/statistics`	GET	Get token statistics
`/api/clients/{clientName}/basic-auth-token/logs`	GET	Get token refresh logs
`/api/clients/basic-auth-tokens/expiring-soon`	GET	Get expiring Basic Auth tokens
`/api/clients/basic-auth-test`	POST	Test Basic Auth connection

Token Management Features

Auto-Refresh

Automatic token refresh before expiry
Configurable refresh timing
Background refresh monitoring
Error recovery mechanisms

Monitoring

Token usage statistics
Refresh success/failure rates
Response time monitoring
Detailed activity logs

Configuration Example

Basic Auth Configuration Request:

{
  "clientId": "my-basic-client",
  "username": "api_user",
  "password": "api_password",
  "tokenUrl": "https://api.example.com/token",
  "grantType": "password",
  "scope": "read write",
  "autoRefresh": true,
  "refreshBeforeExpiry": 300,
  "persistTokens": true
}

Fresh Token Per Call Feature

Advanced Security Feature - Optimized Implementation

The "Fresh Token Per Call" feature allows Basic Auth clients to get a new token for every API call, regardless of whether the current token is still valid. This provides maximum security for sensitive applications with zero database overhead.

🚀 How It Works - Optimized Flow

When `freshTokenPerCall` is set to `true`:

Every API call using Basic Auth for that client will:
- Step 1: Make an OAuth2 request to get a fresh token
- Step 2: Create token object in memory only (NO database save)
- Step 3: Use token immediately for the actual API call
- Step 4: Token is discarded after use
🚫 No database operations: Zero save/delete transactions
🔄 Always fresh: Every single API call gets a brand new token
⚡ No transaction errors: Eliminates "No EntityManager" warnings
🎯 Memory-only tokens: Maximum security with zero persistence

⚙️ Configuration

{
  "clientId": "fresh-token-client",
  "username": "user@example.com",
  "password": "password123",
  "tokenUrl": "https://api.example.com/oauth/token",
  "grantType": "client_credentials", // Recommended for Fresh Token Per Call
  "scope": "email profile",
  "autoRefresh": false,              // Must be false (mutually exclusive)
  "freshTokenPerCall": true,         // 🚀 Enable optimized fresh token per call
  "persistTokens": false             // ⚠️ Ignored when freshTokenPerCall=true
}

Configuration Notes

persistTokens setting is ignored when freshTokenPerCall=true
Tokens are never saved to database regardless of persistTokens value
client_credentials grant type is recommended for better performance
autoRefresh must be false to avoid conflicting behaviors

Validation Rules

Important Validation

The system prevents conflicting configurations:

Cannot enable both autoRefresh and freshTokenPerCall simultaneously
When freshTokenPerCall is true, autoRefresh is automatically set to false
When freshTokenPerCall is true, other token management options are disabled

🔄 Optimized API Flow

Fresh Token Per Call - Zero Database Flow


1. Integration Request
   ↓
2. Check: freshTokenPerCall = true?
   ↓
3. YES → obtainFreshTokenForCall() [OPTIMIZED METHOD]
   ↓ 
4. GET fresh token from OAuth2 provider
   ↓
5. Create token object in MEMORY ONLY (no database save)
   ↓
6. Use token immediately for target API call
   ↓
7. Return API response (token discarded from memory)

Key Optimization Benefits

🚫 Zero Database I/O
No save/delete operations

⚡ No Transaction Errors
Eliminates EntityManager issues

🎯 Memory-Only Processing
Maximum security & performance

Performance Comparison

Feature	`freshTokenPerCall: true`	`freshTokenPerCall: false`
Expiration Check	❌ None	✅ Full checking
Database Operations	🚫 Zero I/O	⚠️ Save/Delete operations
Transaction Errors	✅ Eliminated	⚠️ Possible EntityManager issues
Memory Usage	✅ Memory-only tokens	⚠️ Database persistence
Auto Refresh	➖ Not applicable	✅ Respects setting
Background Refresh	➖ Not applicable	✅ Global scheduler
Performance	⚡ Optimized (no DB I/O)	⚠️ Database overhead
Token Freshness	✅ Always fresh	⚠️ May use cached
OAuth2 Requests	🔥 Every call	🔥 Only when needed
Security	✅ Maximum (zero persistence)	⚠️ Standard (database stored)

🔍 Implementation Details

Optimized Code Methods


// NEW: Optimized method for Fresh Token Per Call
private BasicAuthToken obtainFreshTokenForCall(BasicAuthConfig config) {
    // Get fresh token from OAuth2 provider
    ResponseEntity<Map> response = restTemplate.postForEntity(
        config.getTokenUrl(), request, Map.class);
    
    // Create token object in MEMORY ONLY (no database save)
    return createTokenFromResponse(config.getClientId(), tokenResponse);
}

// Helper method to create token without database operations
private BasicAuthToken createTokenFromResponse(String clientId, 
                                               Map<String, Object> tokenResponse) {
    BasicAuthToken token = new BasicAuthToken();
    token.setClientId(clientId);
    token.setAccessToken((String) tokenResponse.get("access_token"));
    // ... set other fields ...
    return token; // Memory-only object, NOT saved to database
}

📋 Log Messages

How to Verify It's Working


✅ SUCCESS LOGS:
Fresh Token Per Call enabled for client: Planon-Dev - getting fresh token without saving
Fresh Token Per Call: Getting fresh token from: https://api.example.com/oauth/token
Fresh Token Per Call: Successfully obtained fresh token (NOT saving to database)

🚫 NO MORE ERROR LOGS:
❌ Warning: Could not delete existing tokens (ELIMINATED)
❌ No EntityManager with actual transaction available (ELIMINATED)

✅ Use Cases

High-Security Applications

Perfect for applications requiring maximum security where token exposure time must be minimized with zero database overhead.

Financial applications
Healthcare systems
Government applications
Critical infrastructure
NEW: High-volume APIs (no DB bottleneck)

Considerations

Important factors to consider when using Fresh Token Per Call:

Higher OAuth2 provider load
Potential rate limiting
IMPROVED: No more database latency
Higher operational costs

🎯 Database Verification

How to Verify Zero Database Operations

Run multiple API calls and verify that no new tokens are created in the database:


-- Check token count before Fresh Token Per Call testing
SELECT COUNT(*) as token_count, MAX(created_at) as latest_token 
FROM integration_basic_auth_token 
WHERE client_id = 'your-client-id';

-- Result BEFORE: token_count = 3, latest_token = 2025-07-22 13:27:04

-- Make multiple API calls with freshTokenPerCall=true
-- curl -X POST "/api/integrations/execute/YourIntegration" ...

-- Check token count after testing (should be UNCHANGED)
SELECT COUNT(*) as token_count, MAX(created_at) as latest_token 
FROM integration_basic_auth_token 
WHERE client_id = 'your-client-id';

-- Result AFTER: token_count = 3, latest_token = 2025-07-22 13:27:04 (SAME!)

Optimization Summary

🚫 Zero Database I/O
No save/delete operations

⚡ Eliminated Errors
No EntityManager issues

🎯 Memory-Only Tokens
Maximum security

📈 Better Performance
No database overhead

Bearer Token Management

Simple Token Management

Bearer Token authentication provides a simple way to manage static API tokens with automatic validation and monitoring.

Bearer Token APIs

Endpoint	Method	Description
`/api/clients/bearer-token`	POST	Save Bearer token
`/api/clients/{clientName}/bearer-token`	GET	Get Bearer token
`/api/clients/{clientName}/bearer-token`	DELETE	Delete Bearer token

Bearer Token Configuration

Bearer Token Request:

{
  "clientName": "my-bearer-client",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresAt": "2025-12-31T23:59:59Z"
}

Features

Security

Secure token storage
Token validation
Expiry monitoring
Access control

Monitoring

Token usage tracking
Expiry notifications
Access logs
Status indicators

Integration Setup

Creating an Integration

Step-by-Step Process:

Click New in the main interface
Fill in basic integration details:
- Integration ID: Unique identifier
- Name: Descriptive name
- HTTP Method: GET, POST, PUT, DELETE
- URL: Target API endpoint
Configure authentication:
- Select authentication type (Basic, OAuth2)
- For OAuth2: Choose from existing clients or configure manually
Set up payload generation (Template or API)
Configure business rules (JavaScript or Drools)
Define response mappings
Save the integration

Authentication Configuration

OAuth2 Authentication

Select from existing OAuth2 clients
Automatic token management
Support for all grant types
Token refresh and validation

Basic Authentication

Username/password configuration
Automatic header generation
Secure credential storage

Business Rules

Business rules allow you to process API responses and implement custom logic:

JavaScript Rules

Write JavaScript functions to process responses:

function processResponse(response, context) {
    // Transform response here
    response.processed = true;
    response.processedAt = new Date().toISOString();
    return response;
}

Drools Rules

Use Drools rule engine for complex business logic:

$facts.addField("processed", true);
$facts.addField("processedAt", $facts.getCurrentTimestamp());

Response Mapping

Map API responses to your desired format using JsonPath expressions:

Mapping Examples:

$.user.name - Extract user name from response
$.data[*].id - Extract all IDs from data array
$.metadata.total - Extract total count from metadata

Token Management

Advanced Token Management

The Integration Engine provides comprehensive token management with automatic refresh, monitoring, and real-time status tracking for all authentication types.

Auto-Refresh System

Real-time Monitoring

The system automatically monitors and refreshes tokens to ensure continuous API access:

30-second monitoring: Checks token status every 30 seconds
5-minute expiry warning: Refreshes tokens 5 minutes before expiry
Background processing: Non-blocking token refresh operations
Error recovery: Automatic retry mechanisms for failed refreshes

Token Statistics

Performance Metrics

Total token requests
Successful refresh count
Failed refresh count
Average response time
Last refresh timestamp
Next scheduled refresh

Activity Logs

Token refresh attempts
Success/failure events
Error messages and details
Timestamp tracking
Client identification
Response time logging

Token Management APIs

Endpoint	Method	Description	Type
`/api/clients/{clientName}/oauth2-token/valid`	GET	Get valid OAuth2 token with auto-refresh	OAuth2
`/api/clients/{clientName}/oauth2-token/statistics`	GET	Get OAuth2 token statistics	OAuth2
`/api/clients/{clientName}/oauth2-token/logs`	GET	Get OAuth2 token logs	OAuth2
`/api/clients/{clientName}/oauth2-token/manual`	POST	Manually save OAuth2 token	OAuth2
`/api/clients/{clientName}/basic-auth-token/valid`	GET	Get valid Basic Auth token with auto-refresh	Basic Auth
`/api/clients/{clientName}/basic-auth-token/statistics`	GET	Get Basic Auth token statistics	Basic Auth
`/api/clients/{clientName}/basic-auth-token/logs`	GET	Get Basic Auth token logs	Basic Auth
`/api/clients/{clientName}/basic-auth-token/manual`	POST	Manually save Basic Auth token	Basic Auth
`/api/clients/oauth2-tokens/expiring-soon`	GET	Get expiring OAuth2 tokens	OAuth2
`/api/clients/basic-auth-tokens/expiring-soon`	GET	Get expiring Basic Auth tokens	Basic Auth

Manual Token Management

Manually Save OAuth2 Token:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "read write"
}

Manually Save Basic Auth Token:

{
  "accessToken": "basic_auth_token_here",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "read write"
}

Token Monitoring Dashboard

The frontend provides a comprehensive token monitoring dashboard with:

Real-time Status: Live token validity indicators
Expiry Warnings: Visual alerts for expiring tokens
Statistics View: Performance metrics and usage statistics
Activity Logs: Detailed refresh and error logs
Manual Controls: Manual token refresh and management

Configuration Options

Auto-Refresh Settings

Enable/disable auto-refresh
Configure refresh timing
Set retry attempts
Define error thresholds

Persistence Options

Token storage preferences
Log retention settings
Statistics collection
Backup configurations

Database Schema

Database Structure

The Integration Engine uses PostgreSQL to store client configurations, tokens, and logs. Here's the complete database schema with all tables and their relationships.

Core Tables

1. `integration_client`

CREATE TABLE integration_client (
    id BIGSERIAL PRIMARY KEY,
    client_name VARCHAR(255) UNIQUE NOT NULL,
    client_type VARCHAR(50) NOT NULL,
    client_description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2. `integration_oauth2_config`

CREATE TABLE integration_oauth2_config (
    id BIGSERIAL PRIMARY KEY,
    client_name VARCHAR(255) UNIQUE NOT NULL,
    oauth2_client_id VARCHAR(255),
    oauth2_client_secret VARCHAR(255),
    oauth2_token_url VARCHAR(500),
    oauth2_auth_url VARCHAR(500),
    oauth2_grant_type VARCHAR(50),
    oauth2_scopes VARCHAR(255),
    oauth2_redirect_uri VARCHAR(500),
    oauth2_username VARCHAR(255),
    oauth2_password VARCHAR(255),
    oauth2_auto_refresh BOOLEAN DEFAULT FALSE,
    oauth2_refresh_before_expiry INTEGER DEFAULT 300,
    oauth2_persist_tokens BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

3. `integration_basic_auth_config`

CREATE TABLE integration_basic_auth_config (
    id BIGSERIAL PRIMARY KEY,
    client_id VARCHAR(255) UNIQUE NOT NULL,
    username VARCHAR(255),
    password VARCHAR(255),
    token_url VARCHAR(500),
    grant_type VARCHAR(50),
    scope VARCHAR(255),
    auto_refresh BOOLEAN DEFAULT FALSE,
    refresh_before_expiry INTEGER DEFAULT 300,
    persist_tokens BOOLEAN DEFAULT TRUE,
    fresh_token_per_call BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

4. `integration_oauth2_token`

CREATE TABLE integration_oauth2_token (
    id BIGSERIAL PRIMARY KEY,
    client_id VARCHAR(255) NOT NULL,
    access_token TEXT NOT NULL,
    refresh_token TEXT,
    token_type VARCHAR(50),
    expires_in INTEGER,
    scope VARCHAR(255),
    expires_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5. `integration_basic_auth_token`

CREATE TABLE integration_basic_auth_token (
    id BIGSERIAL PRIMARY KEY,
    client_id VARCHAR(255) NOT NULL,
    access_token TEXT NOT NULL,
    token_type VARCHAR(50),
    expires_in INTEGER,
    scope VARCHAR(255),
    expires_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

6. `integration_token_logs`

CREATE TABLE integration_token_logs (
    id BIGSERIAL PRIMARY KEY,
    client_id VARCHAR(255) NOT NULL,
    action VARCHAR(50) NOT NULL,
    status VARCHAR(20) NOT NULL,
    attempt_number INTEGER,
    max_attempts INTEGER,
    error_message TEXT,
    response_time_ms BIGINT,
    token_expires_at TIMESTAMP,
    refresh_triggered_at TIMESTAMP,
    refresh_completed_at TIMESTAMP,
    refresh_before_expiry_seconds INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Database Migration Scripts

Add Fresh Token Per Call Column

-- add_fresh_token_column.sql
ALTER TABLE integration_basic_auth_config
ADD COLUMN fresh_token_per_call BOOLEAN DEFAULT FALSE;

UPDATE integration_basic_auth_config
SET fresh_token_per_call = FALSE
WHERE fresh_token_per_call IS NULL;

Rename Tables (if needed)

-- rename_tables.sql
ALTER TABLE basic_auth_configs RENAME TO integration_basic_auth_config;
ALTER TABLE basic_auth_tokens RENAME TO integration_basic_auth_token;

Table Relationships

Database Schema Relationships

integration_client (1) ←→ (1) integration_oauth2_config

integration_client (1) ←→ (1) integration_basic_auth_config

integration_oauth2_config (1) ←→ (N) integration_oauth2_token

integration_basic_auth_config (1) ←→ (N) integration_basic_auth_token

integration_oauth2_config (1) ←→ (N) integration_token_logs

integration_basic_auth_config (1) ←→ (N) integration_token_logs

Key Fields

Table	Key Field	Description
`integration_client`	`client_name`	Unique identifier for each client
`integration_oauth2_config`	`client_name`	References integration_client.client_name
`integration_basic_auth_config`	`client_id`	References integration_client.client_name
`integration_oauth2_token`	`client_id`	References integration_oauth2_config.client_name
`integration_basic_auth_token`	`client_id`	References integration_basic_auth_config.client_id
`integration_token_logs`	`client_id`	References client configurations

API Reference

Client Management APIs

Endpoint	Method	Description
`/api/clients`	GET	Get all clients
`/api/clients/oauth2`	GET	Get OAuth2 clients only
`/api/clients/create`	POST	Create new client
`/api/clients/{clientName}`	DELETE	Delete client
`/api/clients/{clientName}/oauth2-config`	GET	Get OAuth2 configuration
`/api/clients/oauth2-config`	POST	Save OAuth2 configuration
`/api/clients/{clientName}/oauth2-token`	GET	Get OAuth2 token
`/api/clients/{clientName}/oauth2-token/refresh`	POST	Refresh OAuth2 token
`/api/clients/oauth2-test`	POST	Test OAuth2 connection

Enhanced Integration APIs

Endpoint	Method	Description
`/api/integrations/configurations`	GET	Get all integration configurations
`/api/integrations/configurations/{integrationId}`	GET	Get specific integration configuration
`/api/integrations/configurations`	POST	Create new integration configuration
`/api/integrations/configurations/{integrationId}`	PUT	Update integration configuration
`/api/integrations/configurations/{integrationId}`	DELETE	Delete integration configuration
`/api/integrations/configurations/validate`	POST	Validate integration configuration
`/api/integrations/execute/{integrationId}`	POST	Execute integration (template mode)
`/api/integrations/execute-js/{integrationId}`	POST	Execute integration (JavaScript mode)
`/api/integrations/validate-context-script`	POST	Validate context builder script
`/api/integrations/test-payload-api`	POST	Test payload API configuration
`/api/integrations/validate-payload-api`	POST	Validate payload API configuration
`/api/integrations/data/{integrationId}`	GET	Get integration execution data

Enhanced OAuth2 APIs

Endpoint	Method	Description
`/api/clients/{clientName}/oauth2-token/valid`	GET	Get valid OAuth2 token with auto-refresh
`/api/clients/{clientName}/oauth2-token/statistics`	GET	Get OAuth2 token statistics
`/api/clients/{clientName}/oauth2-token/logs`	GET	Get OAuth2 token logs
`/api/clients/{clientName}/oauth2-token/manual`	POST	Manually save OAuth2 token
`/api/clients/oauth2-tokens/expiring-soon`	GET	Get expiring OAuth2 tokens

Examples & Use Cases

Real-World Examples

Explore practical examples and use cases for different scenarios and requirements.

Use Case 1: High-Security Application

Maximum Security with Fresh Token Per Call

Requirement: Maximum security with fresh tokens for every API call

Configuration:

{
  "clientId": "high-security-client",
  "username": "user@example.com",
  "password": "password123",
  "tokenUrl": "https://api.example.com/oauth/token",
  "grantType": "password",
  "scope": "read write",
  "autoRefresh": false,
  "freshTokenPerCall": true,
  "persistTokens": true
}

Behavior:

Every API call gets a fresh token
No token caching
Maximum security
Higher latency

Use Case 2: Performance-Critical Application

Best Performance with Smart Token Caching

Requirement: Best performance with smart token caching

Configuration:

{
  "clientId": "performance-client",
  "username": "user@example.com",
  "password": "password123",
  "tokenUrl": "https://api.example.com/oauth/token",
  "grantType": "password",
  "scope": "read write",
  "autoRefresh": true,
  "refreshBeforeExpiry": 300,
  "persistTokens": true,
  "freshTokenPerCall": false
}

Behavior:

Cached tokens with expiration checking
Automatic background refresh
Best performance
Standard security

Use Case 3: Manual Control Application

Manual Token Refresh Control

Requirement: Manual token refresh control

Configuration:

{
  "clientId": "manual-client",
  "username": "user@example.com",
  "password": "password123",
  "tokenUrl": "https://api.example.com/oauth/token",
  "grantType": "password",
  "scope": "read write",
  "autoRefresh": false,
  "persistTokens": true,
  "freshTokenPerCall": false
}

Behavior:

Cached tokens with expiration checking
No background refresh
Manual refresh when needed
Good performance

Complete Integration Example

End-to-End Integration Setup

1. Create Client:

curl -X POST "http://localhost:8080/integration-engine/api/clients/create?clientName=my-integration&clientType=basic&clientDescription=My%20Integration%20Client"

2. Configure Basic Auth:

curl -X POST "http://localhost:8080/integration-engine/api/clients/basic-auth-config" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "my-integration",
    "username": "user@example.com",
    "password": "password123",
    "tokenUrl": "https://api.example.com/oauth/token",
    "grantType": "password",
    "scope": "read write",
    "autoRefresh": true,
    "refreshBeforeExpiry": 300,
    "persistTokens": true,
    "freshTokenPerCall": false
  }'

3. Execute Integration:

curl -X POST "http://localhost:8080/integration-engine/api/integrations/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "my-integration",
    "context": {
      "param1": "value1",
      "param2": "value2"
    },
    "authType": "basic",
    "basicUsername": "my-integration"
  }'

4. Monitor Token Status:

# Get current token
curl -X GET "http://localhost:8080/integration-engine/api/clients/my-integration/basic-auth-token"

# Get token statistics
curl -X GET "http://localhost:8080/integration-engine/api/clients/my-integration/basic-auth-token/statistics"

# Get token logs
curl -X GET "http://localhost:8080/integration-engine/api/clients/my-integration/basic-auth-token/logs"

OAuth2 Client Configuration Example

Salesforce OAuth2 Client Setup:

Create OAuth2 client named "salesforce-client"
Configure OAuth2 settings:
- Client ID: Your Salesforce Connected App Client ID
- Client Secret: Your Salesforce Connected App Client Secret
- Token URL: https://login.salesforce.com/services/oauth2/token
- Grant Type: client_credentials
- Scopes: api, refresh_token
Test the connection
Use this client in multiple Salesforce integrations

Business Rule Examples

Data Transformation

function processResponse(response, context) {
    // Transform API response
    if (response.success) {
        response.data = {
            id: response.id,
            status: 'created',
            timestamp: new Date().toISOString()
        };
    }
    return response;
}

Error Handling

function processResponse(response, context) {
    if (response.error) {
        response.processed = false;
        response.errorMessage = response.error.message;
    } else {
        response.processed = true;
    }
    return response;
}

JavaScript Context Building

Context Builder Script Example:

function buildContext(initialContext) {
    // Add computed fields
    initialContext.timestamp = new Date().toISOString();
    initialContext.requestId = generateUUID();
    
    // Transform data
    if (initialContext.user) {
        initialContext.userId = initialContext.user.id;
        initialContext.userEmail = initialContext.user.email;
    }
    
    // Add business logic
    if (initialContext.amount > 1000) {
        initialContext.requiresApproval = true;
        initialContext.approvalLevel = 'senior';
    }
    
    return initialContext;
}

Token Management Examples

Get Valid Token

// Get valid OAuth2 token with auto-refresh
const response = await fetch('/api/clients/myclient/oauth2-token/valid');
const token = await response.json();

// Use token in API calls
const apiResponse = await fetch('/api/integrations/execute/my-integration', {
    headers: {
        'Authorization': `Bearer ${token.accessToken}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(context)
});

Token Statistics

// Get token statistics
const stats = await fetch('/api/clients/myclient/oauth2-token/statistics?hours=24');
const statistics = await stats.json();

console.log('Total requests:', statistics.totalRequests);
console.log('Successful refreshes:', statistics.successfulRefreshes);
console.log('Average response time:', statistics.averageResponseTime);

Health Monitoring Examples

Health Check Implementation:

// Check service health
const healthResponse = await fetch('/health');
const health = await healthResponse.json();

if (health.status === 'UP') {
    console.log('Service is healthy:', health.service, health.version);
} else {
    console.error('Service is down:', health);
}

// Get detailed health information
const detailedHealth = await fetch('/health/detailed');
const details = await detailedHealth.json();
console.log('Database status:', details.details.database);

Troubleshooting

Common Issues

OAuth2 Token Issues

Problem: OAuth2 tokens are not being obtained or refreshed properly.

Solutions:

Verify OAuth2 client configuration (Client ID, Secret, Token URL)
Check grant type compatibility with your OAuth2 provider
Ensure scopes are correctly configured
Test OAuth2 connection in Client Management

Integration Execution Failures

Problem: Integrations are failing to execute.

Solutions:

Check API endpoint URL and HTTP method
Verify authentication configuration
Review business rules for syntax errors
Check response mappings for valid JsonPath expressions

Client Management Issues

Problem: Unable to create or manage clients.

Solutions:

Ensure client names are unique
Check database connectivity
Verify all required fields are filled
Check application logs for detailed error messages

Token Management Issues

Problem: Tokens are not refreshing automatically or showing errors.

Solutions:

Check auto-refresh settings in client configuration
Verify token expiry times and refresh timing
Review token logs for specific error messages
Test manual token refresh functionality
Check network connectivity to token endpoints

Health Check Issues

Problem: Health checks are failing or showing service as down.

Solutions:

Check database connectivity and credentials
Verify application configuration
Review detailed health endpoint for specific issues
Check system resources (CPU, memory, disk)
Verify network connectivity to external services

JavaScript Context Building Issues

Problem: Context builder scripts are failing or producing errors.

Solutions:

Validate context builder script syntax
Check for undefined variables or properties
Test script with sample data
Review error logs for specific JavaScript errors
Ensure proper return statement in context builder function

Debugging Tips

Enable Debug Logging:

Add the following to your application.properties:

logging.level.com.integrateit.engine=DEBUG
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate.SQL=DEBUG

Getting Help

Support Resources

Check application logs for detailed error messages
Use the test functionality in Client Management
Validate integration configurations before saving
Review OAuth2 provider documentation for specific requirements

Summary

Integration Engine Overview

The Integration Engine provides a comprehensive solution for OAuth2 and Basic Auth token management with advanced features for maximum security and performance.

Key Features Summary

Security Features

OAuth2 Token Management - Complete OAuth2 flow support
Basic Auth Token Management - Username/password authentication
Fresh Token Per Call - Maximum security option
Token Encryption - Secure token storage
Comprehensive Logging - All activities tracked

Performance Features

Automated Token Refresh - Background scheduler
Smart Caching - Configurable token persistence
Health Monitoring - Real-time status checks
Statistics & Analytics - Performance insights
RESTful APIs - Complete API coverage

Configuration Options

Feature	Description	Default
Auto Refresh	Automatically refresh tokens before expiry	false
Refresh Before Expiry	Seconds before expiry to refresh token	300
Persist Tokens	Save tokens to database for reuse	true
Fresh Token Per Call	Get new token for every API call	false

Use Case Recommendations

High Security

Use: freshTokenPerCall: true

Financial applications
Healthcare systems
Government applications

High Performance

Use: autoRefresh: true

High-traffic applications
Real-time systems
Performance-critical APIs

Manual Control

Use: autoRefresh: false

Development environments
Testing scenarios
Manual token management

Getting Started

Choose the configuration that best fits your security requirements vs performance needs! 🔒⚡

Start with the Quick Start guide
Configure your first client using Client Management
Set up OAuth2 or Basic Auth authentication
Choose between Fresh Token Per Call or Smart Caching
Monitor performance using Health & Status endpoints
Review Examples & Use Cases for best practices

Important Notes

Backward Compatibility: All existing configurations continue to work
Validation: System prevents conflicting settings automatically
Monitoring: Use health checks and logs for troubleshooting
Security: Choose Fresh Token Per Call for maximum security
Performance: Use Smart Caching for better performance

Overview

What is Integration Engine?

Client Management

OAuth2 Support

Fresh Token Per Call

Comprehensive Logging

Health Monitoring

RESTful APIs

Key Features

Integration Architecture

Quick Start

Getting Started

1. Start the Application

2. Verify Health

3. Create a Client

4. Configure OAuth2

5. Test Token Retrieval

Important Notes

Health & Status

Real-time Monitoring

Health Check Endpoints

Health Check Response

Basic Health Check Response:

Detailed Health Check Response:

Health Monitoring Features

Service Status

Database Health

Frontend Integration

Client Management

Key Feature

Client Types

OAuth2

Basic Auth

Bearer Token

Creating a Client

Step-by-Step Process:

OAuth2 Configuration

Token Management

OAuth2 Authentication

Important

Supported Grant Types

Client Credentials

Authorization Code

Password Grant

Implicit Flow

OAuth2 Flow

Token Lifecycle

Token Management Process:

Basic Authentication

Enhanced Basic Auth Support

Basic Auth Configuration

Basic Auth APIs

Token Management Features

Auto-Refresh

Monitoring

Configuration Example

Basic Auth Configuration Request:

Fresh Token Per Call Feature

Advanced Security Feature - Optimized Implementation

🚀 How It Works - Optimized Flow

When freshTokenPerCall is set to true:

⚙️ Configuration

Configuration Notes

Validation Rules

Important Validation

🔄 Optimized API Flow

Fresh Token Per Call - Zero Database Flow

Key Optimization Benefits

Performance Comparison

🔍 Implementation Details

Optimized Code Methods

📋 Log Messages

How to Verify It's Working

✅ Use Cases

High-Security Applications

Considerations

🎯 Database Verification

How to Verify Zero Database Operations

Optimization Summary

Bearer Token Management

When `freshTokenPerCall` is set to `true`:

1. `integration_client`

2. `integration_oauth2_config`

3. `integration_basic_auth_config`

4. `integration_oauth2_token`

5. `integration_basic_auth_token`

6. `integration_token_logs`