# Quy trình, biến và nút cấu trúc

Trang này mô tả cấu trúc của quy trình, làm tài liệu tham chiếu cho nhà phát triển và tác nhân AI viết quy trình. Hãy dùng [schema cấu trúc](/vi/browser-rpa/local-api#h%E1%BB%A3p-%C4%91%E1%BB%93ng-c%E1%BB%A5c-b%E1%BB%99-d%E1%BA%A1ng-m%C3%A1y-%C4%91%E1%BB%8Dc-%C4%91%C6%B0%E1%BB%A3c) cùng với trang này; [endpoint xác thực](/vi/browser-rpa/api/validate-workflow) chịu trách nhiệm về ngữ nghĩa. Để bắt đầu, xem [Tham chiếu Local API](/vi/browser-rpa/local-api) và [Bắt đầu nhanh](/vi/browser-rpa/quickstart).

## 1. Tài liệu và thứ tự

```json
{
  "editorVersion": 2,
  "editorParametersVersion": 1,
  "variables": {
    "type": "object",
    "properties": {}
  },
  "nodes": [
    {
      "id": "start",
      "type": "start"
    },
    {
      "id": "end",
      "type": "end",
      "data": {
        "inputsValues": {
          "status": {
            "type": "constant",
            "content": "success"
          },
          "message": {
            "type": "constant",
            "content": "Done"
          }
        }
      }
    }
  ]
}
```

Thao tác ghi chỉ chấp nhận editorVersion=2 và editorParametersVersion=1. Dữ liệu có phiên bản tham số 2 vẫn đọc được ở dạng gốc, nhưng bên gọi bên ngoài không âm thầm viết lại dữ liệu đó. Chỉ chỉnh sửa dữ liệu như vậy sau khi đã chuyển đổi tường minh trong ứng dụng máy tính. Thứ tự trong mảng là thứ tự thực thi, và blocks thể hiện cấu trúc lồng nhau. Không có cạnh, kết nối hay trạng thái kích hoạt.

Mảng gốc có start ở đầu và end ở cuối, mỗi loại đúng một nút. Mỗi nút có một id duy nhất. Chúng tôi khuyến nghị ID bắt đầu bằng một chữ cái ASCII, tiếp theo là chữ cái, chữ số hoặc dấu gạch dưới, và dài tối đa 64 ký tự. ID không được dùng các tên dành riêng của trình chỉnh sửa là `system`, `initVars` hoặc `custom`. ID của nhóm và nhánh cũng được tính vào yêu cầu về tính duy nhất. Một hành động thông thường dùng type=`browser_<action>`, data.browserAction phải khớp với type đó, và các đầu vào của hành động được đặt trong data.browserUi.inputs.

Vùng dữ liệu chung chứa title/description, meta (dữ liệu hiển thị dạng JSON) và data.inputs/outputs (mô tả dành cho trình chỉnh sửa; đầu ra của nút hành động do máy chủ tạo, xem [Các trường do máy chủ bổ sung](#c%C3%A1c-tr%C6%B0%E1%BB%9Dng-do-m%C3%A1y-ch%E1%BB%A7-b%E1%BB%95-sung)). Các giá trị trong browserUi.test và kết quả khởi tạo mô phỏng không phải là kết quả thực tế, vì vậy không dùng chúng để ra quyết định về một lượt chạy. Để xem hợp đồng tổng hợp của từng loại nút, hãy xem [hợp đồng nút tĩnh](/vi/browser-rpa/nodes). Hợp đồng này bao gồm cấu trúc đầu vào, giá trị mặc định, điều kiện, các biến thể đầu ra và chính sách trường.

## 2. Biến ban đầu: sáu kiểu trường

variables=`{type:'object',properties:{fieldName:Variable},required?:string[]}`. Tên tham số có thể chứa ký tự tiếng Trung. Tên không được rỗng sau khi loại bỏ khoảng trắng ở hai đầu, không được chứa `.`, `[`, `]`, `${` hoặc `}`, và không được trùng với custom/system/parameters hay bất kỳ ID nút nào trong quy trình này. Các tên `__proto__`, `constructor` và `prototype` bị cấm. Mọi mục trong required phải tồn tại trong properties, và các mục trùng lặp sẽ bị từ chối.

Một Variable công khai có thể dùng các thuộc tính sau: type, description, default và extra. Thuộc tính extra chứa cấu hình trình chỉnh sửa được khai báo bên dưới. Thao tác ghi công khai từ chối các trường không xác định có ảnh hưởng đến việc thực thi, và cấu hình hiển thị chỉ cho phép các trường đã được công bố. Một trường là bắt buộc khi `extra.required=true` hoặc khi danh sách required ở cấp cao nhất chứa trường đó. Chúng tôi khuyến nghị chỉ dùng required ở cấp cao nhất. Nếu hai cách này mâu thuẫn, thao tác ghi trả về 422 thay vì để tác nhân AI dựa vào một thứ tự ưu tiên ngầm định.

| Kiểu nghiệp vụ | Khai báo | Cấu hình extra và giá trị mặc định | Giá trị khi chạy thông thường |
|  --- | --- | --- | --- |
| Chuỗi | type=string | extra.private=false, localPath=false; charValid={enabled:false,value:…}; multiline={value:1,autoHeight:true} | kind=json, value là một chuỗi |
| Số | type=number; số nguyên cũng có thể dùng type=integer | decimalPlaces: mặc định là 2 với number và cố định là 0 với integer (giống trình chỉnh sửa); numberRange={enabled:false,min:null,max:null}; numberSuffix={enabled:false,value:''} | kind=json, value là một số hữu hạn; phạm vi và độ chính xác phải khớp với khai báo |
| Boolean | type=boolean | Không có cấu hình extra nghiệp vụ | kind=json, value là một giá trị boolean |
| Mảng | type=array | multiline={value:1,autoHeight:true} | kind=json, value là một mảng JSON; không truyền chuỗi JSON thay cho mảng |
| Đối tượng | type=object | multiline={value:1,autoHeight:true} | kind=json, value là một đối tượng JSON |
| Tệp | type=object cho một tệp, type=array cho nhiều tệp; extra.type=file | multipleFiles={enabled:false,unlimited:false,maxCount:9} (với nhiều tệp, bỏ qua maxCount cho phép tối đa 9 tệp, và chỉ unlimited=true mới bỏ giới hạn số lượng); formatType là một mảng phần mở rộng tệp; sizeLimit={unit:'KB' hoặc 'MB',value:số dương}, và khi bỏ qua trường này, mỗi tệp có thể lớn tối đa 10MB (giống trình chỉnh sửa) | kind=json, value là một chuỗi đường dẫn cục bộ tuyệt đối (một tệp) hoặc một mảng chuỗi (nhiều tệp). Máy chủ tham chiếu trực tiếp đến tệp tại đường dẫn đó, giống như khi chạy trong ứng dụng, mà không sao chép tệp. Đường dẫn phải tồn tại và đáp ứng các giới hạn về phần mở rộng, số lượng và kích thước. url mà nút nhận được chính là đường dẫn này. Tham số tệp không thể khai báo giá trị mặc định |


Thiết lập multiline.value là một số nguyên từ 1 đến 200. Với số ký tự, độ chính xác và giới hạn tệp, hợp đồng thực tế của ứng dụng là căn cứ; không dùng dữ liệu mô phỏng từ giao diện. Các trường extra.name/index/placeholder là trường hiển thị và không thay đổi tên dùng để tham chiếu tham số. fieldId là khóa trong properties.

Giá trị mặc định thông thường có hai cách biểu diễn sẵn có trong trình chỉnh sửa. Khuyến nghị dùng Variable.default, còn extra.defaultValue={enabled:true,value:…} được hỗ trợ để tương thích. Đặt tường minh extra.defaultValue.enabled=false nghĩa là không có giá trị mặc định. Khi enabled=true, value của nó được áp dụng. Nếu default cũng được cung cấp và hai giá trị khác nhau, thao tác ghi công khai trả về RPA_DEFAULT_CONFLICT thay vì âm thầm chọn một giá trị. Giá trị mặc định dạng mảng hoặc đối tượng là một giá trị JSON. Lượt chạy không thể bắt đầu khi thiếu một giá trị bắt buộc và không có giá trị mặc định. Bỏ qua một giá trị tùy chọn khác với việc truyền tường minh null hoặc mảng rỗng, và null phải vượt qua bước xác thực của trường đích.

```json
{
  "type": "object",
  "properties": {
    "targetUrl": {
      "type": "string",
      "description": "Target URL",
      "default": "https://example.com"
    },
    "count": {
      "type": "integer",
      "default": 2,
      "extra": {
        "decimalPlaces": 0,
        "numberRange": {
          "enabled": true,
          "min": 1,
          "max": 10
        }
      }
    },
    "enabled": {
      "type": "boolean",
      "default": true
    },
    "items": {
      "type": "array",
      "default": []
    },
    "settings": {
      "type": "object",
      "default": {}
    },
    "attachment": {
      "type": "object",
      "extra": {
        "type": "file",
        "multipleFiles": {
          "enabled": false
        },
        "formatType": [
          "txt"
        ],
        "sizeLimit": {
          "unit": "KB",
          "value": 100
        }
      }
    }
  },
  "required": [
    "targetUrl"
  ]
}
```

Quy trình có tham số tệp, hoặc có tham số chuỗi với localPath=true, có thể chạy từ bên ngoài, giống như khi chạy trong ứng dụng. Hãy truyền đường dẫn cục bộ khi chạy.

## 3. Giá trị mặc định riêng tư

Biến riêng tư phải có type=string và extra.private=true. Local API không che giá trị riêng tư. Bạn có thể gửi giá trị mặc định dạng văn bản thuần, GET trả về giá trị mặc định dạng văn bản thuần, và quy trình có tham số riêng tư có thể chạy từ bên ngoài (khi chạy, bạn có thể truyền trực tiếp văn bản thuần; xem [ParameterValues](/vi/browser-rpa/api/data-types#parametervalues)).

Ghi giá trị mặc định dạng văn bản thuần:

```json
{
  "type": "string",
  "default": "p@ssw0rd",
  "extra": {
    "private": true,
    "defaultValue": {
      "enabled": true,
      "value": "p@ssw0rd"
    }
  }
}
```

Cách này khớp với cách trình chỉnh sửa Mẫu tùy chỉnh của ứng dụng lưu dữ liệu: văn bản thuần được ghi nguyên trạng vào nội dung mẫu đám mây, và GET trả về giá trị đó ở dạng văn bản thuần như trên. Khi trình chỉnh sửa của ứng dụng lưu giá trị mặc định dưới dạng tham chiếu đến kho lưu trữ an toàn cục bộ, việc đọc giá trị đó trên máy này sẽ giải mã và trả về giá trị.

| Trường hợp ghi hoặc đọc | Quy tắc |
|  --- | --- |
| POST/PUT/node-edits gửi default hoặc defaultValue.value dạng văn bản thuần | Được ghi nguyên trạng vào mẫu đám mây; việc lưu thành công |
| GET chi tiết mẫu | Giá trị mặc định riêng tư được trả về dưới dạng văn bản thuần trong `default` và `defaultValue:{enabled:true,value}`; `redactedPaths` luôn là `[]` |
| Phản hồi của các endpoint ghi (tạo, cập nhật, sao chép, chỉnh sửa nút) | Giống GET; giá trị mặc định riêng tư được trả về dưới dạng văn bản thuần |
| Biên nhận idempotency (phát lại bằng cùng khóa, kết quả của `GET /requests/{key}`) | Biên nhận không lưu nội dung mẫu. Khi phát lại, máy chủ đọc lại mẫu đám mây và trả về nội dung hiện tại của mẫu, giống như GET |
| PUT/xác thực inline có base là mẫu ban đầu, cùng tên trường ban đầu, kiểu string và private=true, và gửi lại `publicState:"retained"` | Giữ giá trị mặc định hiện có của trường này trong mẫu này (để tương thích với các bên gọi cũ); nếu không có giá trị mặc định tương ứng, trả về 422 RPA_PRIVATE_DEFAULT_INVALID |
| Gửi retained cho một mẫu mới, hoặc cho một mẫu hay trường khác | 422 RPA_PRIVATE_DEFAULT_INVALID; giá trị không được lấy từ mẫu khác. Với mẫu mới, hãy gửi văn bản thuần |
| Bỏ qua defaultValue, hoặc enabled=false | Xóa giá trị mặc định hiện có; trường vẫn có thể là riêng tư; trả về cảnh báo RPA_PRIVATE_DEFAULT_CLEARED |
| node-edits không có variables | Giữ nguyên variables hiện có trên máy chủ và các giá trị mặc định riêng tư |
| node-edits có variables đầy đủ | Được xử lý giống như PUT |
| Sao chép | Bản sao giữ các giá trị mặc định riêng tư của mẫu nguồn, không có cảnh báo |
| Giá trị mặc định riêng tư là tham chiếu đến kho lưu trữ an toàn cục bộ không còn đọc được (ví dụ: giá trị được lưu trên thiết bị khác, hoặc kho lưu trữ an toàn cục bộ đã bị đặt lại) | GET trả về `{enabled:false}` kèm cảnh báo RPA_PRIVATE_DEFAULT_UNAVAILABLE; hãy gửi lại văn bản thuần để khôi phục |


Lệnh gọi chỉ để xác thực là thao tác chỉ đọc. Lệnh gọi này không ghi vào mẫu đám mây, và không tạo hay thay đổi giá trị trong kho lưu trữ an toàn. Tham số riêng tư phải là chuỗi, và chỉ có thể dùng `publicState` trên các trường chuỗi riêng tư.

NodeContract gán cho mỗi trường sensitivity=public|secret|credential|localPath|inlineFile|sourceCode, giá trị này chỉ mô tả bản chất của trường. `authoringPolicy` luôn là `allowed`. Các trường như mã nguồn script (javaScript/injectJavaScript.content), đường dẫn cục bộ (path của từng hành động tệp, thư mục ảnh chụp màn hình), tệp nội tuyến, Cookie/LocalStorage và khóa 2FA đều có thể nhận trực tiếp giá trị literal hoặc tham chiếu. GET trả về nguyên trạng các trường này, và lượt chạy không bị hạn chế. Bên gọi phải tự lưu trữ và che nội dung này; xem [Ranh giới dữ liệu và thực thi](/vi/browser-rpa/api/common#ranh-gi%E1%BB%9Bi-d%E1%BB%AF-li%E1%BB%87u-v%C3%A0-th%E1%BB%B1c-thi).

## 4. Sáu nút cấu trúc

| type | data | blocks | Ngữ nghĩa thực thi |
|  --- | --- | --- | --- |
| start | title/description; customVariables; taskSettings (cài đặt tác vụ của mẫu, xem bên dưới); có thể giữ inputsValues mô tả dùng cho bước khởi tạo, nhưng chúng không cung cấp tham số chạy thực tế | Bỏ qua hoặc [] | Đứng đầu ở cấp gốc; khai báo các biến tùy chỉnh của quy trình này |
| end | inputsValues.status/message; khuyến nghị dùng giá trị cố định success hoặc failed cho status; message có thể là một WorkflowValue; null trở thành chuỗi rỗng, đối tượng được xử lý qua JSON.stringify, còn các giá trị khác được xử lý qua String, nên giá trị cuối cùng là một chuỗi | Bỏ qua hoặc [] | Kết thúc quy trình hiện tại; status=failed làm quy trình thất bại, nếu không thì quy trình thành công; thao tác ghi công khai từ chối các giá trị literal xác định khác; kết quả thô công khai là chuỗi message |
| group | title/name/description/collapsed | Mảng nút bắt buộc, có thể rỗng; **không được chứa group khác** (không thể lồng nhóm, giống trình chỉnh sửa; nếu không sẽ trả về RPA_INVALID_NODE) | Tổ chức thứ tự và không tự tạo ra kết quả thực thi có thể tham chiếu; nhóm được làm phẳng khi chạy, nhưng quy trình đã lưu vẫn giữ nhóm |
| case | title/description tùy chọn (khuyến nghị mô tả ý nghĩa của nhánh; nếu bỏ qua, tiêu đề mặc định `分支` sẽ được điền vào); conditionGroups:[{content:Condition[]}], **chỉ cho phép một nhóm** | Mảng nút bắt buộc | Chỉ nằm trực tiếp dưới ifElse; các điều kiện trong nhóm được kết hợp bằng AND; để biểu diễn "hoặc", hãy thêm nhánh; case đầu tiên khớp, theo thứ tự các case, sẽ được chọn |
| caseDefault | title/description tùy chọn (khuyến nghị mô tả ý nghĩa của nhánh; nếu bỏ qua, tiêu đề mặc định `默认分支` sẽ được điền vào) | Mảng nút bắt buộc | Chỉ chạy khi ifElse không khớp case nào; tối đa một nút, và phải đứng cuối |
| exceptionBlock | title/description tùy chọn | Mảng nút bắt buộc, có thể rỗng | Chỉ dùng làm blocks trực tiếp của một nút được đặt thành "Chạy nhánh xử lý ngoại lệ"; đúng hai khối, nhánh thành công trước và nhánh thất bại sau; xem [Nhánh xử lý ngoại lệ](#nh%C3%A1nh-x%E1%BB%AD-l%C3%BD-ngo%E1%BA%A1i-l%E1%BB%87) |


Đối tượng start.data.taskSettings chứa các cài đặt cấp mẫu mà trình chỉnh sửa lưu từ "Cài đặt tác vụ". GET trả về nguyên trạng các cài đặt này, và bạn có thể ghi lại nguyên vẹn hoặc sửa đổi chúng. Về các trường và giá trị, xem `$defs.start` trong workflow.schema.json. Các cài đặt này chỉ có hiệu lực trong lượt chạy thực tế (chạy toàn bộ quy trình trong trình chỉnh sửa, lượt chạy bắt đầu qua Local API hoặc tác vụ theo lịch). Các cài đặt này không có hiệu lực khi gỡ lỗi từng bước hoặc gỡ lỗi nhóm, và taskSettings trong mẫu con được gọi cũng không có hiệu lực. Các điểm chính:

- delayMinutes: Trước tiên, lượt chạy ở trạng thái xếp hàng mà không chiếm dụng môi trường, và chỉ khởi động trình duyệt tại `startAfter` (một trường của bản tóm tắt lượt chạy; với tác vụ theo lịch, thời điểm đã lên lịch là mốc tính). Có thể hủy lượt chạy khi lượt chạy đang xếp hàng.
- timeoutSeconds: Việc tính giờ bắt đầu khi thời gian trì hoãn kết thúc và trình duyệt khởi động. Khi hết thời gian chờ, trình duyệt của môi trường chính bị đóng và lượt chạy thất bại với mã lỗi RPA_TASK_TIMEOUT. Các nút đang chạy tại thời điểm hết thời gian chờ (bao gồm cả các nút vòng lặp, điều kiện và quy trình con bao quanh) cũng được ghi nhận là failed với RPA_TASK_TIMEOUT. Các nút này không được thử lại và không đi qua xử lý ngoại lệ. Thời gian chờ của tác vụ và thời gian chờ của nút được áp dụng độc lập.
- completionTabs / completionBrowser: Sau khi thành công hoặc thất bại, các cài đặt này tác động lên môi trường chính (môi trường được dùng khi lượt chạy bắt đầu). Không có thao tác nào được thực hiện khi người dùng dừng lượt chạy. Các môi trường được mở bởi nút "Khởi động trình duyệt" không bị ảnh hưởng.
- headless, launchArguments, disableAutofill, allowSavePasswords và clearCacheOnClose chỉ áp dụng cho các trình duyệt do lượt chạy này khởi động (bao gồm cả các trình duyệt do nút "Khởi động trình duyệt" khởi động). Các cài đặt này không có tác dụng với các môi trường đã mở trước lượt chạy. Trình duyệt headless yêu cầu nhân trình duyệt phiên bản 130 trở lên (nếu không sẽ trả về RPA_HEADLESS_CORE_UNSUPPORTED), và luôn bị đóng khi tác vụ kết thúc, kể cả khi người dùng dừng tác vụ.


Thao tác ghi công khai cho case chỉ chấp nhận conditionGroups, với đúng một nhóm điều kiện (giống trình chỉnh sửa; nhiều hơn một nhóm sẽ trả về RPA_WORKFLOW_SCHEMA_INVALID với reason=limit). Khi đọc trường cũ inputsValues.condition, ranh giới API chuyển trường này thành conditionGroups gồm một phần tử. Nếu có cả hai, đó là lỗi cấu trúc bên trong quy trình: thao tác lưu hoặc cập nhật trả về 422, còn lệnh gọi chỉ để xác thực trả về 200 kèm valid=false và một vấn đề. Không dạng nào có thể bị âm thầm bỏ qua. Mỗi nhóm phải không rỗng, và mỗi điều kiện đều cần toán hạng trái. Các toán tử là eq/ne/gt/lt/gte/lte/contains/notContains/exists/notExists, và chỉ exists/notExists mới có thể bỏ qua right. Các toán tử gt/gte/lt/lte so sánh số hoặc chuỗi số. Khi một trong hai vế là null (ví dụ, tham chiếu đến một nút đã bị bỏ qua sau khi thất bại), điều kiện không được thỏa mãn. Các giá trị khác không thể chuyển đổi thành số sẽ trả về VALUE_CONVERSION_FAILED. Viết toán hạng dưới dạng hằng `{"type":"constant","content":…}` hoặc dưới dạng tham chiếu `{"type":"ref","content":["nodeId","data","field"]}`. content của một tham chiếu **phải là một mảng các đoạn đường dẫn** (giống trình chỉnh sửa). Nếu bạn viết nó dưới dạng chuỗi `"nodeId.data.field"`, trình chỉnh sửa coi như trường chưa được điền, và thao tác ghi trả về RPA_NODE_INPUT_INVALID (reason=required). Bạn không thể biến toàn bộ một nhóm điều kiện thành một ref.

workflow.outputs ở cấp gốc là ánh xạ đầu ra thực tế của quy trình, khác với các mô tả dành cho trình chỉnh sửa trong data.outputs của nút. Khi không được khai báo tường minh, môi trường thực thi suy ra `{result:"${<endId>.data.result}"}` từ nút end ở cuối cấp gốc. workflow.outputs tường minh sẽ ghi đè giá trị mặc định này, đó là lý do call_child.data.outputs.result trong ví dụ quy trình con lấy từ ánh xạ này. Mọi tham chiếu trong khai báo cũng phải qua các bước kiểm tra phạm vi, kiểu và chính sách chạy.

Nút cấu trúc không được tính là hành động có thể thực thi, vì vậy khi đọc capabilities, đừng coi start hay group là bị thiếu khi chạy. Nút breakLoop là một hành động điều khiển. Nút này chỉ có thể được đặt trong thân vòng lặp của quy trình hiện tại, và blocks của nút phải được bỏ qua hoặc để rỗng. Lệnh break trong quy trình con không thể thoát khỏi vòng lặp của bên gọi.

Khi tạo vòng lặp, hãy luôn ghi `"accumulatorMode": "none"` (ghi giá trị khác khi bạn cần tích lũy kết quả), khớp với các vòng lặp được tạo trong trình chỉnh sửa của ứng dụng. Khi bỏ qua, giá trị được coi là `none`, khớp với những gì trình chỉnh sửa hiển thị. Đầu ra `index` của vòng lặp là lần lặp hiện tại và **bắt đầu từ 1** (lần lặp đầu tiên là 1). Ở chế độ times, `item` giống với `index`. Ở chế độ list/elements, `item` là phần tử hoặc giá trị hiện tại, và với danh sách đối tượng, `item` là `{key,value}`. Với các trường chọn phần tử thứ N theo vị trí (chẳng hạn serial của getElement, cũng bắt đầu từ 1), hãy tham chiếu trực tiếp `${loopId.data.index}` và không cộng thêm 1. Sau khi vòng lặp kết thúc, `index` là số thứ tự của lần lặp cuối cùng, hoặc 0 nếu vòng lặp không chạy lần nào. Ở chế độ while, chỉ ghi loopConditions dưới dạng mảng quy tắc, `[{"field":"index","operator":"lt","value":3}]` (giống trình chỉnh sửa; không chấp nhận nhóm điều kiện `{content:[…]}`). Khi đạt maxIterations, vòng lặp kết thúc bình thường và exitReason là max_iterations.

## 5. Biến tùy chỉnh và tham chiếu

Mỗi mục trong start.data.customVariables là `{id,name,type,initialValue}`. type của mục là string/number/boolean/array/object, và initialValue phải khớp với type. id phải là duy nhất và biểu diễn được bằng cú pháp đường dẫn. Tham chiếu biến bằng `${custom.<id>}`, không phải bằng tên. Biến tùy chỉnh được khởi tạo độc lập cho mỗi lượt chạy đầy đủ và cho mỗi lần gọi quy trình con. API công khai không cung cấp chức năng gỡ lỗi, nên giá trị không được kế thừa giữa các lượt chạy.

Chỉ có một cách để ghi biến tùy chỉnh (giống trình chỉnh sửa): khai báo biến trong start.data.customVariables và thay đổi biến bằng `browser_updateCustomVariable`. variableId phải là giá trị tĩnh và đã được khai báo, và operation phải phù hợp với kiểu của biến. Bạn không thể ghi động các tham số tùy ý hoặc biến hệ thống. Trình chỉnh sửa không có nút setCustomVariable, nên việc ghi nút này trả về RPA_WORKFLOW_SCHEMA_INVALID. Một nút setCustomVariable còn sót lại trong mẫu hiện có sẽ thất bại trước khi chạy (RPA_ACTION_UNSUPPORTED, kèm ID nút và đường dẫn).

```json
[
  {"id": "start", "type": "start", "data": {"customVariables": [{"id": "demoCounter", "name": "Counter", "type": "number", "initialValue": 0}]}},
  {"id": "set_counter", "type": "browser_updateCustomVariable", "data": {"browserAction": "updateCustomVariable",
    "browserUi": {"inputs": {"variableId": "demoCounter", "operation": "assign", "value": "2"}}}},
  {"id": "end", "type": "end", "data": {"inputsValues": {"status": {"type": "constant", "content": "success"},
    "message": {"type": "ref", "content": ["custom", "demoCounter"]}}}}
]
```

`${parameterName}` đọc một tham số ban đầu, `${nodeId.data.field}` đọc dữ liệu thực thi của một nút, `${custom.id}` đọc một biến tùy chỉnh, còn `${system.browser.id}` và các đường dẫn tương tự đọc ngữ cảnh hệ thống. Tham chiếu toàn bộ giá trị giữ nguyên kiểu ban đầu, còn tham chiếu nằm trong một chuỗi ghép được chuyển thành văn bản. WorkflowNumber nhận một số hoặc một biểu thức số học bị giới hạn, không nhận đối tượng ref. `${…}` chỉ có thể chứa đường dẫn tham chiếu, không chứa phép tính số học: `${loop.data.index + 1}` trả về RPA_REFERENCE_EXPRESSION_UNSUPPORTED. Trong trường số, hãy viết `"${loop.data.index}+1"` (tham chiếu được viết riêng, còn phép tính số học nằm ngoài `${}`). Các trường văn bản thông thường không tính toán biểu thức số học. Tham chiếu trong browserUi.inputs/bindings của nút hành động **chỉ được viết dưới dạng văn bản `${path}`** (giống trình chỉnh sửa), không viết dưới dạng đối tượng bao như `{type:'ref'}`. Trường phần tử và trường frame cũng chỉ nhận văn bản tham chiếu như `${previousNode.data.element}`; không tự viết đối tượng ElementRef/FrameRef. Viết đối tượng bao sẽ trả về RPA_WORKFLOW_SCHEMA_INVALID hoặc RPA_NODE_INPUT_INVALID (reason=format). Đối tượng ref `{type:'ref',content:[pathSegments]}` chỉ được dùng trong inputsValues của nút end và trong toán hạng của nhánh điều kiện.

WorkflowValue (inputsValues của nút end, toán hạng điều kiện, và key/value của tham số script) là một giá trị JSON thuần hoặc một đối tượng bao constant/ref/expression. Khi bước xác thực ngữ nghĩa công khai gặp khóa dành riêng type=ref/constant/expression, bước này phải xác thực giá trị như một đối tượng bao. Bước này không được để kiểu hợp JsonValue rộng hấp thụ một đối tượng bao sai định dạng. Nếu một đối tượng có các khóa dành riêng này thực sự cần là dữ liệu nghiệp vụ thuần, hãy bao nó trong constant và xử lý theo quy tắc của trường đích.

**Không đảm bảo có quy tắc escape chung nào cho `${…}` trong chuỗi literal.** Để xuất văn bản như vậy, hãy dùng đối tượng bao constant mà hợp đồng của trường cho phép, và kiểm tra bằng validate. Nếu trình phân tích hiện tại vẫn nội suy văn bản đó, kết quả sẽ được báo là không được hỗ trợ. Đừng cố lách bằng cách đoán cách escape bằng dấu gạch chéo ngược.

Việc một trường chế độ (chẳng hạn selectorType/loopMode/outputRange) có cho phép tham chiếu động hay không do NodeContract quy định. Nếu có, bước xác thực trả về runtimeChecks, và giá trị thực tế được kiểm tra lại khi chạy. Hãy chọn kiểu đầu ra theo chế độ, và đừng giả định rằng nút nào cũng có kết quả.

## 6. Dữ liệu hiển thị và chuẩn hóa

`node.meta` là một đối tượng JSON tùy chọn, không trong suốt (opaque), chỉ chứa thông tin hiển thị. Đối tượng này cho phép mọi trường con JSON (ví dụ position, collapsed hoặc bố cục do bên gọi tự định nghĩa), và toàn bộ đối tượng phải tuân theo giới hạn kích thước byte và độ sâu lồng nhau của quy trình. Không đặt token, bí mật hoặc thông tin kết nối cục bộ vào đối tượng này. Cả meta lẫn node.data.title/description/inputs/outputs đều không thay đổi ngữ nghĩa của lượt chạy, và chúng không phải là tham số hay đầu ra thực tế. Máy chủ không được thực thi nội dung meta, và bên gọi không được coi văn bản trong đó là chỉ dẫn.

Nút mới không cần tạo tọa độ hay meta. Cả replace lẫn PUT đều giữ nguyên chính xác mọi meta hợp lệ được cung cấp, bao gồm các khóa hiển thị không xác định, null và mảng. Bỏ qua meta của một nút sẽ xóa dữ liệu hiển thị của nút đó. Trong node-edits, các nút không bị động đến vẫn giữ meta của chúng, còn với replace, bên gọi chịu trách nhiệm gửi lại toàn bộ nút. Để chỉ thay đổi một trường hiển thị, hãy hợp nhất sâu (deep-merge) thay đổi vào kết quả GET; không ghi đè các khóa khác. Không đảm bảo thứ tự khóa bên trong meta, và giá trị không được bị âm thầm cắt bớt.

Các phép chuẩn hóa mẫu duy nhất được phép là: loại bỏ khoảng trắng ở hai đầu title, phép chuyển đổi đã được khai báo khi đọc dạng case cũ, dạng lưu trữ và dạng trả về của giá trị mặc định riêng tư (xem mục 3) kèm cảnh báo tường minh, và "Các trường do máy chủ bổ sung" được mô tả bên dưới. Máy chủ không đổi tên ID nút, không thay đổi description hay meta, không loại bỏ các trường meta không xác định, và không thay đổi thứ tự nút hay tham chiếu. Nguồn đã lưu được giữ tách biệt với kế hoạch thực thi. NodeContract.defaults chỉ bổ sung các đầu vào bị bỏ qua cho kế hoạch đã biên dịch hoặc đã xác thực và không được ghi vào browserUi.inputs, và phản hồi của thao tác lưu vẫn giữ nguyên các đầu vào vốn bị bỏ qua. Giá trị 0, false, chuỗi rỗng hoặc null được đặt tường minh không kích hoạt giá trị mặc định. Bên gọi vẫn nên dựa vào toàn bộ kết quả được trả về để thực hiện các chỉnh sửa tiếp theo.

### Các trường do máy chủ bổ sung

Quy trình đã lưu phải mở được trong trình chỉnh sửa RPA trình duyệt của ứng dụng máy tính (trên trang chỉnh sửa mẫu, và dưới dạng bản chụp nhanh quy trình trong bản ghi thực thi và lịch chạy). Vì vậy, mọi thao tác ghi (tạo, thay thế, sao chép, chỉnh sửa nút, xác thực với purpose=save/run, cũng như thao tác lưu và chạy bản nháp trong ứng dụng) đều bổ sung các trường còn thiếu của từng nút hành động (`browser_<action>`) bằng những gì trình chỉnh sửa ghi khi tạo cùng loại nút đó. Sau đó, kết quả được kiểm tra bằng các quy tắc tải của trình chỉnh sửa:

| Trường | Quy tắc bổ sung |
|  --- | --- |
| `data.browserUi.inputs` / `bindings` | `{}` khi bị bỏ qua; giá trị mặc định của đầu vào nút không được ghi vào inputs |
| `data.browserUi.exception` | Khi bị bỏ qua, hoặc khi thiếu một số trường, mỗi trường còn thiếu nhận giá trị mặc định của trình chỉnh sửa (xem [Chính sách ngoại lệ của nút](#ch%C3%ADnh-s%C3%A1ch-ngo%E1%BA%A1i-l%E1%BB%87-c%E1%BB%A7a-n%C3%BAt-workflowexception)); các trường được ghi tường minh được giữ nguyên |
| `data.title` | Khi bị bỏ qua, tên của nút trong trình chỉnh sửa sẽ được điền vào, giữ nguyên cách diễn đạt gốc bằng tiếng Trung. Đây chỉ là giá trị dự phòng. Hãy viết tên mô tả mục đích của nút. Khi tên bị bỏ qua, để trống hoặc trùng với tên mặc định, máy chủ trả về cảnh báo `RPA_NODE_TITLE_GENERIC` (xem bên dưới) |
| `data.inputs` / `data.inputsValues` | Khi bị bỏ qua, lần lượt là `{"type":"object","properties":{}}` và `{}`; inputsValues của nút hành động phải là đối tượng rỗng |
| `data.outputs` | Luôn do máy chủ tạo từ loại nút và browserUi.inputs. Trường này mô tả các biến mà các nút phía sau có thể tham chiếu. Bên gọi không cần điền trường này; nếu có điền, kết quả do máy chủ tạo sẽ được ưu tiên |
| `data` của nút start / end | Các khóa còn thiếu được bổ sung theo các nút start và end mà trình chỉnh sửa tạo cho một mẫu mới: start nhận `title` `初始化`; end nhận `title` `结束`, `inputs`/`inputsValues` (status=success và message rỗng, cho cùng kết quả thực thi như khi bỏ qua chúng) và `outputs`. Các khóa được ghi tường minh (bao gồm title tùy chỉnh và status=failed) được giữ nguyên |
| `data.title` của case / caseDefault | Khi bị bỏ qua, tên nhánh mặc định của trình chỉnh sửa sẽ được điền vào: `分支` cho case và `默认分支` cho caseDefault. Tên được ghi tường minh (kể cả chuỗi rỗng) được giữ nguyên |


Do đó, nút hành động và nút start/end khi đọc lại bằng GET luôn có đầy đủ cấu trúc ở trên, và dạng rút gọn khi gửi (chỉ có browserAction và browserUi.inputs) vẫn hợp lệ. Quy trình mà trình chỉnh sửa vẫn không mở được sau khi đã bổ sung các trường (ví dụ, loại nút không khớp với browserAction, hoặc một nhánh điều kiện không nằm dưới nút điều kiện) sẽ trả về 422, và issues.path trỏ đến nút bị ảnh hưởng. Nội dung đầy đủ do chính trình chỉnh sửa của ứng dụng lưu không bao giờ bị viết lại.

**Lưu ý về tên**: Trình chỉnh sửa của ứng dụng chỉ hiển thị tên của các nút và nhánh trong mẫu. Vì vậy, thao tác tạo, thay thế, chỉnh sửa nút và `POST /validations` trả về một cảnh báo `RPA_NODE_TITLE_GENERIC` cho mỗi nút hành động và mỗi case/caseDefault có tên bị bỏ qua, để trống hoặc trùng với tên mặc định trong trình chỉnh sửa. Mỗi cảnh báo có một path trỏ đến `data/title` của nút, và có kèm `nodeId`. Cảnh báo không chặn việc lưu hay chạy. Các nút start/end, group và exceptionBlock không được kiểm tra, và thao tác sao chép mẫu không trả về cảnh báo này. Hãy đổi tên các nút như vậy để mô tả mục đích của chúng (ví dụ, "Chờ kết quả tìm kiếm xuất hiện" hoặc "Tìm video mục tiêu").

## 7. Ánh xạ chính xác của kết quả cuối cùng

Trên luồng thành công, `end.data.inputsValues.message` được đánh giá → null trở thành `""`, đối tượng và mảng được xử lý qua JSON.stringify, còn các giá trị khác được xử lý qua String → dữ liệu thực thi của nút end, `end.data.result` (chuỗi). Khi workflow.outputs không được cung cấp tường minh, trình biên dịch suy ra `{ "result": "${<endId>.data.result}" }`, nên `data.result.outputs.result` trong phản hồi GET lượt chạy chính là chuỗi này. Nếu workflow.outputs được đặt tường minh, kết quả tuân theo ánh xạ đó, và không có trường result ngầm định. Với status=failed, quy trình kết thúc là thất bại và không được xem là tạo ra kết quả thành công.

Ví dụ, nếu giá trị của getUrl(type=search,key=item) là `"42"` và end.message tham chiếu đến giá trị đó, outputs.result cuối cùng là `"42"`. Khi key không tồn tại, getUrl.value="" và outputs.result cuối cùng là `""`. Điều này không có nghĩa là nút đã thất bại. Nếu end.message tham chiếu đến toàn bộ đối tượng data của getUrl, kết quả là chuỗi JSON của đối tượng đó. Không nhầm lẫn kết quả ở cấp nút với kết quả ở cấp lượt chạy.

## 8. URL và giới hạn của bằng chứng xác thực

Tham số ban đầu dạng URL chỉ cần được khai báo là string; URL không phải là một kiểu biến riêng. Trong bước xác thực để lưu, giá trị literal cố định trong gotoUrl.url phải là URL HTTP(S) tuyệt đối. Với tham chiếu chưa có giá trị khi chạy, bước xác thực kiểm tra khai báo và phạm vi của tham chiếu đó và liệt kê nó trong runtimeChecks. Bước xác thực không thể khẳng định rằng URL hợp lệ hoặc truy cập được. Bước kiểm tra trước khi chạy sẽ kiểm tra lại định dạng URL với các tham số thực tế. Khả năng kết nối đến trang web, chuyển hướng và thay đổi của trang vẫn chỉ có thể được xác nhận trong khi thực thi. Mảng runtimeChecks rỗng không phải là bằng chứng rằng lượt chạy sẽ thành công. Khi valid=false, hãy sửa các vấn đề rồi xác thực lại.

## 9. Các dạng tham chiếu, base và thay đổi hiển thị

Dạng literal là một giá trị JSON thuần cho trường đích. Dạng template là một chuỗi chứa `${…}` (tham chiếu toàn bộ giá trị giữ nguyên kiểu, còn phép ghép chuỗi chuyển kết quả thành văn bản). Dạng numericExpression là một biểu thức số học có giới hạn, gồm bốn phép tính cơ bản và các tham chiếu số, theo khả năng hỗ trợ của WorkflowNumber; đây không phải là JavaScript. Dạng reference là `{type:"ref",content:[pathSegments]}` và chỉ xuất hiện trong inputsValues của nút end và trong toán hạng điều kiện (không dùng trong browserUi của nút hành động). Schema mô tả những gì có thể có về mặt cấu trúc, còn referenceRules giới hạn các dạng mà trường cho phép công khai. Phải thỏa mãn cả hai. Trường gotoUrl.url hỗ trợ literal/template.

Với getUrl.type=href, value và url đều là địa chỉ hiện tại đầy đủ tại thời điểm đọc, bao gồm cả query/hash. Nếu lần điều hướng trước đó bị chuyển hướng, đây là địa chỉ của trang hiện tại sau khi chuyển hướng. Với origin, value gồm scheme, host và cổng. Với search, value là giá trị đầu tiên của khóa truy vấn đã cho, hoặc chuỗi rỗng nếu khóa không tồn tại, và url vẫn là địa chỉ đầy đủ.

Nguồn inline không có base là một bản đề xuất độc lập cho mẫu mới. Máy chủ không thể suy ra nguồn đó đến từ mẫu hiện có nào, nên máy chủ không kiểm tra bất kỳ phiên bản đã lưu nào và không cho phép retained. Khi sửa đổi một mẫu, bạn phải gửi base để bước kiểm tra phiên bản có thể bảo vệ lần kiểm tra trước này. Việc lưu vẫn yêu cầu If-Match. Nếu bên gọi không có quyền truy cập base hoặc mẫu, máy chủ trả về 403/404 trước, không phải RPA_TEMPLATE_VERSION_CONFLICT, và không tiết lộ phiên bản.

Khi người dùng ứng dụng lưu bố cục hiển thị hoặc chỉnh sửa biểu mẫu, người dùng đó cũng được tính là một bên ghi khác. Thao tác này sẽ làm tăng phiên bản mẫu và làm mất hiệu lực các ETag cũ. Việc chỉ mở một mẫu không phải là thao tác ghi mà API đảm bảo, vì vậy đừng dựa vào đó để kết luận rằng phiên bản chưa thay đổi. Hãy luôn đọc lại mẫu hiện tại trước khi tiếp tục chỉnh sửa.

## 10. Chọn nút chờ

"Chờ sau khi truy cập" có thể dùng gotoUrl.postWaitMs hoặc một waitTime riêng, và hai khoảng chờ này được cộng dồn. Nếu người dùng cũng muốn chỉnh sửa riêng nút chờ, chúng tôi khuyến nghị đặt tường minh postWaitMs=0 cùng với một waitTime riêng để tránh tính thời gian chờ hai lần. Đây là lựa chọn kết hợp mặc định, không phải là hạn chế của giao thức. Với waitTime, fixed.timeout cho phép số mili giây hữu hạn có phần thập phân, nhưng không đảm bảo độ chính xác lập lịch của lượt chạy. Cả hai đầu của randomInterval cũng cho phép số thập phân (về quy tắc giá trị, xem hợp đồng browser_waitTime). meta trong phản hồi (Metadata) là thông tin truy vết HTTP, còn node.meta là thông tin hiển thị trên khung vẽ. Không thể dùng giá trị này để điền thay cho giá trị kia.

Khi đổi ID của một nút, bạn phải sửa đồng thời mọi tham chiếu. Hãy thay thế toàn bộ mẫu bằng PUT, hoặc trong một lô node-edits, xóa nút cũ, chèn nút mới và thay thế mọi nút tham chiếu đến nút đó. Bản thân thao tác replace không thể thay đổi node.id. Với cách nào cũng vậy, hãy xác thực toàn bộ bản đề xuất trước, giữ nguyên dữ liệu của người dùng, và dùng If-Match hiện tại cùng một khóa mới cho ý định ghi.

## Chính sách ngoại lệ của nút (WorkflowException)

Cấu hình này được đặt trong `node.data.browserUi.exception`, cùng cấp với inputs và bindings, và không được ghi bên trong inputs. Về cấu trúc trường, phạm vi giá trị và giá trị mặc định, xem [schema WorkflowException](/vi/browser-rpa/local-api#h%E1%BB%A3p-%C4%91%E1%BB%93ng-c%E1%BB%A5c-b%E1%BB%99-d%E1%BA%A1ng-m%C3%A1y-%C4%91%E1%BB%8Dc-%C4%91%C6%B0%E1%BB%A3c).

Khi bỏ qua toàn bộ đối tượng exception hoặc bất kỳ trường nào của nó, máy chủ bổ sung từng trường còn thiếu trước khi lưu, bằng giá trị mặc định mà trình chỉnh sửa của ứng dụng đặt cho nút mới (xem [Các trường do máy chủ bổ sung](#c%C3%A1c-tr%C6%B0%E1%BB%9Dng-do-m%C3%A1y-ch%E1%BB%A7-b%E1%BB%95-sung)). Bạn có thể thấy các giá trị đầy đủ khi đọc lại mẫu. Các trường được ghi tường minh được giữ nguyên. Các giá trị được bổ sung giống với giá trị của cùng loại nút được tạo trong trình chỉnh sửa và giá trị hiển thị trong bảng cài đặt ngoại lệ của trình chỉnh sửa. Khi thực thi, các giá trị đã bổ sung sẽ được dùng.

| Trường | Giá trị bổ sung khi bị bỏ qua | Giá trị và ngữ nghĩa |
|  --- | --- | --- |
| policy | `"interrupt"` | interrupt: lượt chạy dừng sau khi nút thất bại. skip: giữ bản ghi của nút thất bại và tiếp tục. handle: xử lý lỗi bằng handler, rồi tiếp tục hoặc dừng. Việc nút hết thời gian chờ được xử lý theo policy như mọi lỗi khác. Nếu sau khi hết thời gian chờ, thao tác ban đầu vẫn chưa kết thúc trong thêm một khoảng thời gian chờ nữa, trước tiên trình thực thi sẽ ngắt kết nối và tiếp quản lại cùng môi trường đó (giữ nguyên tab hiện tại ban đầu), rồi mới áp dụng policy. Nếu việc tiếp quản thất bại (ngữ cảnh thực thi đã bị cách ly) hoặc lượt chạy bị hủy, skip/handle không thể buộc lượt chạy tiếp tục. |
| handler | Không được bổ sung; trình thực thi coi giá trị là `"screenshot"` | Chỉ có hiệu lực khi policy=handle và không dùng [nhánh xử lý ngoại lệ](#nh%C3%A1nh-x%E1%BB%AD-l%C3%BD-ngo%E1%BA%A1i-l%E1%BB%87). screenshot: tiếp tục sau khi chụp ảnh màn hình thành công, hoặc dừng nếu chụp ảnh màn hình thất bại. stop: dừng phần còn lại của quy trình. remark: thêm một ghi chú môi trường. |
| screenshot | `true` | Thử chụp ảnh màn hình khi nút cuối cùng vẫn thất bại. Đặt false sẽ tắt ảnh chụp màn hình khi thất bại thông thường, nhưng policy=handle với handler=screenshot vẫn yêu cầu chụp ảnh màn hình. Có thể không chụp được ảnh màn hình khi trang đã đóng, lượt chạy bị hủy hoặc ngữ cảnh thực thi đã bị cách ly. Việc chụp ảnh màn hình thất bại không thay thế lỗi ban đầu của nút. Các nút tệp cục bộ useExcel (Đọc Excel), exportExcel (Ghi Excel), importText (Đọc văn bản từ tệp) và saveData (Lưu văn bản) không bao giờ chụp ảnh màn hình, vì lỗi của chúng không liên quan đến trang trình duyệt. Với các nút này, handler=screenshot chỉ ghi nhận lỗi rồi tiếp tục. |
| timeout | `30000` với nút hành động; `0` (không giới hạn) với nút điều khiển | Mili giây, một **số nguyên** trong phạm vi 0–2147483647 (giống trình chỉnh sửa; giá trị có phần thập phân trả về RPA_WORKFLOW_SCHEMA_INVALID). `0` nghĩa là không giới hạn thời gian. Đây là thời gian chờ của một lần thực thi, và cũng bị giới hạn bởi thời gian còn lại của toàn bộ lượt chạy. Đây không phải là thời gian chờ HTTP của Local API. Nút injectJavaScript còn bị giới hạn bởi đầu vào executionTimeoutMs của nút đó. |
| retry | `false` | Bật thử lại khi một hành động nguyên tử thất bại. |
| retryTimes | `1` | Có hiệu lực khi retry=true. Số nguyên trong phạm vi 1–10, đặt số lần thử thêm; hành động chạy tối đa 1+retryTimes lần. |
| retryInterval | `2` | Khoảng cách giữa các lần thử lại, tính bằng giây, trong phạm vi 0–2147483. Đơn vị này khác với timeout, vốn dùng mili giây. |


**Khi bỏ qua timeout, nút hành động (bao gồm cả các nút điều hướng như gotoUrl) nhận 30 giây, còn nút điều khiển (loop, ifElse, breakLoop, applySubProcess, updateCustomVariable) nhận `0`, nghĩa là không giới hạn thời gian.** Nút điều khiển không giới hạn thời gian chỉ bị giới hạn bởi thời gian còn lại của toàn bộ lượt chạy, maxIterations của vòng lặp và việc hủy. Mỗi hành động con bên trong nút vẫn chạy với thời gian chờ riêng (mặc định 30 giây), vì vậy một hành động đơn lẻ trên trang chậm cần được đặt tường minh thời gian chờ lớn hơn. Thời gian chờ được đặt tường minh trên nút điều khiển áp dụng cho toàn bộ lần gọi và mọi nút con của nó, và nút thất bại với TIMEOUT khi hết thời gian đó.

Trình chỉnh sửa của ứng dụng cũng ghi 0 (không giới hạn) cho nút điều khiển mới và 30000 cho nút hành động mới. Bất kỳ nút nào không cần giới hạn thời gian đều có thể đặt tường minh 0. Giá trị 2147483647 do các phiên bản trước lưu vẫn hợp lệ và cũng có nghĩa là không giới hạn thời gian; giá trị này không bị viết lại khi đọc. Khi tác nhân AI soạn quy trình, tác nhân nên đặt exception tường minh theo nhu cầu nghiệp vụ thay vì dựa vào giá trị mặc định.

Việc thử lại áp dụng cho hành động nguyên tử. Nút điều khiển không dùng các thiết lập này để thử lại toàn bộ đồ thị con. Khi nút hết thời gian chờ, nút cũng được thử lại theo cấu hình (việc này có thể lặp lại một hành động đã có hiệu lực). Nếu sau khi hết thời gian chờ, thao tác ban đầu vẫn chưa kết thúc trong thêm một khoảng thời gian chờ nữa, việc thử lại chỉ diễn ra sau khi đã tiếp quản lại môi trường. Không có thử lại tự động sau khi hủy hoặc sau khi tiếp quản thất bại. Cả skip lẫn handle thành công đều không đổi nút thất bại thành thành công, vì vậy bạn vẫn cần kiểm tra hasNodeErrors.

Ví dụ sau đây minh họa một vòng lặp chạy tối đa 10 phút, bỏ qua phần tử bị lỗi rồi tiếp tục, và một nút trên trang chậm đọc một giá trị và thử lại hai lần khi thất bại:

```json
[
  {
    "id": "each_item",
    "type": "browser_loop",
    "data": {
      "browserAction": "loop",
      "browserUi": {
        "inputs": {
          "loopMode": "times",
          "times": 20,
          "accumulatorMode": "none"
        },
        "exception": {
          "policy": "interrupt",
          "timeout": 600000,
          "screenshot": true
        }
      }
    },
    "blocks": [
      {
        "id": "read_title",
        "type": "browser_getElement",
        "data": {
          "browserAction": "getElement",
          "browserUi": {
            "inputs": {
              "selectorType": "selector",
              "selectorRadio": "CSS",
              "selector": "h1",
              "type": "innerText"
            },
            "exception": {
              "policy": "skip",
              "timeout": 15000,
              "retry": true,
              "retryTimes": 2,
              "retryInterval": 1,
              "screenshot": true
            }
          }
        }
      }
    ]
  }
]
```

Sau khi ảnh chụp màn hình được công bố thành công, `data.items` của `GET /runs/{id}/artifacts` chứa siêu dữ liệu của tạo phẩm đó, và `artifacts` của bản ghi thực thi nút đã tạo ảnh chụp màn hình tham chiếu đến cùng id. API không cung cấp URL tải xuống hay nội dung tệp. `path` là đường dẫn của ảnh chụp màn hình trên máy cục bộ.

### Nhánh xử lý ngoại lệ

Một nút hành động (bao gồm cả các hành động điều khiển như applySubProcess, updateCustomVariable và breakLoop, nhưng không gồm ifElse hay loop, vốn có blocks riêng) có thể giao việc xử lý lỗi của nút cho hai nhánh trên khung vẽ: thành công và thất bại. Cách này hoạt động giống như "Chạy nhánh xử lý ngoại lệ" trong trình chỉnh sửa của ứng dụng. Để thiết lập:

- Đặt `data.exception` thành `{"mode":"branchHandle"}` (cùng cấp với `data.browserUi`, không đặt bên trong browserUi.exception).
- Đặt `data.browserUi.exception.policy` thành `"handle"`.
- Cho `blocks` gồm đúng hai nút `exceptionBlock`: nút thứ nhất là nhánh thành công, nút thứ hai là nhánh thất bại. Chỉ thứ tự trong mảng quyết định vai trò. Tiêu đề và ID có thể tùy ý, và một nhánh có thể không chứa nút nào.


Ngữ nghĩa thực thi:

| Kết quả cuối cùng của nút cha | Hành vi |
|  --- | --- |
| Thành công (kể cả thành công sau khi thử lại) | Chỉ chạy nhánh thành công, rồi tiếp tục với các nút sau nút cha |
| Thất bại (đã hết số lần thử lại) | Chỉ chạy nhánh thất bại, rồi tiếp tục. Bản ghi của nút cha vẫn ở trạng thái failed và giữ lỗi ban đầu cùng ảnh chụp màn hình khi thất bại, kèm `nextAction=continue`; lượt chạy có hasNodeErrors=true |
| Bị hủy, hoặc thao tác ban đầu vẫn chưa kết thúc sau khi hết thời gian chờ và việc tiếp quản lại môi trường thất bại (ngữ cảnh thực thi đã bị cách ly) | Không đi vào nhánh thất bại; lượt chạy kết thúc, giống như với các chính sách khác |


- Ở chế độ nhánh, `handler` không có tác dụng (không chụp ảnh màn hình thay thế, không ghi chú, không dừng). Việc có chụp ảnh màn hình khi thất bại hay không chỉ phụ thuộc vào `screenshot`.
- `data` của nút cha được phân giải thành null theo quy tắc dành cho "nút tiếp tục sau khi thất bại". Bên trong nhánh thất bại, bạn có thể tham chiếu `${parentId.error.code}` và `${parentId.status}`.
- Hai nhánh loại trừ lẫn nhau. Nút trong nhánh này không thể tham chiếu đến nút trong nhánh kia (RPA_REFERENCE_NOT_VISIBLE), và bản thân `exceptionBlock` không thể được tham chiếu. Khi một nút phía sau các nhánh tham chiếu đến một nút bên trong nhánh, tham chiếu đó cần được kiểm tra khi chạy.
- Khi một nút bên trong nhánh thất bại, lỗi được xử lý theo exception của chính nút đó và không đi vào nhánh thất bại của nút cha lần nữa. Lần thử lại của nút cha không chạy lại các nhánh.
- Cấu trúc không khớp sẽ trả về RPA_STRUCTURE_INVALID: mode=branchHandle nhưng blocks không phải là đúng hai nút exceptionBlock, policy không phải là handle, thiết lập được đặt trên ifElse/loop, hoặc một exceptionBlock không nằm dưới một nút như vậy.
- `data.exception.mode` được đặt thành `skipStep` / `stopTask` chỉ là dấu đánh dấu của trình chỉnh sửa. Việc thực thi tuân theo policy, và nút không thể có nút con exceptionBlock.


```json
{
  "id": "open_shop",
  "type": "browser_newPage",
  "data": {
    "browserAction": "newPage",
    "browserUi": {
      "inputs": {"openMode": "url", "url": "https://example.com"},
      "exception": {"policy": "handle", "retry": true, "retryTimes": 2, "retryInterval": 2, "screenshot": true}
    },
    "exception": {"mode": "branchHandle"}
  },
  "blocks": [
    {"id": "open_ok", "type": "exceptionBlock", "data": {"title": "Success"}, "blocks": []},
    {"id": "open_failed", "type": "exceptionBlock", "data": {"title": "Failure"}, "blocks": [
      {"id": "wait_retry", "type": "browser_waitTime", "data": {"browserAction": "waitTime", "browserUi": {"inputs": {"timeoutType": "fixed", "timeout": 1000}}}}
    ]}
  ]
}
```

### Nút điều khiển, trạng thái kết thúc và các giai đoạn xác thực

Các nút điều khiển trong danh mục công khai là browser_ifElse, browser_loop, browser_breakLoop, browser_applySubProcess và browser_updateCustomVariable (việc một nút có được cung cấp hay không vẫn phụ thuộc vào danh mục của instance). Các nút này chấp nhận một đối tượng exception. Trường timeout giới hạn toàn bộ lần gọi điều khiển và các lần gọi con của nó, và là 0 (không giới hạn) khi bị bỏ qua. Các trường policy/handler/screenshot xử lý lỗi của lần gọi điều khiển, bao gồm cả các lỗi lan lên đến lần gọi đó. Các tín hiệu điều khiển break, end và stop thông thường không bị coi là lỗi có thể thử lại. Các trường retry/retryTimes/retryInterval vẫn phải vượt qua bước xác thực trường, nhưng nút điều khiển bỏ qua việc thử lại khi chạy và không chạy lại toàn bộ đồ thị con. Hành động nguyên tử trong các nút con chạy theo exception của chính chúng.

Nút có handler=remark có thể được lưu, và cũng có thể chạy từ bên ngoài qua Local API, giống như khi chạy trong ứng dụng.

Nút tiếp tục sau khi thất bại: khi một nút đã chạy, cuối cùng vẫn thất bại và tiếp tục theo exception của nút đó (policy=skip, hoặc tiếp tục sau handle), các tham chiếu về sau đến các trường dưới `data` của nút sẽ được phân giải thành `null`. Tham chiếu toàn bộ giá trị (chẳng hạn `{type:'ref',content:['read','data','value']}` hoặc toàn bộ chuỗi `"${read.data.value}"`) nhận `null`, còn tham chiếu được ghép trong chuỗi template (chẳng hạn `"Title: ${read.data.value}"`) nhận chuỗi rỗng. Tham chiếu đến các đường dẫn không thuộc data, chẳng hạn `${id.status}` và `${id.error}`, không thay đổi. Tham chiếu đến một nút không tồn tại, một nút chưa chạy, hoặc một trường không tồn tại trên một nút đã thành công vẫn thất bại khi chạy với MISSING_VARIABLE. Các quy tắc kiểm tra tham chiếu tĩnh trước khi lưu và chạy không thay đổi. Do đó, các nút phía sau có thể tham chiếu trực tiếp đến một nút thu thập dữ liệu có thể bị bỏ qua, mà không cần thêm nút biến "xóa/ghi lại". Trong điều kiện, phép so sánh gt/gte/lt/lte với null không được thỏa mãn. Để phân biệt "không đọc được gì" với "đọc được 0", hãy kiểm tra exists trước.

Bảng dưới đây chỉ mô tả kết quả mặc định sau khi một nút đơn lẻ đã được thực thi và thất bại. Bảng giả định rằng kết quả không bị ghi đè bởi việc hủy, việc cách ly ngữ cảnh thực thi, một lỗi xảy ra sau đó, việc đánh giá đầu ra thất bại hoặc một chỉ thị kết thúc tường minh:

| Chính sách | Hành động tiếp theo | run.status | hasNodeErrors |
|  --- | --- | --- | --- |
| interrupt | Ngắt lượt chạy | failed | true |
| skip | Tiếp tục với các nút tiếp theo | success (khi mọi nút phía sau đều chạy bình thường) | true |
| handle + screenshot, chụp ảnh màn hình thành công | Tiếp tục với các nút tiếp theo | success (khi mọi nút phía sau đều chạy bình thường) | true |
| handle + screenshot, chụp ảnh màn hình thất bại | Ngắt lượt chạy | failed | true |
| handle + stop | Không chạy thêm nút nào | stopped | true |


Đây là ngữ nghĩa thực thi, không phải quy tắc để suy ra kết quả thay cho việc truy vấn. Việc hủy có thể dẫn đến cancelled. Nút hết thời gian chờ dẫn đến failed (TIMEOUT) và được xử lý theo retry/screenshot/policy. Khi tác vụ hết thời gian chờ, hoặc trình duyệt của môi trường chính bị đóng trong khi chạy, nút đang chạy kết thúc với failed, giống như lượt chạy (RPA_TASK_TIMEOUT / ENVIRONMENT_CLOSED), và retry/policy không được áp dụng. Khi không thể xác nhận việc dừng, lượt chạy kết thúc với failed kèm error.code OUTCOME_UNKNOWN. Sau cùng, hãy luôn đọc run.status, hasNodeErrors và isolation thực tế.

JSON Schema của WorkflowException chỉ ràng buộc hình dạng của các trường; các quy tắc về số nguyên và phạm vi do bước xác thực ngữ nghĩa kiểm tra. Ngay cả khi bước kiểm tra schema cục bộ đã vượt qua, bạn vẫn phải gọi validations. Một lần gọi hành động nguyên tử chỉ thử chụp tối đa một ảnh màn hình khi thất bại, sau khi đã hết số lần thử lại. Nhiều lần gọi trong vòng lặp, hoặc các lỗi riêng biệt của nút cha và nút con, có thể tạo ra nhiều ảnh chụp màn hình.

Ví dụ đầy đủ về việc gắn chính sách ngoại lệ vào một nút (bộ chọn `[` được cố ý dùng để gây lỗi khi chạy, giúp bạn quan sát cách xử lý lỗi):

```json
{
  "id": "capture_failure",
  "type": "browser_getElement",
  "data": {
    "browserAction": "getElement",
    "browserUi": {
      "inputs": {
        "selector": "[",
        "selectorType": "selector",
        "outputRange": "single",
        "type": "innerText"
      },
      "exception": {
        "policy": "interrupt",
        "screenshot": true,
        "retry": false
      }
    }
  }
}
```

Để biết các trường tạo phẩm xuất hiện ở đâu trong bản ghi nút và cách truy vấn chúng theo từng trang, xem [Liệt kê lượt thực thi nút](/vi/browser-rpa/api/list-run-nodes). Về cấu trúc của tập hợp tạo phẩm, xem [Liệt kê tạo phẩm của lượt chạy](/vi/browser-rpa/api/list-run-artifacts).