Integration Points

Overview

The AWS CardDemo application provides multiple integration points for external systems, modernization initiatives, and cross-platform communication. This document details all external interfaces, messaging patterns, and integration architectures.

Integration Architecture Overview

1. IBM MQ Integration (Message Queuing)

1.1 Authorization Request/Response Pattern

Purpose: Real-time credit card authorization processing from external POS systems

Architecture:

Queue Definitions:

Request Message Format (CSV):

AUTH-DATE, AUTH-TIME, CARD-NUM, AUTH-TYPE, CARD-EXPIRY-DATE,
MESSAGE-TYPE, MESSAGE-SOURCE, PROCESSING-CODE, TRANSACTION-AMT,
MERCHANT-CATAGORY-CODE, ACQR-COUNTRY-CODE, POS-ENTRY-MODE,
MERCHANT-ID, MERCHANT-NAME, MERCHANT-CITY, MERCHANT-STATE,
MERCHANT-ZIP, TRANSACTION-ID

Request Field Specifications:

Response Message Format (CSV):

CARD-NUM, TRANSACTION-ID, AUTH-ID-CODE, AUTH-RESP-CODE,
AUTH-RESP-REASON, APPROVED-AMT

Response Field Specifications:

Response Codes:

Processing Program: COPAUA0C (Transaction CP00)

Processing Flow:

1. Message arrives in REQUEST queue
2. MQ trigger starts CICS transaction CP00
3. Program reads and parses CSV message
4. Validates card in CARDDAT and CCXREF
5. Checks account status and limits in ACCTDAT
6. Applies business rules (fraud detection, limits)
7. Stores authorization in IMS database (DBPAUTP0)
8. Optionally logs fraud cases in DB2 (AUTHFRDS)
9. Builds response message
10. Puts response to REPLY queue

Error Handling:

• Invalid message format: Return error code 91
• Card not found: Return error code 05
• Account inactive: Return error code 05
• Over limit: Return error code 51
• Expired card: Return error code 54

1.2 Account Inquiry Pattern

Purpose: Synchronous data retrieval from CICS via messaging

Queue Definitions:

Supported Operations:

Date Inquiry (CDRD)

Program: CODATE01 Purpose: Retrieve system date

Request Format:

DATE_REQUEST

Response Format:

DATE:YYYY-MM-DD,TIME:HH:MM:SS

Account Details Inquiry (CDRA)

Program: COACCT01 Purpose: Retrieve account information

Request Format:

ACCOUNT_REQUEST:ACCT-ID

Response Format:

ACCT:account-id,BAL:balance,LIMIT:credit-limit,STATUS:status

Processing Flow:

Timeout Handling:

• Default timeout: 30 seconds
• Returns timeout error if no response
• Client responsible for retry logic

2. Batch File Interfaces

2.1 Daily Transaction Import

Purpose: Import external transaction files for posting

File Interface:

Record Layout:

Processing Job: POSTTRAN.jcl Processing Program: CBTRN01C

Processing Steps:

1. Read DALYTRAN sequentially
2. Validate card number in CCXREF
3. Lookup account in ACCTDAT
4. Validate transaction data
5. Generate unique TRAN-ID
6. Write to TRANSACT file
7. Update account balances
8. Update category balances (TCATBALF)

Validation Rules:

• Card must exist in CCXREF
• Account must be active
• Transaction amount must be non-zero
• Merchant information required for purchases
• Transaction type must be valid

Error Handling:

• Invalid records written to error file
• Error file: AWS.M2.CARDDEMO.DALYTRAN.ERRORS
• Error record format: Original record + error code + error message

2.2 Data Export Interface

Purpose: Export data for external analytics and reporting

Export Jobs:

Account Export

File Name: AWS.M2.CARDDEMO.ACCT.EXPORT Program: CBEXPORT Format: CSV with header

Record Format:

ACCOUNT_ID,CUSTOMER_ID,STATUS,CURRENT_BALANCE,CREDIT_LIMIT,OPEN_DATE

Transaction Export

File Name: AWS.M2.CARDDEMO.TRAN.EXPORT Program: CBEXPORT Format: CSV with header

Record Format:

TRANSACTION_ID,CARD_NUM,TYPE,CATEGORY,AMOUNT,MERCHANT,TIMESTAMP

Schedule: Daily at 2:00 AM

Delivery Methods:

• FTP to designated server
• S3 upload via AWS CLI
• SFTP to partner systems

2.3 Interest Transaction Interface

Purpose: Output file from interest calculation for posting

File Interface:

Record Layout: Same as DALYTRAN format

Usage:

1. CBACT04C creates interest/fee transactions
2. Writes to SYSTRAN GDG (+1)
3. Next batch cycle posts SYSTRAN to TRANSACT

3. DB2 Integration Points

3.1 Transaction Type Management

Purpose: Maintain reference data in DB2, synchronize to VSAM

DB2 Tables:

• CARDDEMO.TRANSACTION_TYPE
• CARDDEMO.TRANSACTION_TYPE_CATEGORY

Access Methods:

Online Access (CICS)

Programs:

• COTRTLIC: List, update, delete transaction types
• COTRTUPC: Add, edit transaction types

SQL Operations:

-- List transaction types
SELECT TR_TYPE, TR_DESCRIPTION
FROM CARDDEMO.TRANSACTION_TYPE
ORDER BY TR_TYPE

-- Insert new type
INSERT INTO CARDDEMO.TRANSACTION_TYPE
(TR_TYPE, TR_DESCRIPTION)
VALUES (:WS-TYPE, :WS-DESC)

-- Update type
UPDATE CARDDEMO.TRANSACTION_TYPE
SET TR_DESCRIPTION = :WS-DESC
WHERE TR_TYPE = :WS-TYPE

-- Delete type
DELETE FROM CARDDEMO.TRANSACTION_TYPE
WHERE TR_TYPE = :WS-TYPE

Cursor Processing:

• Forward scrolling: DECLARE CURSOR ... ORDER BY TR_TYPE ASC
• Backward scrolling: DECLARE CURSOR ... ORDER BY TR_TYPE DESC
• Page size: 10 records

Batch Synchronization

Job: TRANEXTR.jcl (Weekly) Program: TRANEXTR (Uses DSNTIAUL utility)

Process:

1. Unload data from DB2 to sequential file
2. Sort and format data
3. Update VSAM transaction type file
4. Maintain referential integrity

SQL for Extraction:

SELECT TR_TYPE, TR_DESCRIPTION
FROM CARDDEMO.TRANSACTION_TYPE
ORDER BY TR_TYPE

3.2 Fraud Case Tracking

Purpose: Store and analyze fraud cases

DB2 Table: CARDDEMO.AUTHFRDS

Access Method: CICS Program (COPAUS2C)

Insert Operation:

INSERT INTO CARDDEMO.AUTHFRDS (
    CARD_NUM, AUTH_TS, AUTH_TYPE, CARD_EXPIRY_DATE,
    MESSAGE_TYPE, MESSAGE_SOURCE, AUTH_ID_CODE,
    AUTH_RESP_CODE, AUTH_RESP_REASON, PROCESSING_CODE,
    TRANSACTION_AMT, APPROVED_AMT, MERCHANT_CATAGORY_CODE,
    ACQR_COUNTRY_CODE, POS_ENTRY_MODE, MERCHANT_ID,
    MERCHANT_NAME, MERCHANT_CITY, MERCHANT_STATE,
    MERCHANT_ZIP, TRANSACTION_ID, MATCH_STATUS,
    AUTH_FRAUD, FRAUD_RPT_DATE, ACCT_ID, CUST_ID
) VALUES (
    :CARD-NUM, CURRENT TIMESTAMP, :AUTH-TYPE, :CARD-EXPIRY,
    :MSG-TYPE, :MSG-SOURCE, :AUTH-ID, :RESP-CODE,
    :RESP-REASON, :PROC-CODE, :TRAN-AMT, :APPR-AMT,
    :MERCH-CAT, :COUNTRY, :POS-MODE, :MERCH-ID,
    :MERCH-NAME, :MERCH-CITY, :MERCH-STATE,
    :MERCH-ZIP, :TRAN-ID, :MATCH-STATUS,
    'Y', CURRENT DATE, :ACCT-ID, :CUST-ID
)

Query Operations (External Analytics):

-- Fraud summary by merchant
SELECT MERCHANT_NAME, COUNT(*), SUM(TRANSACTION_AMT)
FROM CARDDEMO.AUTHFRDS
WHERE AUTH_FRAUD = 'Y'
GROUP BY MERCHANT_NAME
ORDER BY COUNT(*) DESC

-- Recent fraud cases
SELECT CARD_NUM, AUTH_TS, MERCHANT_NAME, TRANSACTION_AMT
FROM CARDDEMO.AUTHFRDS
WHERE AUTH_FRAUD = 'Y'
  AND FRAUD_RPT_DATE >= CURRENT DATE - 30 DAYS
ORDER BY AUTH_TS DESC

4. IMS Database Integration

4.1 Authorization Storage

Purpose: Store pending authorizations in hierarchical structure

IMS Databases:

• DBPAUTP0: Primary HIDAM database
• DBPAUTX0: Index database

Access Programs:

• COPAUA0C: Store authorization (online)
• COPAUS0C: View summary (online)
• COPAUS1C: View details (online)
• CBPAUP0C: Purge expired (batch BMP)

DL/I Operations:

Insert Authorization (GU + ISRT)

* Get or create summary segment
EXEC DLI GU
    USING PCB(1)
    SEGMENT('PAUTSUM0')
    WHERE('PA-ACCT-ID = :WS-ACCT-ID')
    INTO(:PAUTSUM0-SEGMENT)
END-EXEC

IF IMS-STATUS-CODE = 'GE'
    * Account not found, insert summary
    EXEC DLI ISRT
        USING PCB(1)
        SEGMENT('PAUTSUM0')
        FROM(:PAUTSUM0-SEGMENT)
    END-EXEC
END-IF

* Insert detail segment
EXEC DLI ISRT
    USING PCB(1)
    SEGMENT('PAUTSUM0', 'PAUTDTL1')
    FROM(:PAUTDTL1-SEGMENT)
END-EXEC

Retrieve Authorizations (GU + GN)

* Get summary
EXEC DLI GU
    USING PCB(1)
    SEGMENT('PAUTSUM0')
    WHERE('PA-ACCT-ID = :WS-ACCT-ID')
    INTO(:PAUTSUM0-SEGMENT)
END-EXEC

* Get all detail children
PERFORM UNTIL IMS-STATUS-CODE = 'GB'
    EXEC DLI GN
        USING PCB(1)
        SEGMENT('PAUTDTL1')
        INTO(:PAUTDTL1-SEGMENT)
    END-EXEC

    IF IMS-STATUS-CODE = SPACES
        PERFORM PROCESS-AUTH-DETAIL
    END-IF
END-PERFORM

Delete Authorization (GHU + DLET)

* Hold for update
EXEC DLI GHU
    USING PCB(1)
    SEGMENT('PAUTSUM0', 'PAUTDTL1')
    WHERE('PA-ACCT-ID = :WS-ACCT-ID'
          'PA-AUTH-DATE-9C = :WS-AUTH-DATE'
          'PA-AUTH-TIME-9C = :WS-AUTH-TIME')
    INTO(:PAUTDTL1-SEGMENT)
END-EXEC

IF IMS-STATUS-CODE = SPACES
    EXEC DLI DLET
        USING PCB(1)
        SEGMENT('PAUTDTL1')
    END-EXEC
END-IF

5. TN3270 Terminal Interface

5.1 Terminal Access

Protocol: TN3270E Port: 23 (default) or custom port Emulation: IBM 3270 Model 2/4

Connection String:

tn3270://aws-m2-host.region.amazonaws.com:port

Supported Features:

• Extended data stream
• 3270 extended attributes
• Color support
• Function keys (PF1-PF24)
• PA keys (PA1-PA3)
• CLEAR, ENTER keys

Screen Dimensions:

• 24 rows x 80 columns (Model 2)
• 43 rows x 80 columns (Model 4)

6. FTP/SFTP Interfaces

6.1 Batch File Transfer

Purpose: Transfer data files to/from external systems

Supported Operations:

FTP Configuration:

Host: ftp.carddemo.example.com
Port: 21 (FTP) / 22 (SFTP)
User: CARDDEMO
Directory: /data/carddemo/

Naming Convention:

DALYTRAN.YYYYMMDD.txt
ACCT.EXPORT.YYYYMMDD.csv
TRAN.EXPORT.YYYYMMDD.csv
STMT.YYYYMM.pdf

7. REST API Integration (Future)

7.1 Proposed API Endpoints

Base URL: https://api.carddemo.example.com/v1

Endpoints:

GET  /accounts/{accountId}
GET  /accounts/{accountId}/cards
GET  /accounts/{accountId}/transactions
POST /accounts/{accountId}/transactions
GET  /cards/{cardNumber}
PUT  /cards/{cardNumber}/status
POST /authorizations
GET  /authorizations/{authId}

Authentication: OAuth 2.0 / API Key

Response Format: JSON

8. Integration Patterns Summary

Pattern Comparison:

9. Security Considerations

9.1 MQ Security

Authentication:

• Channel authentication records
• User ID validation
• SSL/TLS encryption

Authorization:

• Queue-level permissions
• Channel-level security
• Connection authentication

9.2 DB2 Security

Access Control:

• Grant/Revoke privileges
• Role-based security
• View-based restrictions

Audit:

• SQL audit logs
• DB2 trace facility
• Security event logging

9.3 Data Encryption

In Transit:

• TLS for MQ connections
• SSL for DB2 connections
• SFTP for file transfers

At Rest:

• Dataset encryption (z/OS)
• EBS encryption (AWS)
• Database encryption (RDS)

10. Monitoring and Observability

10.1 Integration Metrics

MQ Metrics:

• Queue depth
• Message throughput
• Processing time
• Error rates

DB2 Metrics:

• SQL response time
• Lock contention
• Buffer pool hit ratio
• Thread usage

IMS Metrics:

• Call volume
• Response time
• Database I/O
• Lock conflicts

10.2 Logging

Log Types:

• CICS transaction logs
• MQ channel logs
• DB2 SQL logs
• Batch job logs (SYSOUT)

Centralization:

• AWS CloudWatch Logs
• Splunk integration
• ELK stack

11. Error Handling

11.1 MQ Error Handling

Dead Letter Queue:

• Queue: CARDDEMO.DLQ
• Captures undeliverable messages
• Includes error headers

Retry Logic:

• Automatic retry: 3 attempts
• Retry interval: 5 seconds
• Backout threshold: 3

11.2 DB2 Error Handling

SQLCODE Handling:

EXEC SQL
    SELECT ...
END-EXEC

EVALUATE SQLCODE
    WHEN 0
        PERFORM PROCESS-SUCCESS
    WHEN 100
        PERFORM HANDLE-NOT-FOUND
    WHEN OTHER
        PERFORM HANDLE-SQL-ERROR
END-EVALUATE

Common SQLCODEs:

• 0: Successful
• 100: Row not found
• -803: Duplicate key
• -911: Deadlock

11.3 File Error Handling

FILE STATUS Codes:

READ ACCOUNT-FILE
IF ACCTFILE-STATUS = '00'
    PERFORM PROCESS-RECORD
ELSE IF ACCTFILE-STATUS = '10'
    DISPLAY 'END OF FILE'
ELSE IF ACCTFILE-STATUS = '23'
    DISPLAY 'RECORD NOT FOUND'
ELSE
    PERFORM HANDLE-FILE-ERROR
END-IF