admin/mars
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ecd833f6825b8379ba2bace7a9fb4809fa9ac22f
mars/MARS_Packages/REL01/MARS-1049/confluence/implementation_Instructions_MARS-1049.md
Grzegorz Michalski ecd833f682 Init
2026-02-02 10:59:29 +01:00

14 KiB
Raw Blame History

MARS-1049: ENCODING Implementation in FILE_MANAGER

Change Description

Adding ENCODING column to the A_SOURCE_FILE_CONFIG table and modifying the FILE_MANAGER package to support different character encodings for CSV files.

Objective

Enable configuration of character encoding for individual source files without code modifications. The value from the ENCODING column will be passed as a characterset parameter in the formatting options of the CREATE_EXTERNAL_TABLE procedure.

1. DATABASE STRUCTURE MODIFICATIONS

Adding ENCODING column

-- Add column to A_SOURCE_FILE_CONFIG table
ALTER TABLE CT_MRDS.A_SOURCE_FILE_CONFIG 
ADD (ENCODING VARCHAR2(50));

-- Add column comment
COMMENT ON COLUMN CT_MRDS.A_SOURCE_FILE_CONFIG.ENCODING 
IS 'Character encoding for CSV files (e.g. UTF8, WE8MSWIN1252, etc.)';

Data type: VARCHAR2(50) - sufficient for Oracle encoding names Nullable: YES - defaults to NULL, database default encoding is used Default: NULL

2. FILE_MANAGER PACKAGE MODIFICATIONS

A. CREATE_EXTERNAL_TABLE procedure signature (main)

BEFORE:

PROCEDURE CREATE_EXTERNAL_TABLE (
   pTableName          IN VARCHAR2,
   pTemplateTableName  IN VARCHAR2,
   pPrefix             IN VARCHAR2,
   pBucketUri          IN VARCHAR2 DEFAULT ENV_MANAGER.gvInboxBucketUri,
   pFileName           IN VARCHAR2 DEFAULT NULL,
   pDelimiter          IN VARCHAR2 DEFAULT ','
)

PO:

PROCEDURE CREATE_EXTERNAL_TABLE (
   pTableName          IN VARCHAR2,
   pTemplateTableName  IN VARCHAR2,
   pPrefix             IN VARCHAR2,
   pBucketUri          IN VARCHAR2 DEFAULT ENV_MANAGER.gvInboxBucketUri,
   pFileName           IN VARCHAR2 DEFAULT NULL,
   pDelimiter          IN VARCHAR2 DEFAULT ',',
   pEncoding           IN VARCHAR2 DEFAULT NULL  -- NOWY PARAMETR
)

B. Wywołanie procedury CREATE_EXTERNAL_TABLE (overload)

Lokalizacja: Linie 499-506 PRZED:

CREATE_EXTERNAL_TABLE(
   pTableName => vSourceFileReceived.EXTERNAL_TABLE_NAME,
   pTemplateTableName => vSourceFileConfig.TEMPLATE_TABLE_NAME,
   pPrefix => vSourceFileReceived.SOURCE_FILE_PREFIX_INBOX,
   pBucketUri => ENV_MANAGER.gvInboxBucketUri,
   pFileName => vFileName,
   pDelimiter => ','
);

PO:

CREATE_EXTERNAL_TABLE(
   pTableName => vSourceFileReceived.EXTERNAL_TABLE_NAME,
   pTemplateTableName => vSourceFileConfig.TEMPLATE_TABLE_NAME,
   pPrefix => vSourceFileReceived.SOURCE_FILE_PREFIX_INBOX,
   pBucketUri => ENV_MANAGER.gvInboxBucketUri,
   pFileName => vFileName,
   pDelimiter => ',',
   pEncoding => vSourceFileConfig.ENCODING  -- NOWY PARAMETR
);

C. Logika kodowania w opcjach formatowania

Lokalizacja: Około linii 455 w sekcji vFormat PRZED:

IF pDelimiter = '|' THEN
   vFormat := json_object('delimiter' VALUE '|', 'skipheaders' VALUE '1');
ELSE
   vFormat := json_object('type' VALUE 'CSV', 'skipheaders' VALUE '1', 'ignoremissingcolumns' value 'true');
END IF;

PO:

-- Tworzenie podstawowego formatu
IF pDelimiter = '|' THEN
   vFormat := json_object('delimiter' VALUE '|', 'skipheaders' VALUE '1');
ELSE
   vFormat := json_object('type' VALUE 'CSV', 'skipheaders' VALUE '1', 'ignoremissingcolumns' value 'true');
END IF;

-- Dodanie kodowania jeśli zostało określone
IF pEncoding IS NOT NULL AND LENGTH(TRIM(pEncoding)) > 0 THEN
   vFormat := JSON_MERGEPATCH(vFormat, json_object('characterset' VALUE pEncoding));
END IF;

3. PRZYKŁADY UŻYCIA

Test z kodowaniem UTF-8

-- Konfiguracja dla plików z UTF-8 encoding
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'UTF8'
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;

Test z kodowaniem Windows-1252

-- Konfiguracja dla plików z Windows-1252 encoding
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'WE8MSWIN1252'
WHERE A_SOURCE_FILE_CONFIG_KEY = 2;

Resetowanie do wartości domyślnych

-- Usunięcie kodowania (powrót do domyślnego kodowania bazy)
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = NULL
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;

4. MODYFIKACJA ISTNIEJĄCEJ PROCEDURY ADD_SOURCE_FILE_CONFIG

Rozszerzenie procedury ADD_SOURCE_FILE_CONFIG

PRZED:

PROCEDURE ADD_SOURCE_FILE_CONFIG(
   pSourceKey IN VARCHAR2,
   pSourceFileType IN VARCHAR2,
   pSourceFileId IN VARCHAR2,
   pSourceFileDesc IN VARCHAR2,
   pSourceFileNamePattern IN VARCHAR2,
   pTableId IN VARCHAR2,
   pTemplateTableName IN VARCHAR2
)

PO:

PROCEDURE ADD_SOURCE_FILE_CONFIG(
   pSourceKey IN VARCHAR2,
   pSourceFileType IN VARCHAR2,
   pSourceFileId IN VARCHAR2,
   pSourceFileDesc IN VARCHAR2,
   pSourceFileNamePattern IN VARCHAR2,
   pTableId IN VARCHAR2,
   pTemplateTableName IN VARCHAR2,
   pEncoding IN VARCHAR2 DEFAULT NULL  -- NOWY PARAMETR
)

Modyfikacja INSERT statement w ADD_SOURCE_FILE_CONFIG

PRZED:

INSERT INTO CT_MRDS.A_SOURCE_FILE_CONFIG (
   A_SOURCE_KEY, SOURCE_FILE_TYPE, SOURCE_FILE_ID, SOURCE_FILE_DESC,
   SOURCE_FILE_NAME_PATTERN, TABLE_ID, TEMPLATE_TABLE_NAME
) VALUES (
   pSourceKey, pSourceFileType, pSourceFileId, pSourceFileDesc,
   pSourceFileNamePattern, pTableId, pTemplateTableName
);

PO:

INSERT INTO CT_MRDS.A_SOURCE_FILE_CONFIG (
   A_SOURCE_KEY, SOURCE_FILE_TYPE, SOURCE_FILE_ID, SOURCE_FILE_DESC,
   SOURCE_FILE_NAME_PATTERN, TABLE_ID, TEMPLATE_TABLE_NAME, ENCODING
) VALUES (
   pSourceKey, pSourceFileType, pSourceFileId, pSourceFileDesc,
   pSourceFileNamePattern, pTableId, pTemplateTableName, pEncoding
);

Przykład użycia zmodyfikowanej procedury

-- Dodanie konfiguracji z kodowaniem UTF-8
CALL FILE_MANAGER.ADD_SOURCE_FILE_CONFIG(
   pSourceKey => 'C2D',
   pSourceFileType => 'INPUT',
   pSourceFileId => 'UC_DISSEM',
   pSourceFileDesc => 'UC DISSEM Metadata with UTF-8 encoding',
   pSourceFileNamePattern => 'UC_NMA_DISSEM-*.csv',
   pTableId => 'A_UC_DISSEM_METADATA_LOADS',
   pTemplateTableName => 'CT_ET_TEMPLATES.C2D_A_UC_DISSEM_METADATA_LOADS',
   pEncoding => 'UTF8'
);

-- Dodanie konfiguracji bez kodowania (jak dotychczas)
CALL FILE_MANAGER.ADD_SOURCE_FILE_CONFIG(
   pSourceKey => 'LM',
   pSourceFileType => 'INPUT', 
   pSourceFileId => 'STANDING_FACILITIES',
   pSourceFileDesc => 'Standing Facilities Data',
   pSourceFileNamePattern => 'SF_*.csv',
   pTableId => 'STANDING_FACILITIES',
   pTemplateTableName => 'CT_ET_TEMPLATES.LM_STANDING_FACILITIES'
   -- pEncoding pomijamy - będzie NULL (domyślne kodowanie)
);

5. TESTY WALIDACYJNE

Test 1: Podstawowa funkcjonalność

-- 1. Ustawienie kodowania UTF-8
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'UTF8'
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;

-- 2. Test przetwarzania pliku
CALL FILE_MANAGER.PROCESS_SOURCE_FILE('INBOX/TEST/FILE_ID/TABLE_NAME/test_file.csv');

-- 3. Sprawdzenie logów
SELECT * FROM CT_MRDS.A_PROCESS_LOG 
WHERE PROCEDURE_NAME = 'CREATE_EXTERNAL_TABLE' 
ORDER BY LOG_DATE DESC;

Test 2: Fallback do wartości domyślnych

-- 1. Ustawienie NULL
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = NULL
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;

-- 2. Test przetwarzania - powinno być używane domyślne kodowanie
CALL FILE_MANAGER.PROCESS_SOURCE_FILE('INBOX/TEST/FILE_ID/TABLE_NAME/test_file.csv');

Test 3: Różne kodowania

-- 1. Test z Windows-1252
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'WE8MSWIN1252'
WHERE A_SOURCE_FILE_CONFIG_KEY = 1;

-- 2. Test z UTF-8
UPDATE CT_MRDS.A_SOURCE_FILE_CONFIG 
SET ENCODING = 'UTF8'
WHERE A_SOURCE_FILE_CONFIG_KEY = 2;

-- 3. Test przetwarzania obu plików
CALL FILE_MANAGER.PROCESS_SOURCE_FILE('INBOX/TEST1/FILE_ID/TABLE_NAME/test_file1.csv');
CALL FILE_MANAGER.PROCESS_SOURCE_FILE('INBOX/TEST2/FILE_ID/TABLE_NAME/test_file2.csv');

6. HARMONOGRAM WDROŻENIA

Faza 1: Przygotowanie struktury (KRYTYCZNA)

  1. ✅ Dodanie kolumny ENCODING do tabeli
  2. ✅ Zaktualizowanie definicji tabeli w plikach DDL

Faza 2: Modyfikacja pakietu (WYSOKA)

  1. ⏳ Dodanie parametru do sygnatury CREATE_EXTERNAL_TABLE
  2. ⏳ Implementacja logiki kodowania w formatowaniu JSON
  3. ⏳ Aktualizacja wywołania w procedurze overload
  4. ⏳ Aktualizacja parametrów logowania

Faza 3: Testy i walidacja (ŚREDNIA)

  1. ⏳ Testy jednostkowe z różnymi kodowaniami
  2. ⏳ Testy integracyjne z różnymi typami plików
  3. ⏳ Walidacja fallback do domyślnego kodowania

Faza 4: Modyfikacja procedur konfiguracyjnych (NISKA)

  1. ⏳ Modyfikacja ADD_SOURCE_FILE_CONFIG - dodanie parametru pEncoding
  2. ⏳ Aktualizacja dokumentacji
  3. ⏳ Przykłady użycia w confluence

7. ROLLBACK

W przypadku problemów można wykonać rollback:

-- Usunięcie kolumny (OSTROŻNIE - spowoduje utratę danych)
ALTER TABLE CT_MRDS.A_SOURCE_FILE_CONFIG DROP COLUMN ENCODING;

-- Przywrrócenie oryginalnej wersji pakietu FILE_MANAGER
-- (wymagane przywrrócenie z backupu)

8. UWAGI TECHNICZNE

Ograniczenia

  • Maksymalna długość nazwy kodowania: 50 znaków
  • Obsługiwane kodowania: wszystkie wspierane przez Oracle Database
  • Przykłady poprawnych nazw: UTF8, WE8MSWIN1252, AL32UTF8, WE8ISO8859P1

Bezpieczeństwo

  • Brak walidacji nazwy kodowania na poziomie aplikacji
  • Oracle Database zwaliduje kodowanie podczas tworzenia external table
  • Fallback do domyślnego kodowania bazy w przypadku NULL

Wydajność

  • Minimalne obciążenie - kodowanie dodawane tylko jeśli nie jest NULL
  • Brak wpływu na istniejące procesy gdy kolumna jest NULL
  • Używa natywnej funkcji JSON_MERGEPATCH Oracle Database

9. PRZYGOTOWANIE PACZKI INSTALACYJNEJ

Struktura paczki MARS-1049

MARS_Packages/REL02/MARS-1049/
├── 01_MARS_1049_install_CT_MRDS_ADD_ENCODING_COLUMN.sql
├── 02_MARS_1049_install_CT_MRDS_FILE_MANAGER_SPEC.sql
├── 03_MARS_1049_install_CT_MRDS_FILE_MANAGER_BODY.sql
├── 04_MARS_1049_verify_ENCODING_FUNCTIONALITY.sql
├── 05_MARS_1049_track_version.sql
├── 91_MARS_1049_rollback_FILE_MANAGER_BODY.sql
├── 92_MARS_1049_rollback_FILE_MANAGER_SPEC.sql
├── 93_MARS_1049_rollback_ENCODING_COLUMN.sql
├── 94_MARS_1049_track_rollback_version.sql
├── install_mars1049.sql
├── rollback_mars1049.sql
└── README_ENCODING.md

Zawartość skryptów instalacyjnych

01_MARS_1049_install_CT_MRDS_ADD_ENCODING_COLUMN.sql

-- MARS-1049: Dodanie kolumny ENCODING do A_SOURCE_FILE_CONFIG
-- Autor: System Enhancement
-- Data: 2025-11-24

PROMPT Adding ENCODING column to CT_MRDS.A_SOURCE_FILE_CONFIG

ALTER TABLE CT_MRDS.A_SOURCE_FILE_CONFIG 
ADD (ENCODING VARCHAR2(50));

COMMENT ON COLUMN CT_MRDS.A_SOURCE_FILE_CONFIG.ENCODING 
IS 'Character encoding for CSV files (e.g. UTF8, WE8MSWIN1252, etc.)';

PROMPT ENCODING column added successfully

02_MARS_1049_install_CT_MRDS_FILE_MANAGER_SPEC.sql

-- MARS-1049: Aktualizacja specyfikacji FILE_MANAGER - dodanie parametru pEncoding
-- Zawiera: Modyfikację sygnatury CREATE_EXTERNAL_TABLE i ADD_SOURCE_FILE_CONFIG

04_MARS_1049_verify_ENCODING_FUNCTIONALITY.sql

-- MARS-1049: Weryfikacja funkcjonalności ENCODING
PROMPT Testing ENCODING functionality...

-- Test 1: Sprawdzenie struktury tabeli
SELECT COLUMN_NAME, DATA_TYPE, DATA_LENGTH, NULLABLE 
FROM USER_TAB_COLUMNS 
WHERE TABLE_NAME = 'A_SOURCE_FILE_CONFIG' 
AND COLUMN_NAME = 'ENCODING';

-- Test 2: Test podstawowej funkcjonalności
INSERT INTO CT_MRDS.A_SOURCE_FILE_CONFIG (
    A_SOURCE_KEY, SOURCE_FILE_TYPE, SOURCE_FILE_ID, 
    SOURCE_FILE_DESC, SOURCE_FILE_NAME_PATTERN, 
    TABLE_ID, TEMPLATE_TABLE_NAME, ENCODING
) VALUES (
    'TEST', 'INPUT', 'ENCODING_TEST', 
    'Test ENCODING functionality', 'test_*.csv',
    'TEST_TABLE', 'CT_ET_TEMPLATES.TEST_TABLE', 'UTF8'
);

-- Sprawdzenie czy rekord został dodany
SELECT A_SOURCE_FILE_CONFIG_KEY, ENCODING 
FROM CT_MRDS.A_SOURCE_FILE_CONFIG 
WHERE A_SOURCE_KEY = 'TEST' AND SOURCE_FILE_ID = 'ENCODING_TEST';

-- Cleanup
DELETE FROM CT_MRDS.A_SOURCE_FILE_CONFIG 
WHERE A_SOURCE_KEY = 'TEST' AND SOURCE_FILE_ID = 'ENCODING_TEST';

PROMPT ENCODING functionality verification completed successfully

install_mars1049.sql (Master Install Script)

-- MARS-1049: Master Installation Script
-- CSV Encoding Support Implementation

PROMPT ================================================
PROMPT MARS-1049: Installing CSV Encoding Support
PROMPT ================================================

SPOOL install_mars1049.log

-- Faza 1: Struktura bazy danych
PROMPT Phase 1: Database Structure Changes
@@01_MARS_1049_install_CT_MRDS_ADD_ENCODING_COLUMN.sql

-- Faza 2: Pakiet FILE_MANAGER (Specyfikacja)
PROMPT Phase 2: FILE_MANAGER Package Specification
@@02_MARS_1049_install_CT_MRDS_FILE_MANAGER_SPEC.sql

-- Faza 3: Pakiet FILE_MANAGER (Ciało)
PROMPT Phase 3: FILE_MANAGER Package Body
@@03_MARS_1049_install_CT_MRDS_FILE_MANAGER_BODY.sql

-- Faza 4: Weryfikacja
PROMPT Phase 4: Functionality Verification
@@04_MARS_1049_verify_ENCODING_FUNCTIONALITY.sql

-- Faza 5: Tracking wersji
PROMPT Phase 5: Version Tracking
@@05_MARS_1049_track_version.sql

PROMPT ================================================
PROMPT MARS-1049: Installation completed successfully
PROMPT ================================================

SPOOL OFF

rollback_mars1049.sql (Master Rollback Script)

-- MARS-1049: Master Rollback Script
-- WARNING: This will remove ENCODING functionality

PROMPT ================================================
PROMPT MARS-1049: Rolling back CSV Encoding Support
PROMPT WARNING: This will remove ENCODING column and data!
PROMPT ================================================

SPOOL rollback_mars1049.log

-- Rollback w odwrotnej kolejności
@@94_MARS_1049_track_rollback_version.sql
@@93_MARS_1049_rollback_ENCODING_COLUMN.sql
@@92_MARS_1049_rollback_FILE_MANAGER_SPEC.sql
@@91_MARS_1049_rollback_FILE_MANAGER_BODY.sql

PROMPT ================================================
PROMPT MARS-1049: Rollback completed
PROMPT ================================================

SPOOL OFF

Deployment Commands

# Instalacja paczki MARS-1049
Get-Content "MARS_Packages\REL02\MARS-1049\install_mars1049.sql" | sql "CT_MRDS/Cloudpass#34@ggmichalski_high"

# W przypadku problemów - rollback
Get-Content "MARS_Packages\REL02\MARS-1049\rollback_mars1049.sql" | sql "CT_MRDS/Cloudpass#34@ggmichalski_high"

# Archiwizacja po instalacji
7z a -pMojeSuperHaslo -mhe=on MARS_1049_arch.7z MARS_Packages\REL02\MARS-1049\*.sql

Status: GOTOWE DO IMPLEMENTACJI

Utworzone: 2025-11-24 Autor: System FILE_MANAGER Enhancement MARS Issue: MARS-1049 Priorytet: WYSOKI

Reference in New Issue View Git Blame Copy Permalink