GoodBooks GB5 — EIP & DirectAction Implementation Guide

What is EIP & DirectAction?

The GB5 Enterprise Integration Platform (EIP) provides two ways for people outside the system to interact with it:

How It Works — Big Picture

Step 1 — Configure MDIRECTACTION (Action Group Header)

MDIRECTACTION defines a group of buttons for a specific business entity. One row per approval scenario.

How to identify CONTEXTIDFIELD and ASSIGNEEUSERIDFIELD

Look at the entity DTO that your BLL publishes when the event fires. The field names must exactly match the JSON property names in the payload.

// Example: PurchaseOrder DTO
public class PurchaseOrderDTO
{
    public int    PurchaseOrderId { get; set; }  ← CONTEXTIDFIELD = "PurchaseOrderId"
    public int    ApproverUserId  { get; set; }  ← ASSIGNEEUSERIDFIELD = "ApproverUserId"
    public string VendorName      { get; set; }
    public decimal TotalAmount    { get; set; }
}

// Seed SQL:
INSERT INTO MDIRECTACTION
    (DIRECTACTIONID, DIRECTACTIONCODE, DIRECTACTIONNAME,
     CONTEXTIDFIELD, ASSIGNEEUSERIDFIELD, TENANTID, STATUS, SORTORDER)
VALUES
    (10, 'PO_APPROVAL', 'Purchase Order Approval',
     'PurchaseOrderId', 'ApproverUserId', 42, 1, 1);

Step 2 — Configure MDIRECTACTIONDETAIL (Action Buttons)

One row per button. All buttons for the same action group share the same DIRECTACTIONID.

Full Example — Purchase Order Approval (3 buttons)

-- Button 1: Approve (direct, no remarks needed)
INSERT INTO MDIRECTACTIONDETAIL
    (DIRECTACTIONDETAILID, DIRECTACTIONID, SLNO, ACTIONCODE, ACTIONLABEL,
     EMAILPLACEHOLDER, BUTTONPAYLOADPREFIX, APIENDPOINT, HTTPMETHOD,
     PAYLOADTEMPLATE, NEEDSINPUT, FLOWID)
VALUES
    (101, 10, 1, 'PO_APPROVE', 'Approve',
     'APPROVE_URL', 'PO_APPROVE', '/PurchaseOrder/ApprovePO', 'POST',
     '{"PurchaseOrderId":{ContextId}}', 0, -1);

-- Button 2: Reject (requires remarks — reason for rejection)
INSERT INTO MDIRECTACTIONDETAIL
    (DIRECTACTIONDETAILID, DIRECTACTIONID, SLNO, ACTIONCODE, ACTIONLABEL,
     EMAILPLACEHOLDER, BUTTONPAYLOADPREFIX, APIENDPOINT, HTTPMETHOD,
     PAYLOADTEMPLATE, NEEDSINPUT, FLOWID)
VALUES
    (102, 10, 2, 'PO_REJECT', 'Reject',
     'REJECT_URL', 'PO_REJECT', '/PurchaseOrder/RejectPO', 'POST',
     '{"PurchaseOrderId":{ContextId},"RejectionReason":"{Remarks}"}', 1, -1);

-- Button 3: Return for Revision (requires comments)
INSERT INTO MDIRECTACTIONDETAIL
    (DIRECTACTIONDETAILID, DIRECTACTIONID, SLNO, ACTIONCODE, ACTIONLABEL,
     EMAILPLACEHOLDER, BUTTONPAYLOADPREFIX, APIENDPOINT, HTTPMETHOD,
     PAYLOADTEMPLATE, NEEDSINPUT, FLOWID)
VALUES
    (103, 10, 3, 'PO_RETURN', 'Return for Revision',
     'RETURN_URL', 'PO_RETURN', '/PurchaseOrder/ReturnPO', 'POST',
     '{"PurchaseOrderId":{ContextId},"Comments":"{Remarks}"}', 1, -1);

PayloadTemplate Cookbook

Step 3 — Email Template Setup (MMAILTEMPLATE)

The email template defines the HTML body of the notification email. Buttons are embedded using the ##PLACEHOLDER## syntax, where PLACEHOLDER matches the EMAILPLACEHOLDER column in MDIRECTACTIONDETAIL.

Token Replacement Rules

• ##APPROVE_URL## → replaced with the full signed URL for the APPROVE button
• ##REJECT_URL## → replaced with the full signed URL for the REJECT button
• ##FieldName## → replaced with the value of FieldName from the entity DTO (e.g., ##VendorName##)
• @Model.FieldName → alternative syntax for entity field replacement

Example Email Template HTML (MMAILTEMPLATE body)

<!DOCTYPE html>
<html><body style="font-family:sans-serif;">
<p>Dear ##ApproverName##,</p>

<p>A Purchase Order requires your approval:</p>
<table border="1" cellpadding="8" style="border-collapse:collapse;">
  <tr><td><b>PO Number</b></td><td>##PurchaseOrderCode##</td></tr>
  <tr><td><b>Vendor</b></td><td>##VendorName##</td></tr>
  <tr><td><b>Amount</b></td><td>##TotalAmount##</td></tr>
  <tr><td><b>Requested By</b></td><td>##RequestedByName##</td></tr>
</table>

<p style="margin-top:24px;">Please take action:</p>

<a href="##APPROVE_URL##"
   style="background:#2e7d32;color:#fff;padding:12px 28px;text-decoration:none;
          border-radius:4px;margin-right:8px;display:inline-block;">
   ✓ Approve
</a>

<a href="##REJECT_URL##"
   style="background:#c62828;color:#fff;padding:12px 28px;text-decoration:none;
          border-radius:4px;margin-right:8px;display:inline-block;">
   ✗ Reject
</a>

<a href="##RETURN_URL##"
   style="background:#e65100;color:#fff;padding:12px 28px;text-decoration:none;
          border-radius:4px;display:inline-block;">
   ↩ Return for Revision
</a>

<p style="font-size:12px;color:#999;margin-top:32px;">
  This link expires in 48 hours. Do not share this email.
</p>
</body></html>

MMAILTEMPLATE Key Columns

Step 4 — Publishing ActionEventDto from Application BLL

The application BLL (e.g., PurchaseOrderBLL) is responsible for publishing the event when the entity is saved. The framework generates tokens and sends the email automatically — but only if the publisher provides the correct fields.

Required Fields in ActionEventDto

Single Approver Pattern

// In PurchaseOrderBLL.SavePurchaseOrder():
var po = await _dal.GetPurchaseOrder(poId, login, ct);

await _daprClient.PublishEventAsync("pubsub", "action-event", new ActionEventDto
{
    DirectActionId = 10,          // MDIRECTACTION.DIRECTACTIONID for PO_APPROVAL
    ContextId      = po.PurchaseOrderId,
    AssigneeUserId = po.ApproverUserId,   // must be from MUSER.USERID
    SendTo         = po.ApproverEmail,    // the approver's email address
    DatabaseName   = login.DatabaseName,
    TenantId       = login.ClientId
});

Pool Approval Pattern (any one of N approvers can act)

// One event per approver — each gets their own signed token
var approvers = await _approvalDAL.GetApprovers(poId, login, ct);
foreach (var approver in approvers)
{
    await _daprClient.PublishEventAsync("pubsub", "action-event", new ActionEventDto
    {
        DirectActionId = 10,
        ContextId      = po.PurchaseOrderId,
        AssigneeUserId = approver.UserId,    // different for each
        SendTo         = approver.Email,
        DatabaseName   = login.DatabaseName,
        TenantId       = login.ClientId
    });
}
// Each approver gets a separate email with their own unique token.
// First to click wins. Others who click later get "Already Actioned" page.
// The API at /PurchaseOrder/ApprovePO must handle idempotent calls gracefully.

When you only have email, not UserId

// Use IUserDAL.GetUserIdByEmailAsync() to resolve
var userId = await _userDAL.GetUserIdByEmailAsync(po.ApproverEmail, login, ct);
// Then use userId in AssigneeUserId above

Step 5 — Routing Rules (MEIPROUTINGRULE)

Routing rules determine which conversation flow is triggered when a user sends a message on WhatsApp, Slack, Teams, etc.

Supported Channel Types

Example Routing Table

Step 6 — Flow Definitions (MEIPFLOWDEFINITION)

Each conversational flow is stored as a single JSON document in MEIPFLOWDEFINITION.JSONDEFINITION. The JSON defines all steps and the transitions between them.

Flow JSON Structure

{
  "FlowCode": "YOUR_FLOW_CODE",
  "StartStepCode": "STEP_NAME_OF_FIRST_STEP",
  "Steps": {
    "STEP_NAME": {
      "StepType": "MESSAGE|INPUT|CHOICE|CONDITIONAL|ACTION|END",
      ... step-specific fields ...
    }
  }
}

Step Type Quick Reference

Variable Substitution

Use {VariableName} anywhere in MessageTemplate or ApiConfig.Body to insert a value the user previously entered. Variables are stored by ContextKey in INPUT steps.

// User answered "John" in an INPUT step with ContextKey="UserName"
// Later:
"MessageTemplate": "Hello {UserName}! Your request has been submitted."
// Renders as: "Hello John! Your request has been submitted."

Complete Example: Purchase Order Approval

This example walks through the full setup for a 3-button email approval flow for Purchase Orders.

What happens end-to-end

1. Purchaser raises a PO → PurchaseOrderBLL.SavePO() publishes an ActionEventDto
2. EmailActionHandler generates 3 signed links (Approve / Reject / Return) and sends the email
3. Approver sees email, clicks "Reject", enters reason in the remarks form
4. System calls POST /PurchaseOrder/RejectPO with the PO ID and reason
5. Approver sees "Action Submitted" confirmation page

Database Setup

-- 1. Action Group Header
INSERT INTO MDIRECTACTION VALUES
  (10, 'PO_APPROVAL', 'Purchase Order Approval',
   'PurchaseOrderId', 'ApproverUserId', 42, 1, 1, GETUTCDATE(), NULL, NULL, GETUTCDATE());

-- 2. Approve button (NeedsInput=0 — one click, no form)
INSERT INTO MDIRECTACTIONDETAIL VALUES
  (101, 10, 1, 'PO_APPROVE', 'Approve',
   'APPROVE_URL', 'PO_APPROVE',
   '/PurchaseOrder/ApprovePO', 'POST',
   '{"PurchaseOrderId":{ContextId}}', 0, -1);

-- 3. Reject button (NeedsInput=1 — shows remarks form)
INSERT INTO MDIRECTACTIONDETAIL VALUES
  (102, 10, 2, 'PO_REJECT', 'Reject Purchase Order',
   'REJECT_URL', 'PO_REJECT',
   '/PurchaseOrder/RejectPO', 'POST',
   '{"PurchaseOrderId":{ContextId},"RejectionReason":"{Remarks}"}', 1, -1);

-- 4. Return button (NeedsInput=1 — shows remarks form)
INSERT INTO MDIRECTACTIONDETAIL VALUES
  (103, 10, 3, 'PO_RETURN', 'Return for Revision',
   'RETURN_URL', 'PO_RETURN',
   '/PurchaseOrder/ReturnPO', 'POST',
   '{"PurchaseOrderId":{ContextId},"Comments":"{Remarks}"}', 1, -1);

Email Template (MMAILTEMPLATE body)

Subject: Action Required: PO ##PurchaseOrderCode## needs your approval

Body:
<p>Dear ##ApproverName##,</p>
<p>PO <b>##PurchaseOrderCode##</b> from vendor <b>##VendorName##</b>
   for amount <b>##TotalAmount##</b> requires your approval.</p>

<a href="##APPROVE_URL##" style="...green button...">✓ Approve</a>
<a href="##REJECT_URL##"  style="...red button...">✗ Reject</a>
<a href="##RETURN_URL##"  style="...orange button...">↩ Return</a>

<p>Links expire in 48 hours.</p>

BLL Publisher Code

// In PurchaseOrderBLL.ApprovePO() — after entity is created:
await _eventPublisher.PublishAsync(new ActionEventDto
{
    DirectActionId = 10,
    ContextId      = po.PurchaseOrderId,
    AssigneeUserId = po.ApproverUserId,
    SendTo         = po.ApproverEmail,
    DatabaseName   = login.DatabaseName,
    TenantId       = login.ClientId
}, login, ct);

What the approver sees

Complete Example: WhatsApp Leave Request Bot

Database Setup

-- Routing rule (WhatsApp channel)
INSERT INTO MEIPROUTINGRULE VALUES
  (1, 42, 5, 1, 2, 'leave', 20, 1, GETUTCDATE(), NULL, GETUTCDATE());
-- MATCHTYPE=2 (STARTS_WITH), MATCHVALUE='leave', PRIORITY=20

-- Flow definition
INSERT INTO MEIPFLOWDEFINITION VALUES
  (5, 42, 'LEAVE_REQUEST', 1, 1, '{ ... JSON below ... }', 1, 1, 1, GETUTCDATE(), NULL, NULL);

Flow JSON (JSONDEFINITION)

{
  "FlowCode": "LEAVE_REQUEST",
  "StartStepCode": "GREETING",
  "Steps": {
    "GREETING": {
      "StepType": "MESSAGE",
      "MessageTemplate": "Hi! I'll help you apply for leave.\nPlease type the start date (YYYY-MM-DD):",
      "NextStepCode": "GET_START_DATE"
    },
    "GET_START_DATE": {
      "StepType": "INPUT",
      "MessageTemplate": "Enter your leave start date:",
      "ContextKey": "LeaveStartDate",
      "Validation": { "Required": true, "Pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
      "NextStepCode": "GET_END_DATE"
    },
    "GET_END_DATE": {
      "StepType": "INPUT",
      "MessageTemplate": "Enter your leave end date:",
      "ContextKey": "LeaveEndDate",
      "Validation": { "Required": true, "Pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
      "NextStepCode": "CHOOSE_TYPE"
    },
    "CHOOSE_TYPE": {
      "StepType": "CHOICE",
      "MessageTemplate": "What type of leave?",
      "Choices": {
        "1. Annual Leave": "CONFIRM",
        "2. Sick Leave":   "CONFIRM",
        "3. Unpaid Leave": "CONFIRM"
      }
    },
    "CONFIRM": {
      "StepType": "MESSAGE",
      "MessageTemplate": "Submitting leave from {LeaveStartDate} to {LeaveEndDate}...",
      "NextStepCode": "SUBMIT"
    },
    "SUBMIT": {
      "StepType": "ACTION",
      "ActionType": "CALL_API",
      "ApiConfig": {
        "Endpoint": "/Leave/SaveLeave",
        "Method": "POST",
        "Body": "{\"StartDate\":\"{LeaveStartDate}\",\"EndDate\":\"{LeaveEndDate}\",\"LeaveType\":1}"
      },
      "ContextKey": "LeaveRef",
      "NextStepCode": "DONE"
    },
    "DONE": {
      "StepType": "END",
      "MessageTemplate": "✅ Leave submitted successfully!\nReference: {LeaveRef}\nYour manager will be notified."
    }
  }
}

Conversation on WhatsApp

QUALIFY Step

Runs a configured qualifier against session context data and routes based on the result. Use QUALIFY to enforce business rules (e.g., credit limit check, duplicate detection) without writing flow-specific API endpoints.

When the qualifier finds Error-severity findings, the engine stores a summary string in _QualifyError and routes to OnValidationErrorStepCode. Use {_QualifyError} in a subsequent MESSAGE step to display the reason to the user.

{
  "StepType": "QUALIFY",
  "BoundToType": "LeaveRequest",
  "InputKeys": ["LeaveStartDate", "LeaveEndDate", "EmployeeId"],
  "OutputFactKey": "QualifyResult",
  "MapperCode": "LEAVE_QUALIFY_MAPPER",
  "OnValidationErrorStepCode": "QUALIFY_ERROR",
  "NextStepCode": "SUBMIT_LEAVE"
},
"QUALIFY_ERROR": {
  "StepType": "MESSAGE",
  "MessageTemplate": "Your leave request cannot be submitted: {_QualifyError}",
  "NextStepCode": "RESTART_OR_EXIT"
}

ENRICH Step

Runs a mapper against a single context variable and stores the transformed output under a new key. Use ENRICH to format, augment, or restructure data collected in earlier steps without calling an external API.

{
  "StepType": "ENRICH",
  "MapperCode": "EMPLOYEE_DETAILS_MAPPER",
  "InputKey": "ScannedEmployeeCode",
  "OutputKey": "EmployeeDetails",
  "NextStepCode": "CONFIRM_EMPLOYEE"
}

DYNAMIC_CHOICE Step

Presents a choice menu where the options are built dynamically from a list stored in the session context (populated by a preceding CALL_API or ACTION step), rather than being hardcoded in the flow JSON.

On first visit the step sends the prompt with the dynamically generated buttons. When the user selects an option, the ValueField of the chosen item is stored in StoreSelectedKey and the flow proceeds to NextStepCode.

{
  "StepType": "DYNAMIC_CHOICE",
  "MessageTemplate": "Select the project to log time against:",
  "SourceKey": "ActiveProjects",
  "DataPath": "Data.Projects",
  "LabelField": "ProjectName",
  "ValueField": "ProjectId",
  "StoreSelectedKey": "SelectedProjectId",
  "StoreItemKey": "SelectedProject",
  "MaxChoices": 8,
  "NextStepCode": "GET_HOURS"
}

LOCATION Step

Pauses the flow and prompts the user to share their current location. Supported on AppChat, WhatsApp, and Telegram. On other channels the step sends the prompt text but cannot receive a native location payload — users must type coordinates manually.

After the user shares their location the engine stores the full location object under ContextKey. Individual fields are accessible using dot-notation: {DeliveryLocation.Lat}, {DeliveryLocation.Lng}, {DeliveryLocation.Address}.

{
  "StepType": "LOCATION",
  "MessageTemplate": "Please share your current location so we can dispatch a technician.",
  "ContextKey": "CustomerLocation",
  "NextStepCode": "DISPATCH_TECHNICIAN"
},
"DISPATCH_TECHNICIAN": {
  "StepType": "ACTION",
  "ActionType": "CALL_API",
  "ApiConfig": {
    "Endpoint": "/Dispatch/CreateJob",
    "Method": "POST",
    "Body": "{\"Latitude\":{CustomerLocation.Lat},\"Longitude\":{CustomerLocation.Lng},\"Address\":\"{CustomerLocation.Address}\"}"
  },
  "NextStepCode": "DISPATCH_DONE"
}

LINK Step

Emits one or more interactive buttons and immediately routes to the next step without waiting for user input. Use LINK to present quick-access URLs, phone call shortcuts, or QR codes alongside a message.

{
  "StepType": "LINK",
  "MessageTemplate": "Here are your quick actions for PO {POCode}:",
  "ButtonType": "URL",
  "LinkButtons": [
    { "Title": "View PO Details",   "Url": "https://erp.example.com/po/{POCode}" },
    { "Title": "Download PDF",      "Url": "https://erp.example.com/po/{POCode}/pdf" },
    { "Title": "Contact Vendor",    "Url": "tel:+971501234567" }
  ],
  "NextStepCode": "AWAIT_REPLY"
}

PRESENT Step

Renders a context variable containing a JSON object or array as a structured visual display (table, card, or list). Use PRESENT after a CALL_API step that returns a dataset to show the results to the user in a readable format.

{
  "StepType": "PRESENT",
  "ContextKey": "OpenPOList",
  "MessageTemplate": "Your open purchase orders:",
  "ResponseFormat": {
    "Type": "TABLE",
    "Fields": ["POCode", "VendorName", "TotalAmount", "Status"],
    "MaxRows": 5
  },
  "NextStepCode": "ASK_NEXT_ACTION"
}

Rich Input Types

INPUT steps support a Validation.InputType field that controls how the client renders the input prompt and how the engine validates the response. When InputType is omitted, the step behaves as a plain freeform text input.

Example — Rating INPUT Step

{
  "StepType": "INPUT",
  "MessageTemplate": "How would you rate your delivery experience? (1–5 stars)",
  "ContextKey": "DeliveryRating",
  "Validation": {
    "InputType": "rating",
    "RatingMax": 5,
    "Required": true
  },
  "NextStepCode": "RATING_CONDITIONAL"
}

QR Codes & Geo-Location

Embedding QR Codes in MESSAGE and PRESENT Steps

Add a QrCodeData field to any MESSAGE or PRESENT step to render a QR code alongside the text content. The value should be the string to encode (URL, JSON payload, plain reference code, etc.).

{
  "StepType": "MESSAGE",
  "MessageTemplate": "Scan this QR code to open your delivery tracking page:",
  "QrCodeData": "https://track.example.com/delivery/{DeliveryRef}",
  "NextStepCode": "AWAIT_SCAN_CONFIRM"
}

Per-Channel Rendering Behaviour

qr_scan INPUT Type

Use Validation.InputType = "qr_scan" on an INPUT step to prompt the user to scan a QR code with their device camera. The decoded string is stored in the variable named by ContextKey.

{
  "StepType": "INPUT",
  "MessageTemplate": "Please scan the asset QR tag to continue:",
  "ContextKey": "ScannedAssetCode",
  "Validation": { "InputType": "qr_scan", "Required": true },
  "NextStepCode": "LOOKUP_ASSET"
}

Inbound Location Messages

When a user shares their location via a channel that supports it (AppChat, WhatsApp, Telegram), the EIP engine automatically extracts the coordinates and address into the session context before routing to the next step. No explicit LOCATION step is required to receive a location — it can arrive as the response to any INPUT or CHOICE step.

The auto-extracted context variables are:

These variables are accessible in all subsequent steps via {_Location.Lat}, {_Location.Lng}, and {_Location.Address} substitutions, and can also be read by a LOCATION step's ContextKey (the LOCATION step stores them as a single JSON object under the configured key).

Voice Channel

EIP supports voice as a first-class channel type (ChannelType = 7). Voice conversations follow the same step-based flow engine as text channels. The key difference is that outbound messages are converted to speech and inbound audio is transcribed to text by the telephony platform before reaching the engine.

Enabling a Flow for Voice

Set the channel endpoint's CHANNELTYPE to 7 in MEIPCHANNELENDPOINT. No flow JSON changes are required — the same flow definition can serve both text and voice channels simultaneously through separate routing rules.

VoiceHint and SSML on MESSAGE Steps

Add an optional VoiceHint field to any MESSAGE or END step to provide Speech Synthesis Markup Language (SSML) instructions to the TTS engine. When VoiceHint is present, its content is sent as the spoken text; the plain MessageTemplate is still returned as display text for non-voice channels.

{
  "StepType": "MESSAGE",
  "MessageTemplate": "Your purchase order has been approved. Reference number: PO-5001.",
  "VoiceHint": "<speak>Your purchase order has been approved. <break time='500ms'/> Reference number: <say-as interpret-as='characters'>PO-5001</say-as></speak>",
  "NextStepCode": "DONE"
}

Handler Response for Voice

When the flow engine processes a voice session, the response envelope includes an AdditionalData object that the telephony adapter uses to drive the TTS/speech pipeline:

Platform Integration Notes

New Approval Flow Checklist

Follow these steps in order when setting up a new DirectAction approval flow from scratch:

• Identify the entity DTO that will be published (e.g., PurchaseOrderDTO). Note the exact field names for the entity PK and approver user ID.
• Insert one row in MDIRECTACTION with CONTEXTIDFIELD and ASSIGNEEUSERIDFIELD matching the DTO field names exactly.
• Insert one row in MDIRECTACTIONDETAIL per button (Approve, Reject, Return). Set NEEDSINPUT=0 for direct actions, NEEDSINPUT=1 for actions that need a reason/comments.
• Create or reuse an entry in MMAILTEMPLATE. Add ##PLACEHOLDER## tokens in the HTML body matching the EMAILPLACEHOLDER column values from MDIRECTACTIONDETAIL.
• Configure the MACTION row to link the EventTypeId to this DirectActionId and the mail template.
• In the application BLL (e.g., PurchaseOrderBLL), publish ActionEventDto with correct DirectActionId, ContextId, AssigneeUserId, DatabaseName, and TenantId.
• Test by raising a sample entity. Verify the email arrives with correct buttons and entity details filled in.
• Click Approve. Verify the internal API is called correctly and the confirmation page appears.
• Click Approve again. Verify "Already Actioned" page appears (one-time-use working).
• For NeedsInput=1 buttons: click, verify remarks form appears. Submit with text. Verify API payload contains the remarks text.
• Check TDIRECTACTIONTOKEN table: verify ASSIGNEEUSERID, CONTEXTID, REMARKS, EXPIRESAT columns are populated correctly.
• Test with expired token: manually update TDIRECTACTIONTOKEN... or wait 48h. Verify "Link Expired" page.
• QUALIFY steps: Ensure the qualifier is defined in MQUALIFIERDEFINITION with the correct BoundToType matching the entity being validated. Verify MapperCode exists and returns findings in the expected schema.
• DYNAMIC_CHOICE steps: Confirm the SourceKey is populated in the session context by a preceding CALL_API or ACTION step before the DYNAMIC_CHOICE step runs. An empty source list renders zero buttons and stalls the flow.
• LOCATION steps: Verify the channel supports location sharing — AppChat, WhatsApp, and Telegram are supported. SMS, Voice, and Teams do not support inbound location messages; using a LOCATION step on those channels will time out.
• Voice channel: Register the voice endpoint URL in the calling platform webhook configuration (Twilio: "A Call Comes In" → HTTP POST; Azure Bot Service: Direct Line Speech endpoint). Confirm the platform can reach the GB5 host on the configured port before go-live.

Security Notes for Administrators

Token Security

• Expiry: All email links expire after 48 hours from the time the email was sent. Users clicking expired links see "Link Expired or Invalid".
• One-time use: Each link can only be clicked once. The system tracks usage in TDIRECTACTIONTOKEN.
• Tamper protection: Tokens are signed with HMAC-SHA256. Modifying the link (even one character) invalidates it.
• Do not share: Each link is personal — it contains the assignee's user identity. Forwarding the email to a colleague and having them click the button would record the wrong approver in the audit log.

Revoking a Compromised Link

If an email is sent to the wrong person, or you need to cancel a pending approval link immediately:

-- Revoke all tokens for a specific context (e.g., all PO 5001 approval links)
UPDATE TDIRECTACTIONTOKEN
   SET STATUS = 2   -- 2 = Revoked
WHERE  CONTEXTID  = 5001
  AND  ACTIONCODE IN ('PO_APPROVE', 'PO_REJECT', 'PO_RETURN')
  AND  TENANTID   = 42;

-- User clicking a revoked link sees: "This link has been revoked."

Re-sending Approval Emails

-- Request a fresh email with new tokens via the API:
POST /Action/Resend
{
  "EventTypeId": 42,   -- the event type that triggered the original email
  "ContextId": 5001    -- entity PK
}

-- New tokens are generated (48h from now).
-- Old tokens remain valid until their original expiry but become ineffective
-- once the entity status changes (if the API handles idempotency correctly).

Audit Trail

Every click is recorded in TDIRECTACTIONTOKEN. To check who approved what:

-- Find all actions taken on PO 5001
SELECT
    t.ACTIONCODE,
    t.ASSIGNEEUSERID,
    u.USERNAME,
    t.USEDAT,
    t.REMARKS,
    t.STATUS
FROM   TDIRECTACTIONTOKEN t
JOIN   MUSER u ON u.USERID = t.ASSIGNEEUSERID
WHERE  t.CONTEXTID = 5001
  AND  t.TENANTID  = 42
ORDER  BY t.USEDAT;

Troubleshooting Guide

Useful Diagnostic Queries

-- Check recent DirectAction usage for a tenant
SELECT TOP 20
    t.ACTIONCODE,
    t.CONTEXTID,
    t.ASSIGNEEUSERID,
    t.USEDAT,
    t.STATUS,
    t.REMARKS,
    t.EXPIRESAT
FROM   TDIRECTACTIONTOKEN t
WHERE  t.TENANTID = 42
ORDER  BY t.CREATEDON DESC;

-- Check active EIP sessions for a user
SELECT *
FROM   TEIUSERSESSION
WHERE  USERIDENTIFIER = '+9715551234'
  AND  TENANTID       = 42
  AND  STATUS         = 1;

-- Check recent action pipeline runs
SELECT TOP 20
    r.ACTIONRUNID,
    r.RUNSTATUS,
    r.ERRORMESSAGE,
    r.CREATEDON
FROM   TEVENTACTIONRUN r
WHERE  r.TENANTID = 42
ORDER  BY r.CREATEDON DESC;

-- Check pending outbox messages (not yet sent to Dapr)
SELECT COUNT(*) AS PendingCount
FROM   TACTIONOUTBOX
WHERE  SENDSTATUS = 0
  AND  TENANTID   = 42;

GoodBooks GB5 — EIP & DirectAction Admin Guide — generated 2026-06-20