AKA Guides

{{TOC}}

Mỗi AKA-Form web app là 1 file Google Spreadsheet (sử dụng Google Apps Script phía sau), để tiết kiệm thời gian bạn nên bắt đầu với template có sẵn thay vì tạo mới mọi thứ từ đầu. Template bao gồm các sheet & Apps Script code project.

## Form Url

Các page/form của AKA-Form sẽ có địa chỉ theo format

**Địa chỉ publish webapp**?url=/form/**form-id**

```

https://script.google.com/macros/s/AKfycbwIjB-hULVZdfCtsXFPg4Af_8WoKx2AFf85KMVwnsO_WkeAXW3zarT6vZNFVfwccz1_sA/exec?url=/form/login

```

hoặc tham số đi kèm dạng **Địa chỉ publish webapp**?url=/form/**form-id**/ **tham-số**

```

https://script.google.com/macros/s/AKfycbwIjB-hULVZdfCtsXFPg4Af_8WoKx2AFf85KMVwnsO_WkeAXW3zarT6vZNFVfwccz1_sA/exec?url=/form/crud-employee/1

```

**1**  là record id truyền vào form CRUD Employee

Lưu ý: không nên đổi tên các SHEET dưới đây vì sẽ khiến app gặp lỗi

## Sheet Datasources

Sheet **Datasources** cấu hình nguồn dữ liệu (datasource) sử dụng với web app, hiện tại chỉ hỗ trợ datasource là Google Spreadsheets. Một datasouce có thể là 1 sheet cùng file với file spreadsheet app hoặc nằm bên ngoài. Các field bao gồm:

* **Id** : tên gợi nhớ để tham chiếu ở mục khác, không nên dùng  ký  tự trắng (space) trong giá trị của field Id.

* **Url** : chứa địa chỉ của file spreadsheet nếu sheet của datasouce không nằm cùng file spreadsheet bot 

* **Sheet**: tên sheet sẽ truy vấn.

* **Range**: vùng địa chỉ sẽ truy vấn, ví dụ: A1:J... 

* **Header**: số lượng dòng (row) làm header có trong Range dữ liệu

* **Cached**: Yes: cache data được load, tăng hiệu suất ứng dụng

* **Note**: Ghi chú bổ sung

## Sheet Users

Trường hợp app có sử dụng authentication, sheet **Users** cung cấp cách thức để quản lý user đơn giản. Người dùng đăng nhập với Email & Password. 

Sheet **Users** bao gồm các field :

* **Name** : tên gợi nhớ để tham chiếu ở mục khác.

* **Email** : Email để đăng nhập, không nhất thiết phải email có thực, định dạng giá trị phải là 1 email hợp lệ

* **Password**: Mật khẩu để đăng nhập. Password được mã hóa bằng hàm md5, ví dụ *md5("Hello") => 8b1a9953c4611296a827abf8c47804d7*

* **IsActive**: **Yes** : user đang hoạt động, **No** : User bị khóa

* **Note**: Ghi chú bổ sung

## Sheet Forms

AKA-Form web app là tập hợp các form/page độc lập. Sự liên hệ giữa các form được quy định trong từng form, ví dụ: để truy cập form Customers thì bắt buộc phải login trước. Logic này sẽ được cài đặt bằng Javascript trong form Customers, nếu thông tin đăng nhập không hợp lệ sẽ redirect sang form Login.

Sheet **Forms** bao gồm các field :

* **Id** : tên gợi nhớ để tham chiếu ở mục Url, không ký tự trắng (space) hoặc ký tự đặc biệt.

* **Name** : tên gợi nhớ để tham chiếu ở mục khác, có thể bao gồm khoảng trắng

* **Html**: HTML code (JS/CSS) để tạo nên front-end của form/page, hỗ trợ [Templated HTML](https://developers.google.com/apps-script/guides/html/templates)

* **Template**: Form JSON sinh ra bởi [Form.IO Builder](https://formio.github.io/formio.js/app/sandbox.html)

* **Database**: Tên datasource sẽ đọc dữ liệu, trong trường hợp form Edit sẽ kiểm tra Database có chứa record với id edit tương ứng

* **References**: Trường hợp các thành phần UI của form có sử dụng data lookup, ví dụ: trong form Order, combobox Products sẽ cần load danh sách product bằng cách tham chiếu đến Reference tương ứng cấu hình trong Form JSON

* **SubForms**: Phần nâng cao, dành cho form không sử dụng cơ chế lưu trữ Document mà lưu phẳng trong Spreadsheet

* **NewUrl**: Url để tạo mới record, cũng là template url sử dụng Google Form đóng vai trò làm backend lưu trữ, ví dụ: https://docs.google.com/forms/d/e/1FAIpQLScLnowNlnQXZvp8yFmTcuGFXi0C71K8I9mDNvk8Jha-rRcI3Q/formResponse?entry.779708373=Employees&entry.1745485693={Document}&entry.26640752={Id}&entry.967646527={CreatedBy}&entry.1408490212={ModifiedBy}&entry.2129865903={CreatedAt}&entry.95214425={ModifiedAt}&entry.988375443={IsDeleted}*

* **Link**: đơn thuần là lối tắt để truy cập form, format dạng *[web-app-published-url]?url=/form/<Id>* 

## Sheet SubForms

SubForm được sử dụng trường hợp lưu trữ dạng phẳng (flatten) thay vì dạng Document. Mô hình Document đơn giản trong việc cấu hình và query dữ liệu khi mọi data được tổ chức thành 1 document (nested objects). Dạng phẳng (flatten) được lưu trữ riêng biệt cho từng object trong form. Mỗi object được lưu ở 1 sheet riêng biệt. Dạng phẳng không cần tốn thêm công đoạn bóc tách dữ liệu bằng AKA-Bot để làm báo cáo.

Sheet **SubForms** bao gồm các field :

* **Id** : tên gợi nhớ để tham chiếu ở mục Url, không ký tự trắng (space) hoặc ký tự đặc biệt.

* **Name** : tên gợi nhớ để tham chiếu ở mục khác, có thể bao gồm khoảng trắng

* **Collection** : Thuộc tính tham chiếu trong đối tượng dữ  liệu JSON của form submission

* **Database**: Tên datasource sẽ đọc dữ liệu, trong trường hợp form Edit sẽ kiểm tra Database có chứa record với id edit tương ứng

* **NewUrl**: Url để tạo mới record, cũng là template url sử dụng Google Form đóng vai trò làm backend lưu trữ.

## Sheet System

Sheet **System**  lưu các setting/configuration dạng Key-Value để dùng trong module/app. Trong config, có thể truy cập các key bằng cú pháp template <#Key#>. Các field bao gồm:

* **Key** : tên gợi nhớ để tham chiếu ở mục khác, không nên dùng  ký  tự trắng (space) trong giá trị của field Key.

* **Value** : Giá trị mặc định. Giá trị không nhất thiết là giá trị tĩnh (static), bạn có thể sử dụng Google Sheets formula để tạo giá trị động (dynamic) phù hợp với yêu cầu business.

* **Note** : Ghi chú (tùy chọn)

## Sheet Log

App ghi nội dung log trong quá trình thực thi. Level gồm:

* Trace = 0

* Debug = 1

* Info = 2

* Warn = 3

* Error = 4

Apps Scripts Project Settings có thuộc tính app.logLevel đế set giá trị global cho log level

**Giá trị mặc là 2 => chỉ xuất ra sheet Log các log entry Level từ Info trở lên**