@things-factory/integration-base 6.1.115 → 6.1.117

package/helps/integration/task/oracle-procedure.ko.md

@@ -0,0 +1,135 @@
+# Oracle Procedure Task
+
+Oracle 데이터베이스에 저장되어 있는 프로시저를 호출하는 태스크이며, 
+개별 데이터 타입에 따라서 데이터의 리스트 혹은 특정 데이터 타입의 값을 반환한다.
+
+## Parameters
+
+### 프로시저
+  - 프로시저를 호출하는 함수부를 작성한다. 작성 시에 BEGIN과 END는 실제 내부에서 추가되기 때문에 별도로 지정할 필요가 없다.
+  - 호출 이후에 ;을 추가해야 한다.
+  - 프로시저의 입출력 파라미터는 :과 함께 사용한다.
+  - 프로시저 작성 예는 다음과 같다.
+    
+    ```sql
+    mcs.myproc(:id, :out_name);
+    ```
+
+### 파라미터
+  - 파라미터는 다음과 같은 요소로 구성되어 있다.
+    - 파라미터 이름
+    - 입출력 지정: IN, INOUT, OUT
+    - 파라미터 타입: String, Number, Date, Cursor
+    - 값: 해당 변수가 입력일 경우, 해당 입력에 대한 값
+    - 최대크기: 해당 변수타입이 String이나 Buffer일 경우, 변수의 최대 크기를 지정.
+
+#### 파라미터 이름
+
+파라미터 이름은 프로시저 작성에 사용된 파라미터의 이름을 지정한다.
+앞의 예의 경우,
+  ```sql
+  mcs.myproc(:id, :out_name);
+  ```
+id와 out_name이 각각 파라미터 이름이다.
+
+### 입출력 지정
+
+해당 변수가 입력(IN) 혹은 출력(OUT) 여부를 지정한다.
+
+### 파라미터 타입
+
+파라미터 타입을 지정한다. 타입은 실제 프로시저 생성 시에 지정되어 있는 이름과 동일하게 지정되어야 한다.
+
+프로시저가 다음과 같이 구현되어 있다면,
+
+```sql
+CREATE OR REPLACE NONEDITIONABLE PROCEDURE myproc (in_id IN VARCHAR2, out_name OUT VARCHAR2) AS
+BEGIN
+    SELECT name INTO out_name FROM MCS.FMB_USERS WHERE id = in_id ;
+END;
+```
+
+첫번째 파라미터와 두번째 파라미터 모두 VARCHAR2로 지정되어 있으며, 
+
+이러한 프로시저를 호출해야 할 경우 파라미터 타입은 모두 String을 지정해야 하고, 
+출력의 경우, 최대 크기까지 지정해야 한다.
+
+호출 지정 예는 다음과 같다.
+
+![procedure example1](./assets/../../../../assets/images/oracle-procedure-example1.png 'procedure example1')
+
+
+### 접근자 [accessor](../concept/data-accessor.md)
+
+설정 방법은 [JSONATA 도큐먼트](http://docs.jsonata.org/overview.html)를 따른다.
+
+
+### 값
+
+파라미터가 입력(IN)일 경우, 해당 값을 지정한다. 
+해당 값에 바로 상수 값을 입력하지 않고, 특정 태스크 이름을 지정하도록 한다.
+
+위의 예어서 id의 입력 값을 ID라고 지정되어 있다면, ID 태스크에서 반환되는 값을 입력 값으로 지정한다.
+
+
+### 최대 크기
+
+파라미터 타입이 String이나 Buffer 일 경우, 최대 크기를 지정한다. 다른 타입의 경우 값을 지정하지 않고 무시한다.
+
+## 태스크 결과
+
+프로시저 호출에 대한 결과는 Object 형태로 반환되며, 파라미터 중에서 출력으로 지정된 파라미터 이름이 키가 되어 값을 반환한다.
+
+만약, 위에서 소개된 태스크의 경우 다음과 같은 결과 값을 반환한다.
+
+```javascript
+{
+  out_name: 'Admin'
+}
+```
+
+
+## 다른 사용 예(커서)
+
+### 프로시저 작성 예
+
+```sql
+CREATE OR REPLACDE NONEDITIONABLE PROCEDURE PROCEDURE1(out_cursor OUT SYS_REFCURSOR) AS 
+BEGIN
+    BEGIN
+        OPEN out_cursor FOR
+            SELECT * FROM FARMWEATHER WHERE rownum <= 1000;
+    END;
+END PROCEDURE1;
+
+```
+
+### 프로시저 호출 예
+
+![procedure example2](./assets/../../../../assets/images/oracle-procedure-example2.png 'procedure example2')
+
+### 프로시저 태스크 호출 결과
+
+```javascript
+{
+  "out_cursor": [
+    {
+      "FARMDATE": "2006-01-07T15:00:00.000Z",
+      "MAXT": 29.5,
+      "MINT": 21.8,
+      "WINDSPEED": 1.6,
+      "FARMHUM": 70.2,
+      "PRECIPITATION": 0
+    },
+    {
+      "FARMDATE": "2006-01-08T15:00:00.000Z",
+      "MAXT": 30.1,
+      "MINT": 21,
+      "WINDSPEED": 1.6,
+      "FARMHUM": 67.4,
+      "PRECIPITATION": 0
+    },
+    ..
+  ]
+}
+```

package/helps/integration/task/oracle-procedure.md

@@ -0,0 +1,136 @@
+# Oracle Procedure Task
+
+A task that calls a procedure stored in an Oracle database, 
+Depending on the individual data type, it returns a list of data or a value of a specific data type.
+
+## Parameters
+
+### Procedure
+  - Write a function that calls the procedure. You don't need to specify BEGIN and END at the time of writing because they are actually added internally.
+  - You need to add ;after the call.
+  - The input and output parameters of a procedure are used with :.
+  - An example of writing a procedure is as follows
+    
+    ```sql
+    mcs.myproc(:id, :out_name);
+    ```
+
+### Parameters
+  - A parameter consists of the following elements
+    - The parameter name
+    - Input/output designation: IN, INOUT, OUT
+    - Parameter type: String, Number, Date, Cursor
+    - Value: If the variable is an input, the value for that input.
+    - MaxSize: If the variable is of type String or Buffer, specifies the maximum size of the variable.
+
+#### Paramter name
+
+Parameter name specifies the name of the parameter used in the procedure.
+For the previous example,
+
+  ```sql
+  mcs.myproc(:id, :out_name);
+  ```
+
+id and out_name are the parameter names, respectively.
+
+### In/Out Type
+
+Specifies whether the variable is an input (IN) or output (OUT).
+
+### Paramter type
+
+Specifies the parameter type. The type must be the same as the name given to the actual procedure when it is created.
+
+If the procedure is implemented as follows,
+
+```sql
+CREATE OR REPLACE NONEDITIONABLE PROCEDURE myproc (in_id IN VARCHAR2, out_name OUT VARCHAR2) AS
+BEGIN
+    SELECT name INTO out_name FROM MCS.FMB_USERS WHERE id = in_id ;
+END;
+```
+
+Both the first and second parameters are specified as VARCHAR2, 
+
+If you need to call these procedures, the parameter types should all be String, 
+For the output, the maximum size should be specified.
+
+An example call specification is as follows
+
+![procedure example1](./assets/../../../../assets/images/oracle-procedure-example1.png 'procedure example1')
+
+
+# Accessor [accessor](../concept/data-accessor.md)
+
+- Set when you want to propagate only a part of the data object of the source component or the transformed data.
+- The setting method follows [JSONATA document](http://docs.jsonata.org/overview.html).
+
+### Value(for Input)
+
+If the parameter is an input (IN), specify its value. 
+Do not enter a constant value directly into the value, but rather specify a specific task name.
+
+In the example above, if the input value for id is specified as ID, specify the value returned by the ID task as the input value.
+
+### Maxsize
+
+If the parameter type is String or Buffer, specify the maximum size. For other types, no value is specified and it is ignored.
+
+## Task Result
+
+The result of a procedure call is returned as an Object, where the name of the parameter specified as output is the key, and the value is returned.
+
+For example, the task introduced above returns the following result value.
+
+```javascript
+{
+  out_name: 'Admin'
+}
+```
+
+
+## Another Example(using cursor)
+
+### Procedure using cursor parameter
+
+```sql
+CREATE OR REPLACDE NONEDITIONABLE PROCEDURE PROCEDURE1(out_cursor OUT SYS_REFCURSOR) AS 
+BEGIN
+    BEGIN
+        OPEN out_cursor FOR
+            SELECT * FROM FARMWEATHER WHERE rownum <= 1000;
+    END;
+END PROCEDURE1;
+
+```
+
+### Task example to call the procedure using a cursor as an output
+
+![procedure example2](./assets/../../../../assets/images/oracle-procedure-example2.png 'procedure example2')
+
+### Task result
+
+```javascript
+{
+  "out_cursor": [
+    {
+      "FARMDATE": "2006-01-07T15:00:00.000Z",
+      "MAXT": 29.5,
+      "MINT": 21.8,
+      "WINDSPEED": 1.6,
+      "FARMHUM": 70.2,
+      "PRECIPITATION": 0
+    },
+    {
+      "FARMDATE": "2006-01-08T15:00:00.000Z",
+      "MAXT": 30.1,
+      "MINT": 21,
+      "WINDSPEED": 1.6,
+      "FARMHUM": 67.4,
+      "PRECIPITATION": 0
+    },
+    ...
+  ]
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/integration-base",
-  "version": "6.1.115",
+  "version": "6.1.117",
   "main": "dist-server/index.js",
   "browser": "client/index.js",
   "things-factory": true,
@@ -26,12 +26,12 @@
   },
   "dependencies": {
     "@apollo/client": "^3.6.9",
-    "@things-factory/api": "^6.1.115",
-    "@things-factory/auth-base": "^6.1.115",
-    "@things-factory/env": "^6.1.112",
-    "@things-factory/oauth2-client": "^6.1.115",
-    "@things-factory/scheduler-client": "^6.1.115",
-    "@things-factory/shell": "^6.1.115",
+    "@things-factory/api": "^6.1.116",
+    "@things-factory/auth-base": "^6.1.116",
+    "@things-factory/env": "^6.1.116",
+    "@things-factory/oauth2-client": "^6.1.116",
+    "@things-factory/scheduler-client": "^6.1.116",
+    "@things-factory/shell": "^6.1.116",
     "async-mqtt": "^2.5.0",
     "chance": "^1.1.11",
     "cross-fetch": "^3.0.4",
@@ -46,5 +46,5 @@
   "devDependencies": {
     "@types/cron": "^2.0.1"
   },
-  "gitHead": "3677982365595b0f3a8ec26e47c234878ecbb910"
+  "gitHead": "82d5cb1eab1ce608345fba651a221082c47915f5"
 }

package/server/engine/task/oracle-procedure.ts

@@ -10,7 +10,14 @@ try {
   logger.error('oracledb module loading failed')
 }
 
-type ProcedureParameterType = { name: string; dir: string; type: string; val: any; maxSize: number }
+type ProcedureParameterType = {
+  name: string
+  dir: string
+  type: string
+  val?: any
+  accessor?: string
+  maxSize?: number
+}
 
 const TYPES = {
   Number: oracledb.NUMBER,
@@ -48,20 +55,28 @@ async function OracleProcedure(step, context) {
 
   const procedureParameters =
     parameters &&
-    parameters.reduce((sum, { name, val, dir, type, maxSize }) => {
+    parameters.reduce((sum, { name, val, dir, type, accessor, maxSize }) => {
       sum[name] = {
         dir: DIR[dir],
-        type: TYPES[type],
-        val: access(val, data),
-        maxSize
+        type: TYPES[type]
       }
 
-      // remove empty keys
-      Object.keys(sum[name]).forEach(key => {
-        if (!sum[name][key]) {
-          delete sum[name][key]
-        }
-      })
+      const calculated = val !== undefined ? val : accessor ? access(accessor, data) : undefined
+
+      if (calculated !== undefined) {
+        sum[name].val =
+          type == 'Date'
+            ? new Date(calculated)
+            : type == 'Number'
+            ? Number(calculated)
+            : type == 'String'
+            ? String(calculated)
+            : calculated
+      }
+
+      if (maxSize) {
+        sum[name].maxSize = maxSize
+      }
 
       return sum
     }, {})
@@ -103,4 +118,6 @@ OracleProcedure.parameterSpec = [
   }
 ]
 
+OracleProcedure.help = 'integration/task/oracle-procedure'
+
 TaskRegistry.registerTaskHandler('oracle-procedure', OracleProcedure)