| name | iaud-module-create |
| description | i-AUD 모듈(Module) 생성 가이드. Module/ 폴더에 TypeScript 원본 소스(.ts)와 모듈 JSON 모델(.module.md) 2개 파일을 작성합니다. "모듈 만들기", "모듈 생성", "프로세스 봇 모듈", "워크플로우 모듈" 등을 요청할 때 사용하세요. |
i-AUD 모듈(Module) 생성 가이드
1. 모듈이란?
i-AUD 모듈은 프로세스 봇(WorkFlow)에서 재활용할 수 있는 클라이언트 스크립트 단위입니다.
모듈은 익명 함수 형태로 호출되며, 파라미터는 arguments[n]으로 전달받습니다.
실행 구조:
(function() {
// ← SCRIPT_TEXT 내용이 여기에 들어감
// arguments[0], arguments[1], ... 로 파라미터 수신
})(파라미터1값, 파라미터2값, ...)
2. 모듈 폴더 구조 및 출력 파일
모듈은 보고서 폴더 하위에 Modules/ 전용 폴더를 만들어 관리합니다.
각 모듈은 2개의 파일을 생성합니다:
reports/
├── Modules/ ← 모듈 전용 폴더
│ ├── [모듈제목].ts ← ① 원본 TypeScript 소스 (개발/유지보수용)
│ ├── [모듈제목].module.md ← ② 모듈 JSON 모델 (배포용, 확장자 .md)
│ ├── [다른모듈].ts
│ └── [다른모듈].module.md
└── ...
2.1 파일별 역할
| 파일 | 확장자 | 용도 |
|---|
| 원본 TypeScript 소스 | .ts | 가독성 있는 원본 스크립트. 주석, 포맷팅 포함. 수정/유지보수 시 이 파일을 편집 |
| 모듈 JSON 모델 | .module.md | i-AUD 서버에 등록할 모듈 정의 JSON. SCRIPT_TEXT는 이스케이프된 한 줄 문자열 |
왜 2개 파일인가?
.ts 파일: 사람이 읽고 수정하기 쉬운 원본 코드 (주석, 들여쓰기 유지).module.md 파일: 서버 등록용 JSON 모델 (SCRIPT_TEXT가 이스케이프되어 직접 편집이 어려움)- TypeScript 소스를 수정한 후, JSON 모델의 SCRIPT_TEXT를 갱신하는 방식으로 유지보수합니다.
참고: .module.md 확장자를 사용하는 이유는 마크다운 뷰어에서 JSON 구조를 쉽게 확인할 수 있고, 별도 파서 충돌 없이 관리하기 위함입니다.
2.2 원본 TypeScript 소스 (.ts) 작성 규칙
원본 TypeScript 파일은 사람이 읽기 쉬운 형태로 작성합니다.
실제 모듈 런타임은 순수 JavaScript이지만, 개발/유지보수를 위해 TypeScript 형태로 보관합니다.
var gridName = (arguments[0] || "").trim();
var chartName = (arguments[1] || "").trim();
var titleText = (arguments[2] || "").trim();
var errors: string[] = [];
if (!gridName) errors.push("그리드 이름은 필수입니다.");
if (!chartName) errors.push("차트 이름은 필수입니다.");
if (errors.length > 0) {
Matrix.Alert("파라미터 오류\n\n" + errors.join("\n"));
return;
}
var grid = Matrix.getObject(gridName);
var chart = Matrix.getObject(chartName);
핵심: 원본 .ts 파일의 상단 주석에 각 파라미터의 arguments 인덱스, PARAM_TYPE, 필수 여부를 반드시 기록합니다.
2.3 모듈 JSON 모델 (.module.md) 전체 구조
{
"TYPE": "Single",
"MTX_MODULE_INFO": [
{
"MODULE_CODE": "",
"MODULE_SUBJECT": "모듈 제목",
"USE_AUTHORITY": "0",
"EDIT_AUTHORITY": "-1",
"MODULE_DESCRIPTION": "모듈 설명",
"SCRIPT_TEXT": "... JavaScript 소스코드 ...",
"MODULE_TYPE": "",
"RESULT_TYPE": "",
"ORIGINAL_MODULE_CODE": "",
"CREATE_USER": "",
"MODIFY_USER": "",
"MODULE_SEQ": "3",
"WF_YN": "",
"EVENT_YN": "N",
"ATTR1": "",
"ATTR2": "",
"ATTR3": "",
"MTX_MODULE_PARAMS": [
{
"MODULE_CODE": "",
"PARAM_SEQ": "1",
"PARAM_TYPE": "INP001",
"NULLABLE": "N",
"PARAM_DESCRIPTION": "파라미터 설명",
"DEFAULT_VALUE": "",
"ATTR1": "",
"ATTR2": "",
"ATTR3": ""
}
]
}
]
}
2.4 주요 필드 설명
| 필드 | 설명 | 비고 |
|---|
MODULE_CODE | 모듈 고유코드 | 빈 문자열 (서버에서 자동 생성) |
MODULE_SUBJECT | 모듈 제목 | 사용자에게 표시되는 이름 |
MODULE_DESCRIPTION | 모듈 설명 | 줄바꿈은 \n 사용 |
SCRIPT_TEXT | JavaScript 소스코드 | 익명 함수 본문 (아래 작성 규칙 참조) |
EVENT_YN | 이벤트 등록 모듈 여부 | "Y" 또는 "N" |
WF_YN | WorkFlow 전용 여부 | "Y" 또는 빈 문자열 |
MTX_MODULE_PARAMS | 파라미터 정의 배열 | 필수 — 반드시 정의해야 함 (아래 파라미터 섹션 참조) |
2.5 EVENT_YN 판단 기준
"N" (기본): 모듈 실행 시 즉시 동작하고 완료 (예: 값 설정, 데이터 변환, Alert 표시)"Y": 모듈이 이벤트 핸들러를 등록하여 이후 사용자 동작에 반응 (예: 버튼 클릭 시 동작, 그리드 데이터 바인딩 시 동작)
3. 파라미터 설정 (MTX_MODULE_PARAMS) — ⚠️ 필수
⚠️ 중요: 파라미터 정의는 절대 누락하지 마세요!
모듈의 MTX_MODULE_PARAMS 배열은 반드시 작성해야 합니다.
스크립트에서 arguments[n]으로 받는 모든 값에 대해 대응하는 파라미터를 정의해야 합니다.
파라미터가 누락되면 사용자가 모듈 실행 시 입력 UI가 표시되지 않아 모듈이 정상 동작하지 않습니다.
3.1 파라미터 필수 작성 규칙
- 스크립트의
arguments[n] 수 = MTX_MODULE_PARAMS 배열 길이와 반드시 일치해야 합니다
PARAM_SEQ: "1"부터 순서대로 증가하며, arguments 인덱스 + 1 입니다PARAM_TYPE: 각 파라미터의 용도에 맞는 적절한 타입을 선택합니다PARAM_DESCRIPTION: 사용자가 이해할 수 있는 명확한 설명을 작성합니다NULLABLE: 필수 파라미터는 "N", 선택 파라미터는 "Y"로 설정합니다DEFAULT_VALUE: 선택 파라미터는 합리적인 기본값을 설정합니다
3.2 파라미터 타입 (PARAM_TYPE)
| 코드 | 설명 | UI 동작 | arguments 값 |
|---|
INP001 | 텍스트 입력 | 텍스트 입력창 | string |
INP002 | 정수 입력 | 숫자 입력창 | string (정수) |
INP021 | 실수 입력 | 숫자 입력창 (소수점) | string (실수) |
INP003 | 데이터 그리드 선택 | 그리드 목록에서 선택 | string (컨트롤명) |
INP004 | 단일 컨트롤 선택 | 컨트롤 목록에서 하나 선택 | string (컨트롤명) |
INP005 | 다중 컨트롤 선택 | 컨트롤 목록에서 여러 개 선택 | string (콤마 구분) |
INP006 | Form 선택 | Form 목록에서 선택 | string (Form명) |
INP007 | 데이터 소스 선택 | 데이터소스 목록에서 선택 | string (데이터소스명) |
INP008 | Y/N 선택 | 체크박스 | string ("Y" 또는 "N") |
INP009 | BoxStyle 선택 | BoxStyle 목록에서 선택 | string (스타일코드) |
INP010 | ServerScript 선택 | 서버스크립트 목록에서 선택 | string (스크립트명) |
INP011 | 실행계획 선택 | 실행계획 목록에서 선택 | string (실행계획명) |
INP020 | 보고서 선택 | 보고서 선택 다이얼로그 | string (보고서코드) |
INP999 | 사용자 정의 목록 | 드롭다운 선택 | string (선택값) |
INP999 사용 시 ATTR1 설정
INP999는 ATTR1에 파이프(|)로 구분한 선택 목록을 정의합니다. 항목의 실제 값과 사용자에게 표현값을 달리하려면 값;표시문자 형태로 합니다.
{
"PARAM_TYPE": "INP999",
"PARAM_DESCRIPTION": "집계 함수를 선택해 주세요.",
"DEFAULT_VALUE": "SUM",
"ATTR1": "SUM;합계|COUNT;개수|AVG;평균|MIN;최소값|MAX;최대값"
}
4. 스크립트 작성 규칙
4.1 핵심 규칙
- 순수 JavaScript로 작성 - TypeScript 문법 사용 불가 (var 사용, 타입 어노테이션 없음)
- 익명 함수 본문 - function 선언 없이 바로 실행 코드 작성
- 파라미터는
arguments[n] - 0부터 시작, 모두 string 타입
Matrix 객체 사용 가능 - 전역으로 접근 가능EXECUTE_NEXT() 호출 - WorkFlow에서 다음 단계로 진행 시 호출 (비동기 작업 완료 후)
- 원형:
EXECUTE_NEXT(success?: boolean, message?: string)
- 비동기 콜백 내부에서 호출하여 다음 모듈로 제어를 넘김
success 생략 또는 true: 성공 → 다음 모듈 실행success = false: 실패 → WorkFlow 실패 분기로 이동, message에 오류 메시지 전달- 동기 모듈(즉시 완료)에서는 호출하지 않아도 됨 (자동으로 다음 단계 진행)
- 비동기 모듈에서
EXECUTE_NEXT()를 호출하지 않으면 WorkFlow가 멈추므로 반드시 모든 분기에서 호출 필요
- SCRIPT_TEXT는 한 줄 문자열 - JSON 내에서 줄바꿈은
\n, 따옴표는 \", 탭은 \t로 이스케이프
4.2 스크립트 구조 패턴
var gridName = (arguments[0] || "").trim();
var chartName = (arguments[1] || "").trim();
var errors = [];
if (!gridName) errors.push("그리드 이름은 필수입니다.");
if (errors.length > 0) {
Matrix.Alert("파라미터 오류\n\n" + errors.join("\n"));
return;
}
function doSomething() {
var grid = Matrix.getObject(gridName);
}
doSomething();
grid.OnDataBindEnd = function() { ... };
4.2.1 비동기 모듈 패턴 (EXECUTE_NEXT 사용)
비동기 작업(서버 호출, 실행 계획 등)이 포함된 모듈은 콜백 완료 시 EXECUTE_NEXT()를 호출하여 WorkFlow의 다음 단계로 진행합니다.
var planName = arguments[0];
Matrix.ExecutePlan(planName, "", function(p) {
if (p.Success == false) {
EXECUTE_NEXT(false, p.Message);
} else {
EXECUTE_NEXT();
}
});
주의: 비동기 모듈에서는 모든 콜백 분기(성공/실패)에서 EXECUTE_NEXT()를 호출해야 합니다. 누락하면 WorkFlow가 멈춥니다.
4.3 이벤트 등록 모듈 패턴 (EVENT_YN = "Y")
이벤트를 등록하는 모듈은 실행 즉시 이벤트 핸들러를 바인딩하고, 이후 사용자 동작 시 실제 로직이 동작합니다.
var controlName = arguments[0];
var grid = Matrix.getObject(controlName);
if (grid) {
grid.OnDataBindEnd = function(_sender, _args) {
};
}
4.4 사용 가능한 API
모듈 스크립트에서는 클라이언트 스크립트 API를 사용합니다:
Matrix.getObject(name) - 컨트롤 참조Matrix.Alert(msg) / Matrix.Confirm(msg, title, callback, type) - 메시지Matrix.CreateDataSet() - DataSet 생성Matrix.doRefresh(controlNames) - 컨트롤 새로고침Matrix.ExecutePlan(planName, params, callback) - 실행계획 호출Matrix.RunScriptEx(targets, serviceName, params, callback) - 서버 스크립트 호출- Grid:
GetDataSet(), GetFields(), GetRowCount(), SetDataSet(), Calculate(), Draw()
- DataTable:
GetRowCount(), getData(rowIdx, fieldName), setData(rowIdx, fieldName, value), AppendRow(), AddColumn(name, isNumber)
- Chart:
SetDataSet(ds), Draw()
자세한 API는 /iaud-client-script 스킬 또는 types/aud/ 폴더의 TypeScript 인터페이스를 참조하세요.
5. 기존 모듈 조회 (MCP 도구)
모듈을 새로 만들기 전에, 이미 유사한 기능의 모듈이 서버에 등록되어 있는지 확인합니다.
기존 모듈을 재활용하거나 참고하면 개발 시간을 절약할 수 있습니다.
5.1 get_module_list — 모듈 목록 조회
서버에 등록된 모듈 목록을 검색합니다.
MCP 도구: get_module_list
파라미터:
- filter (선택): 모듈명/설명 검색어
- limitRows (선택, 기본 500): 조회 최대 행 수
반환 필드:
| 필드 | 설명 |
|---|
MODULE_CODE | 모듈 고유 코드 |
MODULE_SUBJECT | 모듈 제목 |
MODULE_DESCRIPTION | 모듈 설명 |
EVENT_YN | 이벤트 등록 모듈 여부 (Y/N) |
5.2 get_module_params — 모듈 파라미터 조회
특정 모듈의 파라미터 정의를 조회합니다.
MCP 도구: get_module_params
파라미터:
- moduleCode (필수): 모듈 코드 (get_module_list에서 조회한 MODULE_CODE)
반환 필드:
| 필드 | 설명 |
|---|
MODULE_CODE | 모듈 코드 |
PARAM_SEQ | 파라미터 순번 (1부터) |
PARAM_TYPE | 파라미터 타입 (INP001~INP999) |
NULLABLE | 필수 여부 (Y: 선택, N: 필수) |
PARAM_DESCRIPTION | 파라미터 설명 |
ATTR1 | INP999일 때 선택 목록 등 부가 정보 |
ATTR2 | 부가 속성 2 |
ATTR3 | 부가 속성 3 |
DEFAULT_VALUE | 기본값 |
5.3 활용 흐름
1. get_module_list(filter: "키워드")로 유사 모듈 검색
2. 유사 모듈이 있으면 → get_module_params(moduleCode)로 파라미터 구조 확인
3. 재활용 가능 → 기존 모듈 사용 안내
4. 유사하지만 다름 → 기존 모듈 참고하여 새 모듈 작성
5. 없음 → 새 모듈 생성 (아래 절차)
6. 모듈 생성 절차
사용자가 모듈 생성을 요청하면 아래 순서로 진행합니다:
Step 1: 요구사항 파악
사용자 요청에서 다음을 파악합니다:
- 모듈이 무엇을 하는지 (기능)
- 어떤 컨트롤을 대상으로 하는지
- 사용자에게 어떤 입력을 받아야 하는지
- 즉시 실행인지 이벤트 등록인지
Step 2: 파라미터 설계 — ⚠️ 반드시 수행
⚠️ 이 단계를 건너뛰지 마세요! 파라미터 누락은 모듈 실행 실패의 가장 흔한 원인입니다.
- 스크립트에서
arguments[n]으로 받는 모든 값을 파라미터로 정의
- 각 입력 항목에 적합한
PARAM_TYPE 선택
- 필수/선택 여부(
NULLABLE) 결정
- 사용자 친화적인 설명(
PARAM_DESCRIPTION) 작성
- 기본값(
DEFAULT_VALUE) 설정
- 검증:
arguments 개수와 MTX_MODULE_PARAMS 배열 길이가 일치하는지 확인
Step 3: TypeScript 원본 소스 작성
Modules/[모듈제목].ts 파일 생성- 상단 주석에 파라미터 목록 (인덱스, PARAM_TYPE, 필수 여부) 기록
- 파라미터 수신 및 검증 코드
- 비즈니스 로직 함수
- 실행 코드 또는 이벤트 등록 코드
Step 4: 모듈 JSON 모델 (.module.md) 출력
Modules/[모듈제목].module.md 파일 생성- JSON 구조에 맞게 조립
- SCRIPT_TEXT를 JSON 문자열로 이스케이프 (Step 3의 .ts 소스 기반)
MTX_MODULE_PARAMS 배열이 빠짐없이 정의되었는지 재확인src/reports/Modules/ 하위에 저장
7. 샘플 모듈
7.1 간단한 모듈: 컨트롤 값 초기화
{
"TYPE": "Single",
"MTX_MODULE_INFO": [
{
"MODULE_CODE": "",
"MODULE_SUBJECT": "컨트롤 값 초기화 하기",
"MODULE_DESCRIPTION": "선택된 컨트롤들의 값을 초기화 합니다.\n값은 빈 값으로 설정합니다.",
"SCRIPT_TEXT": "var controls = arguments[0].split(\",\");\nvar ctl;\nfor(var i=0;i<controls.length; i++){\n\tctl = Matrix.getObject(controls[i]);\n\tif(ctl){\n\t\ttry{\n\t\t\tif(typeof ctl.SetValue == \"function\"){\n\t\t\t\tctl.SetValue(\"\");\n\t\t\t}else{\n\t\t\t\tif(ctl.Checked=== true){\n\t\t\t\t\tctl.Checked = false;\n\t\t\t\t}\n\t\t\t}\n\t\t}catch(e){}\n\t}\n}",
"USE_AUTHORITY": "0",
"EDIT_AUTHORITY": "-1",
"MODULE_TYPE": "",
"RESULT_TYPE": "",
"ORIGINAL_MODULE_CODE": "",
"CREATE_USER": "",
"MODIFY_USER": "",
"MODULE_SEQ": "3",
"WF_YN": "Y",
"EVENT_YN": "Y",
"ATTR1": "",
"ATTR2": "",
"ATTR3": "",
"MTX_MODULE_PARAMS": [
{
"MODULE_CODE": "",
"PARAM_SEQ": "1",
"PARAM_TYPE": "INP005",
"NULLABLE": "N",
"PARAM_DESCRIPTION": "대상 컨트롤 목록",
"DEFAULT_VALUE": "",
"ATTR1": "",
"ATTR2": "",
"ATTR3": ""
}
]
}
]
}
7.2 이벤트 등록 모듈: 체크박스 변경 시 조회
{
"TYPE": "Single",
"MTX_MODULE_INFO": [
{
"MODULE_CODE": "",
"MODULE_SUBJECT": "체크박스 상태 변경 시 특정 컨트롤 조회 하기",
"MODULE_DESCRIPTION": "체크 박스 클릭 시 특정 컨트롤을 조회 합니다.",
"SCRIPT_TEXT": "var controlNames = arguments[0];\nvar refreshCtls = arguments[1];\nvar controls = controlNames.split(\",\");\nvar chkBox, name;\nfor(var i=0; i<controls.length; i++){\n\tname = controls[i].trim();\n\tchkBox = Matrix.getObject(name);\n\tif(chkBox){\n\t\tchkBox.OnValueChange = function(s, e){\n\t\t\tMatrix.doRefresh(refreshCtls);\n\t\t};\n\t}\n}",
"USE_AUTHORITY": "0",
"EDIT_AUTHORITY": "-1",
"MODULE_TYPE": "",
"RESULT_TYPE": "",
"ORIGINAL_MODULE_CODE": "",
"CREATE_USER": "",
"MODIFY_USER": "",
"MODULE_SEQ": "3",
"WF_YN": "",
"EVENT_YN": "N",
"ATTR1": "",
"ATTR2": "",
"ATTR3": "",
"MTX_MODULE_PARAMS": [
{
"MODULE_CODE": "",
"PARAM_SEQ": "1",
"PARAM_TYPE": "INP005",
"NULLABLE": "N",
"PARAM_DESCRIPTION": "체크 박스 컨트롤 목록",
"DEFAULT_VALUE": "",
"ATTR1": "",
"ATTR2": "",
"ATTR3": ""
},
{
"MODULE_CODE": "",
"PARAM_SEQ": "2",
"PARAM_TYPE": "INP005",
"NULLABLE": "N",
"PARAM_DESCRIPTION": "조회 대상 컨트롤",
"DEFAULT_VALUE": "",
"ATTR1": "",
"ATTR2": "",
"ATTR3": ""
}
]
}
]
}
7.3 복합 모듈: 데이터 그리드 필터·그룹핑 → 차트 바인딩
파라미터 6개, 입력 검증, 이벤트 등록을 포함하는 복합 모듈입니다.
실제 샘플은 src/reports/Modules/차트 데이터 구성하기 (데이터 그리드 필터 및 그룹).module.md을 참조하세요.
주요 특징:
INP003(그리드 선택), INP004(차트 선택), INP001(텍스트), INP999(목록 선택) 활용- arguments 수신 → validate → 이벤트 등록 → 비즈니스 함수 호출 패턴
grid.GetFields()로 Caption → Name 변환 처리
8. SCRIPT_TEXT JSON 이스케이프 규칙
SCRIPT_TEXT는 JSON 문자열이므로 다음을 이스케이프해야 합니다:
| 원본 | 이스케이프 |
|---|
| 줄바꿈 | \n |
| 탭 | \t |
쌍따옴표 " | \" |
역슬래시 \ | \\ |
중요: JavaScript 코드를 먼저 작성한 뒤, JSON 문자열로 변환하여 SCRIPT_TEXT에 넣습니다.
9. MCP 검증 도구 (validate_module)
모듈 JSON 파일을 작성한 후, MCP validate_module 도구를 호출하여 스키마 검증을 수행합니다.
사용 방법
MCP 도구: validate_module
파라미터:
- path: 모듈 JSON 파일의 전체 경로
또는
- document: 모듈 JSON 문자열/객체
검증 항목
스키마 검증 (에러):
TYPE이 "Single"인지- 필수 필드 존재 여부 (
MODULE_SUBJECT, SCRIPT_TEXT, USE_AUTHORITY, EDIT_AUTHORITY, MODULE_DESCRIPTION, MODULE_SEQ, EVENT_YN)
MODULE_SUBJECT, SCRIPT_TEXT가 빈 문자열이 아닌지EVENT_YN이 "Y" 또는 "N"인지WF_YN이 "Y", "N", 또는 빈 문자열인지PARAM_TYPE이 유효한 코드(INP001~INP999)인지NULLABLE이 "Y" 또는 "N"인지- 알 수 없는 속성이 포함되지 않았는지
비즈니스 로직 검증 (경고):
ATTR3="MTX"인 경우 MATRIX 내장 모듈로 서버에서 가져오기 거부 경고PARAM_TYPE="INP999"인데 ATTR1(선택 목록)이 비어있는 경우 경고PARAM_SEQ 순번이 배열 순서와 일치하지 않는 경우 경고
모듈 생성 절차에 통합
Step 4(.module.md 파일 출력) 이후 반드시 validate_module 도구를 호출하여 검증합니다.
오류가 발견되면 수정 후 재검증합니다.
10. 체크리스트
모듈 생성 시 아래 항목을 확인합니다:
📁 파일 구조
📝 모듈 정보
⚠️ 파라미터 (가장 중요)
🔧 스크립트 품질
