BPMCore Activities API

The Activities API provides comprehensive audit trail and activity logging functionality. It tracks user actions, system events, and transaction history across the BankLingo platform, enabling compliance monitoring, security audits, and user behavior analysis.

Base Endpoint

The Activities API uses a different endpoint pattern than other BPMCore APIs:

GET /api/Activities/loggedinuseractivities
GET /api/Activities

Note: This API uses REST GET endpoints rather than the command-based POST pattern used by other BPMCore APIs.

Endpoints

1. Get Logged-In User Activities

Retrieves activity logs for the currently authenticated user.

Endpoint: GET /api/Activities/loggedinuseractivities

Query Parameters

Parameter	Type	Required	Description
startDate	string	No	Filter by activity date start (YYYY-MM-DD)
endDate	string	No	Filter by activity date end (YYYY-MM-DD)
activityType	string	No	Filter by activity type (Login, Transaction, etc.)
pageNumber	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (default: 20)

Request Example

GET /api/Activities/loggedinuseractivities?startDate=2024-01-01&endDate=2024-01-31&pageNumber=1&pageSize=50
Authorization: Bearer <your-jwt-token>

Response Structure

{
  "data": [
    {
      "Id": 1001,
      "UserId": 12345,
      "UserName": "jane.doe@banklingo.com",
      "ActivityType": "Login",
      "ActivityDescription": "User logged in successfully",
      "IpAddress": "192.168.1.100",
      "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0",
      "Timestamp": "2024-01-20T09:15:30",
      "EntityType": null,
      "EntityId": null,
      "EntityReference": null,
      "Success": true,
      "ErrorMessage": null
    },
    {
      "Id": 1002,
      "UserId": 12345,
      "UserName": "jane.doe@banklingo.com",
      "ActivityType": "Transaction",
      "ActivityDescription": "Created deposit account",
      "IpAddress": "192.168.1.100",
      "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0",
      "Timestamp": "2024-01-20T09:20:15",
      "EntityType": "Deposit",
      "EntityId": 54321,
      "EntityReference": "DEP-2024-00123",
      "Success": true,
      "ErrorMessage": null
    },
    {
      "Id": 1003,
      "UserId": 12345,
      "UserName": "jane.doe@banklingo.com",
      "ActivityType": "Transaction",
      "ActivityDescription": "Attempted loan disbursement",
      "IpAddress": "192.168.1.100",
      "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0",
      "Timestamp": "2024-01-20T10:05:00",
      "EntityType": "Loan",
      "EntityId": 67890,
      "EntityReference": "LN-2024-00456",
      "Success": false,
      "ErrorMessage": "Insufficient funds in disbursement account"
    }
  ],
  "totalRows": 150,
  "totalPages": 3,
  "pageSize": 50,
  "currentPage": 1,
  "hasNext": true,
  "hasPrevious": false
}

Response Fields

Field	Type	Description
Id	long	Activity log ID
UserId	long	ID of the user who performed the action
UserName	string	Username/email of the user
ActivityType	string	Type of activity (Login, Transaction, Export, etc.)
ActivityDescription	string	Detailed description of the activity
IpAddress	string	IP address of the user
UserAgent	string	Browser/client user agent string
Timestamp	datetime	When the activity occurred
EntityType	string	Type of entity affected (Client, Loan, Deposit, etc.)
EntityId	long	ID of the affected entity (null if not applicable)
EntityReference	string	Human-readable reference for the entity
Success	boolean	Whether the activity completed successfully
ErrorMessage	string	Error details if Success = false

---

2. Get Activities (All Users)

Retrieves activity logs for all users. Typically restricted to administrators.

Endpoint: GET /api/Activities

Query Parameters

Parameter	Type	Required	Description
userId	long	No	Filter by specific user ID
userName	string	No	Filter by username/email
startDate	string	No	Filter by activity date start (YYYY-MM-DD)
endDate	string	No	Filter by activity date end (YYYY-MM-DD)
activityType	string	No	Filter by activity type
entityType	string	No	Filter by entity type
entityId	long	No	Filter by specific entity ID
success	boolean	No	Filter by success status (true/false)
ipAddress	string	No	Filter by IP address
pageNumber	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (default: 20)

Request Example

GET /api/Activities?startDate=2024-01-01&endDate=2024-01-31&activityType=Transaction&success=false&pageNumber=1&pageSize=100
Authorization: Bearer <your-jwt-token>

Response Structure

Same as loggedinuseractivities, but includes activities from all users.

---

Activity Types

System Activity Types

Type	Description	Examples
Login	User authentication	Successful login, failed login attempt, logout
Transaction	Banking transactions	Deposits, withdrawals, transfers, loan disbursements
Create	Entity creation	New client, new account, new loan
Update	Entity modification	Account updates, profile changes
Delete	Entity deletion	Account closure, record deletion
Export	Data export	Report generation, data exports
Import	Data import	Bulk uploads, file imports
Approval	Approval workflows	Loan approval, transaction authorization
Configuration	System configuration	Settings changes, product configuration
Security	Security events	Password changes, role assignments

Entity Types

Activities can be associated with various entity types:

• Client
• Loan
• Deposit
• Policy (Insurance)
• Terminal
• User
• Branch
• Product
• Transaction
• Report

---

Common Use Cases

Example 1: User Login History

Track login attempts for a specific user:

GET /api/Activities?userId=12345&activityType=Login&startDate=2024-01-01&endDate=2024-01-31
Authorization: Bearer <token>

Example 2: Failed Transaction Audit

Identify failed transactions for investigation:

GET /api/Activities?activityType=Transaction&success=false&startDate=2024-01-01&pageSize=100
Authorization: Bearer <token>

Example 3: Entity Change History

Track all activities related to a specific loan:

GET /api/Activities?entityType=Loan&entityId=67890
Authorization: Bearer <token>

Example 4: Security Audit - Suspicious IPs

Monitor activities from specific IP addresses:

GET /api/Activities?ipAddress=192.168.1.100&startDate=2024-01-01&endDate=2024-01-31
Authorization: Bearer <token>

Example 5: User Activity Report

Generate activity report for a user:

GET /api/Activities/loggedinuseractivities?startDate=2024-01-01&endDate=2024-01-31&pageSize=1000
Authorization: Bearer <token>

---

Audit Trail Scenarios

Compliance Monitoring

Scenario: Regulatory audit requires proof of user actions

GET /api/Activities?userId=12345&activityType=Transaction&startDate=2023-01-01&endDate=2023-12-31&pageSize=10000

Result: Complete transaction history for compliance documentation

Security Investigation

Scenario: Suspicious activity detected from unusual IP

GET /api/Activities?ipAddress=203.0.113.45&startDate=2024-01-20

Result: All activities from the suspicious IP for security analysis

Performance Analysis

Scenario: Identify peak usage times

GET /api/Activities?startDate=2024-01-01&endDate=2024-01-31&activityType=Login&pageSize=5000

Result: Login patterns for capacity planning

Error Analysis

Scenario: Troubleshoot recurring transaction failures

GET /api/Activities?success=false&activityType=Transaction&startDate=2024-01-15&pageSize=500

Result: Failed transaction details for error resolution

---

Integration Notes

Automatic Activity Logging

The BankLingo platform automatically logs activities for:

• User authentication (login, logout, password changes)
• All financial transactions
• Entity creation, updates, and deletions
• Report generation and data exports
• Administrative actions
• Approval workflow actions

Custom Activity Logging

Applications can also log custom activities using internal APIs (not exposed via BPMCore).

Activity Retention

• Activities are typically retained indefinitely for compliance
• May be subject to data archival policies
• Soft-delete mechanisms may apply for user privacy requests

Performance Considerations

• Use date range filters to limit result sets
• Consider pagination for large datasets
• Activities table can grow very large; indexes are critical
• Export functionality may be rate-limited

---

Security & Access Control

Authorization Levels

Endpoint	Required Permission	Scope
/loggedinuseractivities	Authenticated User	Own activities only
/api/Activities	Administrator	All user activities

Sensitive Data

Activities may contain:

• IP addresses (for security analysis)
• User agent strings (for device tracking)
• Entity references (for context)
• Error messages (may contain sensitive details)

Privacy Considerations

• Comply with data protection regulations (GDPR, NDPR, etc.)
• Implement data retention policies
• Provide data export mechanisms for user requests
• Support right-to-erasure where applicable

---

Response Headers

Both endpoints include standard pagination headers:

X-Total-Count: 150
X-Page-Number: 1
X-Page-Size: 50
X-Total-Pages: 3

---

Error Responses

Unauthorized Access

{
  "statusCode": 401,
  "message": "Unauthorized. Please authenticate.",
  "timestamp": "2024-01-20T10:30:00"
}

Forbidden (Insufficient Permissions)

{
  "statusCode": 403,
  "message": "Forbidden. You do not have permission to view all user activities.",
  "timestamp": "2024-01-20T10:30:00"
}

Invalid Date Range

{
  "statusCode": 400,
  "message": "Invalid date range. Start date must be before end date.",
  "timestamp": "2024-01-20T10:30:00"
}

---

Best Practices

For Developers

1. Date Range Filters: Always use date filters to limit result sets
2. Pagination: Implement proper pagination for large datasets
3. Error Handling: Handle failed activity lookups gracefully
4. Caching: Consider caching for frequently accessed activity summaries
5. Rate Limiting: Respect rate limits for high-volume queries

For Administrators

1. Regular Audits: Schedule periodic security audits
2. Failed Login Monitoring: Set up alerts for multiple failed logins
3. Anomaly Detection: Monitor for unusual activity patterns
4. Data Exports: Regularly export audit logs for compliance
5. Retention Policy: Implement and enforce data retention policies

For Compliance

1. Complete Audit Trail: Ensure all critical actions are logged
2. Tamper-Proof: Activity logs should be immutable
3. Long-Term Storage: Retain logs per regulatory requirements
4. Access Controls: Restrict who can view sensitive activity data
5. Regular Reviews: Periodically review activity logs for compliance

---

Related APIs

• Comments API - User-added notes and comments
• User Management - User account operations
• Transaction History - Financial transaction details

---

Documentation Author: Owa Oluwasegun Tunbosun, Senior Platform Engineer