# insureMO iBooking

The iBooking Platform is a low-code, highly configurable solution designed to streamline the management of external insurance data. It replaces custom coding with dynamic configuration, enabling rapid and flexible integration with diverse data sources from partners and channels.

## Core Architecture

The platform features two independent, highly configurable modules:

### Input Processing Module

This module handles the ingestion and parsing of incoming data files (CSV, TSV, etc.) from external sources. Key features include:

- **Low-Code Configuration**: File parsing logic is defined through dynamic configuration, eliminating hardcoded development
- **Flexible Execution**: Files uploaded to Amazon S3 can be processed via manual triggers or scheduled automated batch jobs
- **Automated Processing**: Files placed in date-based directories are automatically processed the following day
### Output Generation Module

Operating independently from input processing, this module generates standardized reports and data extracts:

- **Configuration-Driven Logic**: Output rules are set up administratively without code changes
- **Dual Trigger Modes**: Output batch jobs run on defined schedules (daily/monthly) or can be executed manually
- **Multiple Formats**: Supports CSV, XLSX, and API-based PDF/Word generation
- **Flexible Distribution**: Files can be sent via email, SFTP/FTP, or stored in CloudDisk (S3) with download tracking

## Key Business Value

The iBooking Platform provides flexibility and efficiency. It empowers insurers to quickly adapt to changing data formats and reporting requirements, significantly reducing development time and operational overhead.

## Step-by-Step Guide

### Overview

iBooking Platform is a configurable data processing system for insurance companies to handle external partner data and generate reports efficiently through configuration-based operations.

**Applicable Roles**: Insurance enterprise data administrators, operation managers, claim review specialists.

### Step 1: Log in to the Platform

- **Operation**: Open Chrome 90+, enter platform address, input username/password, click **Login**

- **Goal**: Successfully access platform homepage

- **Key Node**: Check VPN connection if login fails; contact operation team for password reset

  *contact: [operation-team-email@insuremo.com]*

### Step 2: Configure File Parsing Rules

- **Operation**: Navigate to **System → File Parsing Configuration**

- **Goal**: Define how different file formats should be parsed

- **Configuration Options**:
    - **File Format**: Select CSV, TSV, or XLSX

    - **Delimiter**: Configure field separator (comma, tab, etc.)

    - **Header Row**: Specify if file contains header row

    - **Column Mapping**: Map file columns to database fields

    - **Validation Rules**: Set data validation criteria

- **Key Node**: Test configuration with sample files before production use

### Step 3: Upload Input Files

- **Operation**: Navigate to **Data → File Upload**

- **Supported Formats**: CSV, TSV, XLSX

- **File Naming Conventions**: Follow specific naming patterns (e.g., AUKC.csv, CWF_受付一覧.csv, There are no special rules for file naming)

- **Upload Location**: S3 bucket, Configurable for different S3 or directory structures, for example: **clouddisk://[bucket-name]/[path]/**

- **Goal**: Upload compliant data files to designated location

- **Key Node**: Ensure files are uploaded to correct date directory for automatic processing

### Step 4: Configure Batch Processing Jobs

- **Operation**: Navigate to **System → Batch Job Configuration**

- **Job Types**:
    - **Input Jobs** (Input01-Input08): Process uploaded files

    - **Output Jobs** (Output01-Output08): Generate output reports

- **Scheduling Options**:
  - **Manual Trigger**: Execute jobs on-demand

    - **Scheduled**: Set daily/monthly execution times

    - **Event-Driven**: Trigger based on file upload events

- **Notification Settings**: Configure email alerts for job completion/failure

- **Goal**: Set up automated data processing workflows

- **Key Node**: Test job configurations in test environment before production deployment

### Step 5: Monitor Processing Status

- **Operation**: Navigate to **System → Batch History**

- **View Options**:
    - **Execution Status**: Success, failure, in-progress

    - **Processing Times**: Job duration and performance metrics

    - **Error Details**: View detailed error messages for troubleshooting

      *To view errors, you can log in to portal → search for monitor → use traceid to query error log*

- **Goal**: Monitor batch job execution and identify issues

- **Key Node**: Set up proactive monitoring for critical jobs

### Step 6: Configure Output Generation

- **Operation**: Navigate to **System → Output Configuration**

- **Data Sources**:
    - **DataMO Subjects**: Select datasets with `CUST_` prefix

    - **DataMO Topics**: Choose topics with `domain_` or `mart_` prefix

- **Output Options**:
    - **File Format**: CSV, XLSX, or PDF via API integration

    - **Column Selection**: Choose which columns to include

    - **Formatting**: Configure date, number, and text formats

    - **Filtering**: Apply business-specific filters

    - **Sorting**: Set output sorting order

- **Distribution Channels**:
    - **Email**: Send to specified recipients
    - **File Transfer**: SFTP/FTP/FTPS to external servers
    - **Cloud Storage**: Store in CloudDisk (S3)

- **Goal**: Configure automated report generation and distribution

- **Key Node**: Test output formats and distribution channels

### Step 7: Access and Download Output Files

- **Operation**: Navigate to **Output → Output Files**

- **Search Options**: Filter by date, file type, job type

- **Download**: Click **Download** to save files locally

- **Download History**: View complete audit trail of file access

- **Goal**: Retrieve generated output files for business use

- **Key Node**: Classify and archive reports according to enterprise regulations

### Step 8: Data Search and Management

- **Operation**: Navigate to **Policy → Policy Info Enquiry**

- **Search Criteria**: Policy Number, Campaign Code, Policyholder Name, etc.

- **Data Validation**: Review and manage pending policies requiring attention

- **Administrative Actions**: Correct or drop invalid records

- **Goal**: Access and manage policy data

- **Key Node**: Regular data quality checks to maintain system integrity

## Key Configuration Points

### File Path Conventions

```
Input Configuration Example:
clouddisk://[bucket-name]/[path]/

where clouddisk is the protocol and [bucket-name] is the bucket name.

Output Configuration Example:
clouddisk://[bucket-name]/[path]/[subdirectory]
```

### Batch Job Types

- **Input01-Input08**: File processing jobs (daily/monthly)

- **Output01-Output07**: Monthly report generation (runs on 2nd day of month)

- **Output08**: Daily data output (runs daily at 06:00)

### Business Date Handling

- Monthly outputs process previous month's data

- Claims outputs (Output02-Output03) use only month-end data

## Common Tasks

### Daily Operation

1. Upload previous day's partner files to S3

2. Verify automatic processing completed successfully

3. Download and distribute required output reports

4. Monitor for any data quality issues

### Monthly Reporting

1. Ensure all daily files for previous month are processed

2. Trigger monthly output batches on 2nd of month

3. Distribute monthly reports to stakeholders

## Support Resources

- **Batch History**: Track all processing jobs

- **Download History**: Monitor file access

- **Error Logs**: Troubleshoot processing issues

- **User Manual**: Detailed feature documentation

## Permission Control (URP)

- Each output configuration can be individually controlled with permissions
- Configure OutputConfig permissions: Log in to insuremo → url → permission
- PermissionCode rule: report type + Config Code (for example, if the code for a configuration is 1001, the permissionCode needs to be defined as: [report_type]_[config_code])

## Customization Development Guide

### Development Environment Setup

#### Prerequisites

- Install IntelliJ IDEA (recommended version 2023 or above)
- JDK 17 or higher
- Install git
- Install Maven
- Install Node.js (18.12.1 or higher)
- Install Yarn 1.22.5
- Pull the latest main branch code from the iBooking code repository
- Use the command `git checkout -b feature/[feature-name]` to create a development branch

### Node Service Startup

#### Configure npm Registry

Create `.npmrc` file in user home directory:

```properties
registry=http://repo.insuremo.com/artifactory/api/npm/npm-all
_auth=[your-auth-token]
always-auth=true
email=[your-email@domain.com]
```

To create `_auth` token for `.npmrc`, use:

```bash
curl -u [username]:[password] http://repo.insuremo.com/artifactory/api/npm/auth
```

#### Initialize Workspace

```bash
yarn install
```

If timeout occurs, try:

```bash
yarn install --network-timeout 1000000000
```

<div class="docs-note"><span class="docs-admonitions-text">note</span>

For network issues in virtual machines, you may need to remove certain files to avoid connection errors.

</div>

#### Start Services

```bash
# Start node service
cd node-service
yarn start

# Start web application
cd web
yarn start
```

### Backend Service Startup

#### Configure Maven

1. Add the bin directory under Maven installation directory to PATH environment variable
2. Verify installation: `mvn -v`
3. Modify the `settings.xml` file in the conf folder under Maven installation directory
4. Configure Maven in IntelliJ IDEA

#### Set VM Parameters

```bash
-Dinsuremo_access_token="Bearer [YourPAT]"
-Dinsuremo_gw_url=https://ptdev-gw.insuremo.com
-DTENANT_CODE=[tenantCode]
-Dnode_service_url=http://localhost:3721
-Dcontext_path=/api/[tenantCode]/ibooking-service
```

#### Run Startup Class

Execute the main application class in IntelliJ IDEA.

### Code Development Standards

#### REST API Standards

**Path Naming Convention**

| Specification | Lowercase, words separated by hyphens, Path=[noun]/[noun]/[verb]-[condition] |
|---------------|----------------------------------------------------------|
| Example       | `md/rule/save`                                            |

**API Return Format**

| Specification | Directly return body, no need to wrap in RestResponse, framework already encapsulated |
|---------------|----------------------------------------------------------|
| Example       | `return policyMain;`                                      |

**API Exception Handling**

| Specification | Business validation directly throws Exception            |
|---------------|----------------------------------------------------------|
| Example       | `throw AppException(code, message)`                       |

**Transaction Management**

| Specification | Add @Transactional to create/update/delete APIs |
|---------------|-------------------------------------------------|
| Note          | Default uses `Propagation.REQUIRED`              |

**Pagination Query**

| Specification | Pagination starts from 1 |
|---------------|--------------------------|

**API Authorization**

| Specification | Use AuthorityAssert for authorization check                           |
|---------------|------------------------------------------------------------------------------|
| Example       | `AuthorityAssert.hasAny(AuthorityCode.AUTHORITY_CODE_BDX_CONFIGURATION_EDIT);` |

#### Service Layer Standards

**Service Exception Handling**

| Specification | Service directly throws Exception, no need to return RestError |
|---------------|----------------------------------------------------------|
| Example       | `throw AppException(code, message)`                       |

#### Data Access Object (DAO) Standards

**Unified Query Solution**

Recommended to use JPA Specification:

```java
Specification<EntityClass> spec = new Specification<EntityClass>() {
    @Override
    public Predicate toPredicate(Root<EntityClass> root, CriteriaQuery<?> query, CriteriaBuilder criteriaBuilder) {
        List<Predicate> predicates = new ArrayList<>();
        if (StringUtils.hasText(fieldName)) {
            Predicate predicate = criteriaBuilder.equal(
                criteriaBuilder.upper(root.get("fieldName")),
                fieldName.toUpperCase()
            );
            predicates.add(predicate);
        }
        return criteriaBuilder.and(predicates.toArray(new Predicate[0]));
    }
};

Page<EntityClass> results = repository.findAll(spec, pageable);
```

For simple queries (1-2 parameters), use JPA native SQL:

```java
@Entity
interface Repository extends JpaRepository<Entity, Long>, JpaSpecificationExecutor<Entity> {
    @Query(value = "SELECT column1, column2 FROM table_name", nativeQuery = true)
    public List<Object[]> customQuery();
}
```

For complex cross-table queries, use JdbcTemplate:

```java
public Page<ResultSet> query(String fileName, Long ruleId, PageRequest pageable) {
    StringBuilder dynamicSql = new StringBuilder();
    dynamicSql.append("SELECT t1.col1, t2.col2 FROM table1 t1, table2 t2 WHERE t1.id = t2.id");

    List params = new ArrayList();
    if (StringUtils.hasText(fileName)) {
        dynamicSql.append(" AND upper(t1.file_name) LIKE ?");
        params.add("%" + fileName.toUpperCase() + "%");
    }

    // Execute query and return paginated results
    // ...
}
```

**JPA Null Value Handling**

| Specification | Use Optional.orElseThrow() directly for JPA null value handling |
|---------------|----------------------------------------------------------|
| Example       | `Entity entity = repository.findById(id).orElseThrow();`  |