Trace ID Helper Lite - Short Integration Guide
1. Summary
Trace ID Helper Lite is a reusable OutSystems Reactive Web component that generates and displays a unique support Trace ID. Users can copy the Trace ID and share it with support, QA, development, or SRE teams for troubleshooting.
Example Trace ID:
TRACE-EMPLOYEEPORTAL-UAT-20260712-153022-A7F4
2. Component Details
Component Name: Trace ID Helper Lite
Module Name: TraceIDHelperLite
Public Block: TraceIDHelper
Server Action: GenerateTraceID
Demo Screen: TraceIDHelperDemo
Database Required: No
Target App Type: Reactive Web App
3. What the Trace ID Contains
Recommended format:
{Prefix}-{AppKey}-{EnvironmentKey}-{Date}-{Time}-{RandomCode}
Example:
Meaning:
TRACE = Prefix
EMPLOYEEPORTAL = Application key
UAT = Environment key
20260712 = Date
153022 = Time
A7F4 = GUID-based random code
4. Key Features
- Auto-generate Trace ID
- Display passed Trace ID
- Server-side GUID-based random code
- AppKey and EnvironmentKey support
- Custom prefix support
- Copy Trace ID to clipboard
- Regenerate Trace ID
- Display modes: Card, Badge, Inline, Floating
- Floating positions: TopLeft, TopRight, BottomLeft, BottomRight
- Lightweight and no database required
5. Block Inputs
AppKey: Application key. Example: EMPLOYEEPORTAL
EnvironmentKey: Environment key. Example: UAT
TracePrefix: Prefix for Trace ID. Example: TRACE or ERR
TraceID: Existing Trace ID. If blank and AutoGenerate is True, a new Trace ID is generated.
DisplayMode: Card, Badge, Inline, Floating
Position: TopLeft, TopRight, BottomLeft, BottomRight
ShowCopyButton: Shows Copy action
ShowRefreshButton: Shows Regenerate action
AutoGenerate: Generates Trace ID automatically when TraceID is blank
6. Integration Steps
Step 1: Add Dependency
In the consumer app, open Manage Dependencies and add TraceIDHelper from TraceIDHelperLite.
Step 2: Create Site Properties
Create these Site Properties in the consumer app:
AppKey: Text
EnvironmentKey: Text
AppKey = EMPLOYEEPORTAL
EnvironmentKey = UAT
Step 3: Place the Block
Place TraceIDHelper on an error screen, support screen, debug page, footer, or failure message section.
Step 4: Configure Inputs
Recommended setup:
AppKey = Site.AppKey
EnvironmentKey = Site.EnvironmentKey
TracePrefix = "TRACE"
TraceID = ""
DisplayMode = "Card"
Position = "BottomRight"
ShowCopyButton = True
ShowRefreshButton = True
AutoGenerate = True
7. Recommended Runtime Flow
If TraceID is provided:
Use the passed TraceID.
If TraceID is blank and AutoGenerate is True:
Call GenerateTraceID server action and assign the output to CurrentTraceID.
If Copy is clicked:
Copy CurrentTraceID to clipboard and show Copied message.
If Regenerate is clicked:
Call GenerateTraceID again and update CurrentTraceID.
8. Common Usage Examples
Error Screen:
TracePrefix = "ERR"
ShowRefreshButton = False
Footer Badge:
DisplayMode = "Badge"
Floating Debug Widget:
TracePrefix = "SUPPORT"
DisplayMode = "Floating"
9. Testing Checklist
- Trace ID generates when AutoGenerate = True
- Passed TraceID displays correctly
- Copy button copies Trace ID
- Regenerate button creates a new Trace ID
- Trace ID includes prefix, app key, environment key, timestamp, and random code
- Card, Badge, Inline, and Floating modes work
- Floating positions work correctly
- Empty AppKey falls back to APP
- Empty EnvironmentKey falls back to DEV
- Empty TracePrefix falls back to TRACE
10. Best Practices
- Use Site.AppKey and Site.EnvironmentKey
- Use uppercase app and environment values
- Use ERR prefix on error screens
- Use TRACE prefix for general support IDs
- Use Card mode for error screens
- Use Badge or Inline mode for compact layouts
- Avoid storing sensitive data in Trace ID
- Do not include username, email, phone, session token, or customer ID