GoodBooks GB5 — EIP & DirectAction Developer Reference

System Overview

The GB5 backend provides two complementary integration platforms for external actors to interact with the ERP:

Both platforms share the Action Pipeline (TEVENTACTIONRUN → TACTIONOUTBOX → Dapr pub/sub → EmailActionHandler) for outbound notification delivery.

Architecture Map

EIP Conversational Engine

Every inbound message goes through a 6-phase sequential pipeline. Each phase produces a result consumed by the next. If any phase fails, the request is terminated with an error response.

The orchestrator is EIPConversationEngine.ProcessIncomingMessageAsync(). All phases receive the same EIPExecutionContextDTO, which accumulates state across phases.

Phase 1 — Channel Normalization

File: FrameworkBLL/EIPConversation/EIPHandlers/EIPEngine/ChannelNormalizer/EIPChannelNormalizer.cs

Converts vendor-specific webhook payloads into the internal EIPExecutionContextDTO.

EIPChannelType enum

Phase 2 — Routing Engine

File: FrameworkBLL/EIPConversation/EIPHandlers/EIPEngine/RoutingEngine/EIPRoutingEngine.cs

Loads active rules from MEIPROUTINGRULE, ordered by PRIORITY ascending (lower number = higher priority). Rules are matched in priority order; first match wins.

Phase 3 — Flow Engine

File: FrameworkBLL/EIPConversation/EIPHandlers/EIPEngine/FlowEngine/EIPFlowEngine.cs

Executes the flow definition loaded from MEIPFLOWDEFINITION.JSONDEFINITION. The engine loops through steps (max 50 iterations — prevents infinite loops) dispatching to registered step handlers.

Flow Definition JSON Structure

{
  "FlowCode": "LEAVE_REQUEST",
  "StartStepCode": "GREETING",
  "Steps": {
    "GREETING": {
      "StepType": "MESSAGE",
      "MessageTemplate": "Hello {CustomerName}! I can help with your leave request. Type 'start' to begin.",
      "NextStepCode": "COLLECT_DATES"
    },
    "COLLECT_DATES": {
      "StepType": "INPUT",
      "MessageTemplate": "Please enter your leave start date (YYYY-MM-DD):",
      "ContextKey": "LeaveStartDate",
      "Validation": { "Required": true, "Pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
      "NextStepCode": "COLLECT_REASON"
    },
    "COLLECT_REASON": {
      "StepType": "CHOICE",
      "MessageTemplate": "What type of leave is this?",
      "Choices": {
        "1. Annual Leave":  "CONFIRM_ANNUAL",
        "2. Sick Leave":    "CONFIRM_SICK",
        "3. Unpaid Leave":  "CONFIRM_UNPAID"
      }
    },
    "CONFIRM_ANNUAL": {
      "StepType": "CONDITION",
      "ConditionExpression": "confirm",
      "NextStepCode": "SUBMIT_LEAVE"
    },
    "SUBMIT_LEAVE": {
      "StepType": "ACTION",
      "ActionType": "CALL_API",
      "ApiConfig": {
        "Endpoint": "/Leave/SaveLeave",
        "Method": "POST",
        "Body": "{\"LeaveType\": 1, \"StartDate\": \"{LeaveStartDate}\", \"UserId\": \"{UserId}\"}"
      },
      "ContextKey": "SubmitResult",
      "NextStepCode": "DONE"
    },
    "DONE": {
      "StepType": "END",
      "MessageTemplate": "Your leave has been submitted successfully! Reference: {SubmitResult}"
    }
  }
}

Execution Rules

• Pause steps: MESSAGE, PROMPT, INPUT, CHOICE always pause — the engine saves session and waits for the next message. DYNAMIC_CHOICE (first visit), LOCATION (awaiting location) also pause.
• Continue steps: CONDITION, CONDITIONAL, ACTION, CAPABILITY, EXTERNAL_ACTION, QUALIFY, ENRICH, LINK, PRESENT — run synchronously without waiting for user input.
• End: When NextStepCode is null/empty or step type is END, the flow completes and the session is expired.
• Variable substitution: Any {Key} in MessageTemplate or action Body is replaced from context.Variables. Dot-notation supported: {VarKey.SubKey} — if VarKey holds a JSON object string, SubKey is extracted from the root.

All Step Types

CONDITIONAL Step — Operators

Example: CONDITIONAL Step

{
  "StepType": "CONDITIONAL",
  "ConditionKey": "RiskScore",
  "Conditions": [
    { "Operator": "GT", "Value": "80", "NextStepCode": "HIGH_RISK_BLOCK" },
    { "Operator": "GT", "Value": "50", "NextStepCode": "MEDIUM_RISK_OTP" }
  ],
  "DefaultNextStepCode": "LOW_RISK_PROCEED"
}

Phase 4 — Capability Engine

File: FrameworkBLL/EIPConversation/EIPHandlers/EIPEngine/CapabilityEngine/EIPCapabilityEngine.cs

Only invoked for CAPABILITY steps. Sequence:

1. Risk Assessment — EIPRiskAssessment.EvaluateRiskAsync(). Returns risk level + RequiresOtp flag. Currently: keyword "PAYMENT" → HIGH risk.
2. OTP Generation (if high risk) — EIPOtpService.GenerateOtpAsync(). Currently logs a 6-digit code only; no DB persistence yet.
3. Action Context Build — wraps CapabilityCode + context variables into EIPActionContextDTO with IdempotencyKey = CorrelationId.
4. Action Executor — routes to IEIPActionExecutor.ExecuteAsync().

Phase 5 — Action Engine

File: FrameworkBLL/EIPConversation/EIPHandlers/EIPEngine/ActionEngine/EIPActionEngine.cs

Handler factory: case-insensitive dictionary of IEIPActionHandler keyed by ActionCode.

CRUD_OPERATION Payload Example

// Flow step ApiConfig:
{
  "Endpoint": "/Leave/SaveLeave",
  "Method": "POST",
  "Body": "{\"LeaveType\": 1, \"StartDate\": \"{LeaveStartDate}\"}"
}

// Handler resolves:
// SysJobSettings:ServiceBaseUrl + Endpoint = full URL
// Variables already substituted before handler call

Phase 6 — Response Engine

File: FrameworkBLL/EIPConversation/EIPHandlers/EIPEngine/ResponseEngine/EIPResponseEngine.cs

Sequence:

1. Rate limit check — in-memory ConcurrentDictionary keyed "CHANNEL:RECIPIENT". 2-second window per recipient. Drops message silently if too frequent (protects downstream providers).
2. Handler selection — looks up IEIPChannelHandler by channel name (case-insensitive). Throws if no handler registered.
3. Delivery — calls handler.SendAsync(context, login, ct).
4. Metadata update — records last sent time, recipient, channel, response status on context for audit.

Response Fields

The following fields are present on EIPFlowExecutionResultDTO, EIPExecutionResultDTO, and (where applicable) EIPChatMessageDTO to support extended channel capabilities introduced by the PRESENT, LOCATION, LINK, and Voice step types.

Session State

Table: TEIUSERSESSION  |  DAL: EIPSessionDAL

Sessions enable multi-turn conversations. The engine restores session before Phase 2, upserts after Phase 3 if paused, and expires on flow completion.

Session Lifecycle

Multi-Turn Conversation Example

This traces a 3-turn leave request conversation, showing exact DB state at each turn.

Turn 1 — User sends "start leave"

POST /EIPConversation/Receive
{ "message": "start leave", "tenantId": "42", "channelType": 1,
  "userIdentifier": "+9715551234" }

Phase 2: MEIPROUTINGRULE matches STARTS_WITH "start" → FlowCode="LEAVE_REQUEST"
Phase 3: Starts at "GREETING" (MESSAGE step) → pauses
Session saved: CurrentStepCode="COLLECT_DATES", FlowCode="LEAVE_REQUEST",
               ContextJson="{}"

Response: "Hello! I can help with your leave request..."

Turn 2 — User sends "2024-07-15"

POST /EIPConversation/Receive
{ "message": "2024-07-15", "tenantId": "42", "channelType": 1,
  "userIdentifier": "+9715551234" }

Session restored: CurrentStepCode="COLLECT_DATES"
Phase 3: INPUT step validates "2024-07-15" against pattern "^\d{4}-\d{2}-\d{2}$" → valid
         Stores Variables["LeaveStartDate"] = "2024-07-15"
         Moves to COLLECT_REASON (CHOICE step) → pauses
Session saved: CurrentStepCode="COLLECT_REASON",
               ContextJson="{\"LeaveStartDate\":\"2024-07-15\"}"

Response: "What type of leave? 1.Annual 2.Sick 3.Unpaid"

Turn 3 — User sends "1"

POST /EIPConversation/Receive
{ "message": "1", "tenantId": "42", "channelType": 1,
  "userIdentifier": "+9715551234" }

Session restored: CurrentStepCode="COLLECT_REASON", Variables={"LeaveStartDate":"2024-07-15"}
Phase 3: CHOICE "1" matches "1. Annual Leave" → NextStepCode="CONFIRM_ANNUAL"
         CONFIRM_ANNUAL (ACTION/CALL_API) → POST /Leave/SaveLeave (no pause)
         Returns result → DONE (END step) → sends final message
Session expired: STATUS=0

Response: "Your leave has been submitted! Reference: LV-2024-001"

Channel Handlers

WhatsApp — Retry Policy

Polly exponential backoff: 3 retries with delays of 2s, 4s, 8s. Dual provider selection via MessageHubSettings:Celitix:Enable and MessageHubSettings:WhatsApp:Enable in appsettings.

Qualifier & Mapper Integration

QUALIFY Step

The QUALIFY step calls IQualifierFacadeImpl.ExecuteStageAsync() to run a named qualifier stage against input data assembled from context variables.

Execution Context Built by the Step Handler

var ctx = new QualifierExecutionContext
{
    ClientId      = login.ClientId,
    EntityId      = qualifyConfig.EntityId,           // optional numeric entity PK
    EntityCode    = qualifyConfig.BoundToType,         // qualifier bound-to type code
    Stage         = qualifyConfig.Stage,               // e.g., "VALIDATE_ADDRESS"
    Scope         = qualifyConfig.Scope,               // optional scope tag
    Document      = JsonDocument.Parse(inputsJson),    // JSON built from InputKeys[]
    CorrelationId = context.CorrelationId
};

Result Handling

• If QualifierResult.IsSuccess == false — the engine routes to OnValidationErrorStepCode and sets context.Variables["_QualifyError"] to the first Error finding's message.
• If IsSuccess == true — QualifierResult.Facts.ExportAll() is serialized as JSON and stored in context.Variables[OutputFactKey].
• If MapperCode is set — IMappingEngineBLL.TransformAsync(MapperCode, factsJson, login, ct) is called and the result is stored in context.Variables[OutputMapKey].

ENRICH Step

The ENRICH step calls IMappingEngineBLL.TransformAsync() directly, without a qualifier stage:

var transformed = await _mappingEngine.TransformAsync(
    enrichConfig.MapperCode,
    context.Variables[enrichConfig.InputKey],
    login,
    ct);
context.Variables[enrichConfig.OutputKey] = transformed;

Dependency Injection

Structured Data & PRESENT Step

EIPStructuredDataDTO

The PRESENT step parses JSON from a context variable and produces an EIPStructuredDataDTO, which is placed on the flow execution result and forwarded to the channel handler.

EIPResponseFormatDTO — Step Configuration

Defined inside the PRESENT step's flow JSON under ResponseFormat:

EIPTextFormatter — Plain-Text Fallback

File: FrameworkBLL/EIPConversation/EIPHandlers/EIPEngine/FlowEngine/EIPTextFormatter.cs

EIPTextFormatter.FormatAsText(EIPStructuredDataDTO data) converts structured data to a plain-text string for channels that cannot render native structured output (WhatsApp, SMS):

• TABLE / CARD: Each row is rendered as *Label*: value\n blocks, with rows separated by ---.
• LIST: Each row is rendered as a numbered list: 1. value\n, 2. value\n, etc.
• If IsTruncated is true, appends (Showing N of M) to the end of the output.

WhatsApp and SMS channel handlers call EIPTextFormatter.FormatAsText() automatically when context.StructuredData != null. AppChat receives the full EIPStructuredDataDTO object for native rendering.

QR Code & Location

QR Code Generation

When a step sets QrCodeData on the execution result, each channel handler renders it differently:

• WhatsApp: Sends an "image" message type (not "media") with the QR server URL in payload["image"]["link"] (e.g., https://api.qrserver.com/v1/create-qr-code/?data=...).
• Telegram: Calls the sendPhoto Bot API method with the QR server URL as photo.
• AppChat: Receives the raw QrCodeData string and renders a native canvas QR code client-side.
• SMS / Voice: QR code is omitted; a plain-text fallback message is sent instead.

QR Scan Input

For INPUT steps requiring a barcode or QR scan, set Validation.InputType = "qr_scan" in the step definition. This causes the engine to set InputHint = "qr_scan" on the response. The AppChat widget activates the device camera / barcode scanner; when the user scans, the decoded text is sent back as a regular message and processed by the INPUT step validation.

Inbound Location Data

When the channel delivers a location payload, the inbound EIPConversationDTO.Location field is populated as an EIPLocationDTO:

Phase 1 (Channel Normalizer) detects a non-null Location and automatically sets context.Variables["_Location.Lat"], "_Location.Lng", and "_Location.Address" before the flow engine runs.

RequestLocation Rendering per Channel

When the engine sets RequestLocation = true on the response (produced by a LOCATION step on first visit), each channel reacts:

• WhatsApp: Appends a plain-text prompt (e.g., "Please share your location using the attachment button") — WhatsApp Cloud API does not support a native location-request button.
• Telegram: Sends a ReplyKeyboardMarkup with a single button: { text: "📍 Share Location", request_location: true }. Tapping it sends the user's location automatically.
• AppChat: Receives RequestLocation = true in EIPChatMessageDTO; the frontend activates the HTML5 Geolocation API and sends the coordinates back as a location payload.

DirectAction System

DirectAction enables external actors (users in email or WhatsApp) to trigger backend API calls by clicking a link or button — without logging in. The system is stateless (state is in the signed token), one-time-use, and multi-tenant isolated.

Token Format & Security

Payload

payload = "{actionCode}:{contextId}:{tenantId}:{assigneeUserId}:{expiresAtTicks}:{databaseName}"
token   = Base64Url(payload) + "." + Base64Url(HMAC-SHA256(payload, secret))

Example payload (plaintext before encoding):

WORKFLOW_APPROVE:5001:42:99:638501234567890123:goodbooks_prod_42

Example signed token:

V09SS0ZMT1dfQVBQUk9WRTo1MDAx....Ojk5OjYzODUwMTIzNA.xK7f2mNq8...

Security Properties

• HMAC-SHA256 signature — forgery requires the secret key (in HashiCorp Vault in production).
• Fixed-time comparison — CryptographicOperations.FixedTimeEquals prevents timing attacks.
• Expiry enforcement — token rejected if DateTime.UtcNow > expiresAt.
• One-time-use — SHA256(token) stored in TDIRECTACTIONTOKEN on first use; subsequent uses return "Already Actioned".
• Tenant isolation — LoginDTO reconstructed only from token fields; client cannot forge a different tenantId.

Validation Order (failfast)

1. Token is not null/empty
2. Token contains exactly one . separator
3. Base64Url decode succeeds
4. HMAC signature matches (fixed-time compare)
5. Payload has ≥ 6 fields; fields 2–5 parse as int/long
6. DateTime.UtcNow <= expiresAt

NeedsInput=0 Flow (Direct Click)

Used for simple one-click actions: Approve, Return, Forward.

NeedsInput=1 Flow (With Remarks)

Used when the action requires user-provided text (e.g., rejection reason, approval comment).

Why not record the token on the initial GET?

If the token were recorded when the form is shown, any network error, browser back-navigation, or accidental page load would permanently consume the one-time-use slot and the user would see "Already Actioned" if they re-submit. By deferring recording to the POST, the form is safe to reload multiple times.

WhatsApp Button Path

WhatsApp interactive buttons carry a payload string (max 256 chars). DirectAction uses the BUTTONPAYLOADPREFIX pattern to encode the ContextId.

PayloadTemplate Substitution

The PAYLOADTEMPLATE column in MDIRECTACTIONDETAIL is a JSON string with two supported placeholders:

Examples

-- NeedsInput=0: Approve without comments
PAYLOADTEMPLATE = '{"Items":[{"TaskId":{ContextId},"Action":1}]}'
After substitution (ContextId=5001):
  {"Items":[{"TaskId":5001,"Action":1}]}

-- NeedsInput=1: Reject with reason
PAYLOADTEMPLATE = '{"Items":[{"TaskId":{ContextId},"Action":2,"Remarks":"{Remarks}"}]}'
After substitution (ContextId=5001, Remarks="Budget not available"):
  {"Items":[{"TaskId":5001,"Action":2,"Remarks":"Budget not available"}]}

Resend Flow

POST /Action/Resend
Body: { "EventTypeId": 42, "ContextId": 5001 }

→ Publishes new OutboxEvent to TOUTBOX
→ Action pipeline re-executes → new TEVENTACTIONRUN
→ EmailActionHandler generates FRESH tokens (48h from resend time)
→ New email sent with new buttons

Old tokens remain valid until their original 48-hour expiry. The one-time-use check in TDIRECTACTIONTOKEN prevents double-execution — whichever token is clicked first wins. Old tokens can be manually revoked by setting STATUS=2 in TDIRECTACTIONTOKEN.

EIP Database Tables

MEIPFLOWDEFINITION

CREATE TABLE MEIPFLOWDEFINITION (
    FLOWDEFINITIONID  int           NOT NULL PRIMARY KEY,
    TENANTID          int           NOT NULL,
    FLOWCODE          nvarchar(100) NOT NULL,
    FLOWVERSION       int,
    FLOWSTATUS        int,           -- 1=active, 0=archived
    JSONDEFINITION    nvarchar(max), -- full flow JSON (StartStepCode + Steps dict)
    VERSION           int,
    STATUS            int,           -- 1=active (soft delete)
    CREATEDBYID       int,
    CREATEDON         datetime2,
    MODIFIEDBYID      int,
    MODIFIEDON        datetime2,
    CONSTRAINT UX_FLOWCODE UNIQUE (FLOWCODE, TENANTID, STATUS)
);

MEIPROUTINGRULE

CREATE TABLE MEIPROUTINGRULE (
    ROUTINGRULEID     int           NOT NULL PRIMARY KEY,
    TENANTID          int           NOT NULL,
    FLOWDEFINITIONID  int           NOT NULL, -- FK → MEIPFLOWDEFINITION
    ENDPOINTID        int           NOT NULL, -- FK → MEIPCHANNELENDPOINT
    MATCHTYPE         int,          -- 1=EQUALS, 2=STARTS_WITH, 3=CONTAINS, 4=REGEX
    MATCHVALUE        nvarchar(500),
    PRIORITY          int,          -- lower = higher priority
    STATUS            int,          -- 1=active
    VERSION           int,
    CREATEDBYID       int,
    CREATEDUTC        datetime2,
    MODIFIEDBYID      int,
    MODIFIEDUTC       datetime2
);

TEIUSERSESSION

CREATE TABLE TEIUSERSESSION (
    SESSIONID         uniqueidentifier NOT NULL PRIMARY KEY,
    USERIDENTIFIER    nvarchar(255),  -- phone/email/userId
    TENANTID          int,
    CHANNELTYPE       int,            -- EIPChannelType enum value
    FLOWCODE          nvarchar(100),
    CURRENTSTEPCODE   nvarchar(100),
    CONTEXTJSON       nvarchar(max),  -- JSON dict of Variables
    STARTEDAT         datetime2,
    LASTACTIVITYAT    datetime2,      -- 30-min TTL check
    STATUS            int             -- 1=active, 0=expired
);
CREATE INDEX IX_TEIUSERSESSION_LOOKUP
    ON TEIUSERSESSION (USERIDENTIFIER, TENANTID, CHANNELTYPE) WHERE STATUS = 1;

DirectAction Database Tables

MDIRECTACTION (Header)

CREATE TABLE MDIRECTACTION (
    DIRECTACTIONID      int           NOT NULL PRIMARY KEY,
    DIRECTACTIONCODE    nvarchar(20),  -- "WFAPPROVAL", "PO_APPROVAL"
    DIRECTACTIONNAME    nvarchar(200), -- display name
    CONTEXTIDFIELD      nvarchar(200), -- field name in entity payload for the PK
    ASSIGNEEUSERIDFIELD nvarchar(200), -- field name for assignee user ID
    TENANTID            int,           -- -1 = global template
    STATUS              int,
    VERSION             int,
    SORTORDER           int,
    SOURCETYPE          int,
    CREATEDBYID         int,
    CREATEDON           datetime2,
    MODIFIEDBYID        int,
    MODIFIEDON          datetime2
);

MDIRECTACTIONDETAIL (Buttons)

CREATE TABLE MDIRECTACTIONDETAIL (
    DIRECTACTIONDETAILID  int            NOT NULL PRIMARY KEY,
    DIRECTACTIONID        int            NOT NULL,  -- FK → MDIRECTACTION
    SLNO                  smallint,                  -- display order
    ACTIONCODE            nvarchar(20),  -- "WORKFLOW_APPROVE"
    ACTIONLABEL           nvarchar(200), -- "Approve" (shown in form title for NeedsInput=1)
    EMAILPLACEHOLDER      nvarchar(100), -- "APPROVE_URL" → ##APPROVE_URL## in email template
    BUTTONPAYLOADPREFIX   nvarchar(100), -- "WF_APPROVE" → WhatsApp button payload prefix
    APIENDPOINT           nvarchar(500), -- "/WorkFlow/WorkFlowActions"
    HTTPMETHOD            nvarchar(10),  -- "POST", "PUT", "PATCH", "DELETE"
    PAYLOADTEMPLATE       nvarchar(max), -- JSON with {ContextId} and {Remarks}
    NEEDSINPUT            tinyint,       -- 0=direct, 1=show remarks form
    FLOWID                int            -- FK → MEIPFLOWDEFINITION (-1 if N/A)
);

TDIRECTACTIONTOKEN (One-time-use audit)

CREATE TABLE TDIRECTACTIONTOKEN (
    TOKENHASH       nvarchar(64)   NOT NULL PRIMARY KEY,  -- SHA256 hex of signed token
    CONTEXTID       int,
    ACTIONCODE      nvarchar(20),
    ASSIGNEEUSERID  int,
    TENANTID        int,
    EXPIRESAT       datetime,      -- original token expiry (48h from generation)
    USEDAT          datetime,      -- when clicked (NULL = never used / recorded on click)
    STATUS          tinyint,       -- 0=unused, 1=used, 2=revoked
    REMARKS         nvarchar(2000),-- user-provided remarks (NeedsInput=1 only)
    CREATEDON       datetime
);
CREATE INDEX IX_TDIRECTACTIONTOKEN_HASH_TENANT
    ON TDIRECTACTIONTOKEN (TOKENHASH, TENANTID);

Action Pipeline Tables

TEVENTACTIONRUN

-- Tracks execution lifecycle of each triggered action
ACTIONRUNID      int PK       -- app-generated sequence
ACTIONID         int          -- FK → MACTION
TENANTID         int
RUNSTATUS        int          -- 0=Pending, 1=InProgress, 2=Completed, 3=Failed
PAYLOAD          nvarchar(max)-- entity JSON at time of trigger
RESULT           nvarchar(max)-- execution outcome
ERRORMESSAGE     nvarchar(max)
ATTEMPTS         int
CORRELATIONKEY   nvarchar(255)-- for deduplication: ActionId + entity PK

TACTIONOUTBOX

-- Transactional outbox: reliable publish to Dapr/RabbitMQ
OUTBOXID          int PK
TENANTID          int
DESTINATIONTOPIC  nvarchar(100) -- "action-exec-p0" through "action-exec-p4" (tenantId % 5)
PAYLOAD           nvarchar(max) -- ActionEventDto JSON
SENDSTATUS        int           -- 0=Pending, 1=Sent, 2=Failed
ATTEMPTS          int
CREATEDON         datetime2

Edge Cases & Known Issues

QC Test Scenarios

DirectAction — Email Path

DirectAction — WhatsApp Button Path

EIP Conversation Engine

Key File Map

EIP Conversation Engine

Extended EIP DTOs

DirectAction System

GoodBooks GB5 — EIP & DirectAction Developer Reference — generated 2026-06-20