Tích hợp (Integrations)

Tổng quan

Trang Quản trị → Tích hợp cho phép quản trị viên kết nối tài khoản bên thứ ba — ví dụ HubSpot — với tổ chức AgentFlow. Sau khi kết nối, các bước Tích hợp (Integration) trong quy trình có thể đọc và ghi bản ghi vào hệ thống đó mà không cần lưu mật khẩu ở phía người dùng.

Thông tin xác thực được niêm phong khi lưu và không bao giờ hiển thị lại. Quy trình tham chiếu đến tên kết nối, không phải khóa.

Trang này quản lý ba loại kết nối, nằm chung một bảng nhưng không có cùng bộ thao tác:

Loại	Dùng cho	Cách tạo
Tài khoản OAuth (ví dụ HubSpot)	Bước Tích hợp (Integration) và các trình kích hoạt từ nhà cung cấp	Cấp quyền qua cửa sổ bật lên
Cơ sở dữ liệu / kho dữ liệu	Bước Truy vấn SQL (SQL query)	Nhập thông tin đăng nhập vào biểu mẫu
Lưu trữ tệp (SFTP / FTP)	Thư mục theo dõi	Nhập thông tin máy chủ, rồi xác nhận thứ máy chủ trình ra

Ghi chú

Cần có quyền integration.admin để quản lý tích hợp. Nếu không thấy mục Tích hợp trong sidebar, hãy liên hệ quản trị viên hệ thống.

Kết nối một tài khoản

Ghi chú

Các bước dưới đây là dành cho kết nối OAuth. Kết nối cơ sở dữ liệu và kết nối lưu trữ tệp cũng bắt đầu từ nút Kết nối, nhưng bước thứ hai là một biểu mẫu chứ không phải cửa sổ cấp quyền — xem hai mục cuối trang.

1. Vào Quản trị → Tích hợp và nhấn Kết nối.
2. Trong hộp thoại, chọn Nhà cung cấp (ví dụ: HubSpot).
3. Đặt Tên kết nối để phân biệt với các tài khoản khác, ví dụ: HubSpot Kinh doanh.
4. Tùy chọn: thêm Mô tả để ghi rõ kết nối này dùng để làm gì.
5. Nhấn Sau.
6. Nhấn Kết nối tới HubSpot — một cửa sổ bật lên sẽ xuất hiện yêu cầu bạn đăng nhập và cấp quyền cho AgentFlow.
7. Sau khi cấp quyền thành công, cửa sổ bật lên tự đóng và trạng thái chuyển sang Đã cấp quyền. Lưu để hoàn tất.
8. Nhấn Tạo kết nối.

Mẹo

Bạn có thể kết nối nhiều tài khoản của cùng một nhà cung cấp — ví dụ, một tài khoản HubSpot cho nhóm Kinh doanh và một tài khoản khác cho nhóm Hỗ trợ. Mỗi kết nối có tên riêng và hiển thị riêng biệt trong trình thiết kế quy trình.

Mỗi dòng kết nối cho biết gì

Danh sách hiển thị mỗi kết nối trên một dòng. Trên dòng đó có:

Thông tin	Ý nghĩa
Tên kết nối	Tên bạn đặt khi kết nối
Trạng thái	Đã kết nối / Cần kết nối lại / Lỗi
Nhà cung cấp	HubSpot, PostgreSQL, SFTP, FTP…
Tài khoản	Mã định danh tài khoản bên thứ ba
Mô tả	Nếu bạn có nhập khi tạo

Kết nối lại

Ghi chú

Kết nối lại chỉ có ở kết nối OAuth. Kết nối cơ sở dữ liệu và kết nối lưu trữ tệp không có nút này — chúng không giữ token nào để hết hạn; muốn thay thông tin đăng nhập thì dùng Sửa.

Nếu một kết nối hiển thị trạng thái Cần kết nối lại (token hết hạn hoặc bị thu hồi phía nhà cung cấp):

1. Nhấn Kết nối lại trên dòng kết nối đó. Hộp thoại mở ra với nhà cung cấp và tên đã điền sẵn — nhấn Sau.
2. Hoàn tất lại quy trình cấp quyền trong cửa sổ bật lên — phải dùng đúng tài khoản ban đầu.
3. Nhấn Tạo kết nối.

Ghi chú

Nếu bạn đang ở trang chi tiết của kết nối, nút Kết nối lại ở đó mở thẳng cửa sổ cấp quyền và tự hoàn tất khi bạn cấp xong — không qua hộp thoại nào.

Chú ý

Nếu bạn cấp quyền bằng tài khoản khác với tài khoản gốc của kết nối, hệ thống sẽ không lưu và báo rằng tài khoản vừa cấp quyền khác với tài khoản của kết nối này, kèm lời nhắc kết nối lại bằng đúng tài khoản ban đầu. Điều này bảo vệ các phiên chạy quy trình đang chạy khỏi bị chuyển sang tài khoản khác một cách ngoài ý muốn.

Thu hồi kết nối

Khi bạn không còn cần một kết nối:

1. Nhấn biểu tượng thùng rác ở cuối dòng kết nối — hoặc mở trang chi tiết của kết nối rồi nhấn Thu hồi.
2. Xác nhận trong hộp thoại — thao tác này không thể hoàn tác.

Thu hồi xóa hẳn kết nối cùng thông tin xác thực đã lưu; kết nối biến mất khỏi danh sách. Các quy trình đang dùng nó sẽ gặp lỗi cho đến khi bạn tạo một kết nối mới và trỏ quy trình sang đó.

Xem lịch sử hoạt động

Nhấn vào tên một kết nối để xem trang chi tiết và phần Hoạt động. Phần này ghi lại mọi sự kiện đến từ nhà cung cấp.

Cột	Ý nghĩa
Thời điểm	Khi nào sự kiện đến
Nguồn	Webhook (thời gian thực) hoặc Đồng bộ (bắt kịp định kỳ)
Trạng thái	Đã nhận / Đã điều phối / Lỗi treo
Thay đổi	Loại thay đổi: Tạo mới / Cập nhật / Đã xóa
Quy trình	Phiên chạy được khởi chạy (nếu có)

Sử dụng bộ lọc Nguồn và Trạng thái để thu hẹp kết quả khi cần tìm một sự kiện cụ thể.

Ghi chú

Kết nối lưu trữ tệp không có phần Hoạt động — không có webhook và không có lượt đồng bộ nào để ghi vào đó. Trang chi tiết của chúng hiển thị phần Thư mục đang theo dõi thay vào chỗ đó; xem mục Kết nối lưu trữ tệp bên dưới.

Xử lý cửa sổ bật lên bị chặn

Nếu thấy thông báo “Trình duyệt đã chặn cửa sổ bật lên”:

1. Tìm biểu tượng chặn pop-up trên thanh địa chỉ của trình duyệt.
2. Chọn tùy chọn cho phép pop-up của trang AgentFlow — cách gọi khác nhau tùy trình duyệt.
3. Nhấn Kết nối tới … lại một lần nữa.

Một số trình duyệt lưu cài đặt này theo domain, vì vậy bạn chỉ cần cho phép một lần.

Ví dụ: Quy trình “Đề xuất mua sắm”

Trong quy trình mẫu Đề xuất mua sắm, bước cuối dùng nút Tích hợp (Integration) để tạo hoặc cập nhật một Deal trong HubSpot sau khi phê duyệt xong. Bước đó tham chiếu đến kết nối HubSpot Kinh doanh đã thiết lập ở đây — không cần nhập lại thông tin xác thực khi thiết kế quy trình.

Xem thêm: Nút Tích hợp trong quy trình.

Kết nối cơ sở dữ liệu

Ngoài các kết nối OAuth ở trên, trang Tích hợp cũng là nơi quản lý kết nối cơ sở dữ liệu (database) và kho dữ liệu (data warehouse) — dùng bởi bước Truy vấn SQL (SQL query) trong quy trình để đọc, và khi được bật, ghi dữ liệu vào hệ thống nội bộ của bạn. Đây không phải một trang quản trị riêng — kết nối cơ sở dữ liệu chỉ là một loại kết nối khác, nằm chung bảng với các kết nối OAuth như HubSpot.

Khác với kết nối OAuth (cấp quyền qua cửa sổ bật lên), kết nối cơ sở dữ liệu được tạo bằng cách nhập trực tiếp thông tin đăng nhập vào một biểu mẫu — không có bước cấp quyền nào cả.

Tạo một kết nối cơ sở dữ liệu

1. Vào Quản trị → Tích hợp và nhấn Kết nối.
2. Chọn một Nhà cung cấp là cơ sở dữ liệu hoặc kho dữ liệu (ví dụ PostgreSQL), đặt Tên kết nối và tùy chọn Mô tả, rồi nhấn Sau.
3. Điền thông tin kết nối:
   • Máy chủ và Cổng (mặc định 5432).
   • Cơ sở dữ liệu — tên database/schema cần kết nối tới.
   • Tên đăng nhập và Mật khẩu.
   • Chế độ SSL — từ verify-full (chặt chẽ nhất) đến disable (chỉ dùng khi phát triển).
   • Công tắc Cho phép ghi — tắt theo mặc định, xem mục Cho phép ghi bên dưới.
   • Mở Cài đặt nâng cao nếu muốn đặt giới hạn riêng cho kết nối này: hết hạn câu lệnh, hết hạn khóa, số dòng tối đa, số byte tối đa, số kết nối tối đa trong pool. Hệ thống luôn áp dụng giá trị nghiêm ngặt hơn giữa các giới hạn này và giới hạn cứng của deployment.
4. Nhấn Tạo kết nối. Hệ thống thử kết nối tới máy chủ trước khi lưu; nếu thất bại, lỗi trả về sẽ nêu rõ nguyên nhân (sai thông tin đăng nhập, không tới được máy chủ, lỗi TLS…).

Mẹo

Nên dùng một vai trò cơ sở dữ liệu chỉ đọc cho kết nối, trừ khi quy trình của bạn thực sự cần ghi dữ liệu qua bước Truy vấn SQL.

Kết nối cơ sở dữ liệu xuất hiện trong cùng bảng với các kết nối OAuth, nhưng có hai nút thao tác riêng: Sửa (mở lại biểu mẫu trên; để trống ô mật khẩu để giữ nguyên thông tin xác thực đã lưu) và Kiểm tra (xác minh kết nối vẫn dùng được mà không cần mở biểu mẫu sửa).

Cho phép ghi (Allow writes)

Theo mặc định, một kết nối cơ sở dữ liệu mới không cho phép ghi — mọi câu lệnh chạy qua kết nối này chỉ có thể đọc dữ liệu, bất kể quy trình nào tham chiếu tới nó. Bật công tắc Cho phép ghi trong biểu mẫu kết nối (lúc tạo hoặc lúc sửa) để cho phép câu lệnh INSERT / UPDATE / DELETE chạy qua kết nối này.

Chú ý

Bật Cho phép ghi mới chỉ mở khả năng ghi ở tầng kết nối. Để một bước Truy vấn SQL trong quy trình thực sự chạy được ở chế độ ghi, tác giả thiết kế bước đó còn cần quyền workflow.sql.write (hoặc là quản trị viên tổ chức) — cả hai điều kiện phải đúng đồng thời. Xem Truy vấn SQL để biết chi tiết cách quyền này kết hợp với công tắc này.

Vì câu lệnh ghi có thể sửa hoặc xóa dữ liệu, và có thể chạy lại nhiều lần khi hệ thống thử lại — chỉ bật Cho phép ghi cho một kết nối có thông tin đăng nhập được giới hạn đúng phạm vi dữ liệu mà quy trình của bạn được phép thay đổi.

Xem thêm: Truy vấn SQL.

Kết nối lưu trữ tệp (SFTP / FTP)

Loại kết nối thứ ba trên trang này là lưu trữ tệp: một máy chủ SFTP hoặc FTP mà bên gửi đổ tệp vào — máy quét của phòng văn thư, một điểm nhận hồ sơ của đối tác, một thư mục ai đó chép tài liệu vào hằng ngày.

Kết nối này không phục vụ một nút nào trên canvas. Nó phục vụ Thư mục theo dõi: bạn trỏ một thư mục theo dõi vào một thư mục trên máy chủ đó, hệ thống liệt kê thư mục vài phút một lần và ghi nhận có những gì trong đó, rồi quy trình xử lý từng hồ sơ. Tệp không bị sao chép và không bị thay đổi.

Ghi chú

Nếu thư mục nằm ngay trên chính hệ thống chạy AgentFlow (lựa chọn Trên chính hệ thống này khi tạo thư mục theo dõi), bạn không cần kết nối nào cả — đường dẫn đó do người vận hành cấu hình sẵn. Kết nối chỉ cần khi thư mục nằm trên một máy chủ SFTP hoặc FTP.

Tạo một kết nối SFTP hoặc FTP

Vẫn bắt đầu từ nút Kết nối như mọi loại kết nối khác, nhưng bước thứ hai hỏi thông tin máy chủ thay vì mở cửa sổ cấp quyền.

1. Vào Quản trị → Tích hợp và nhấn Kết nối.
2. Chọn Nhà cung cấp là SFTP hoặc FTP, đặt Tên kết nối và tùy chọn Mô tả, rồi nhấn Sau.
3. Điền thông tin máy chủ:
   • Máy chủ và Cổng.
   • Tên đăng nhập.
   • Với SFTP: Đăng nhập bằng — chọn Mật khẩu hoặc Khóa riêng (dán khóa chưa đặt mật khẩu bảo vệ; khóa được cất giữ đã mã hóa và không hiển thị lại).
   • Với FTP: chỉ có Mật khẩu — FTP không dùng cặp khóa. Ngoài ra còn lựa chọn Bảo mật đường truyền, xem mục dưới.
   • Thư mục gốc — mọi thứ kết nối này đọc đều nằm bên trong đường dẫn đó.
4. Nhấn Kiểm tra máy chủ (SFTP) hoặc Kết nối và kiểm tra (FTP). Hệ thống kết nối đúng một lần và hiển thị thứ máy chủ vừa trình ra: khóa máy chủ với SFTP, chứng thư với FTP. Chưa có gì được lưu ở bước này.
5. Đối chiếu giá trị hiển thị với giá trị bạn được cấp qua một kênh khác. Khớp thì nhấn Khớp — lưu lại (SFTP) hoặc Xác nhận và lưu (FTP). Không khớp thì đừng lưu.

Mẹo

Bước 4–5 là một bước xác nhận, không phải bước gõ lại. Giá trị trên màn hình là thứ máy chủ vừa trình ra; việc của bạn chỉ là nói nó có đúng là máy chủ bạn định trỏ tới hay không.

Sau khi lưu, kết nối hiện trong cùng bảng với các kết nối khác và có thể chọn được khi tạo thư mục theo dõi.

Bảo mật đường truyền (chỉ FTP)

FTP gửi mật khẩu ở dạng văn bản thuần nếu không bật TLS, nên Bảo mật đường truyền không phải một tùy chọn theo sở thích.

Lựa chọn	Ý nghĩa
TLS, ghim chứng thư	Mặc định. Chứng thư của máy chủ được ghim theo vân tay. Đây là chế độ duy nhất an toàn khi máy chủ nằm trong mạng nội bộ hoặc VPN.
TLS, xác thực qua CA	Đối chiếu với các CA của hệ thống. Dùng cho máy chủ có chứng thư thật.
Không có	Hoàn toàn không mã hóa: mật khẩu và toàn bộ tệp đi qua mạng ở dạng văn bản thuần. Biểu mẫu cảnh báo ngay khi bạn chọn mục này.

Chú ý

Một số máy chủ FTP không báo được thời điểm sửa tệp đủ chính xác để phân biệt một tài liệu đã ghi xong với một tài liệu đang được ghi dở. Máy chủ như vậy bị từ chối ngay ở bước kiểm tra, kèm lý do — không thể dùng để theo dõi thư mục, và biết điều đó lúc này tốt hơn là biết sau nhiều giờ theo dõi một thư mục không bao giờ sẵn sàng.

Chú ý

Một số máy chủ FTP ẩn các tệp có tên bắt đầu bằng dấu chấm. Khi gặp máy chủ như vậy, bước kiểm tra sẽ hiện cảnh báo. Trên kết nối đó không dùng được tệp báo hoàn tất (theo quy ước là .done): hệ thống không nhìn thấy tệp đánh dấu nên thư mục sẽ không bao giờ được coi là sẵn sàng, dù các tệp khác vẫn hiện đầy đủ. Với kết nối này hãy dùng khoảng lặng thay cho tệp đánh dấu.

Điểm kết nối cố định sau khi lưu

Với cả SFTP và FTP, máy chủ, cổng, tên đăng nhập, thư mục gốc, và phần đã ghim (khóa máy chủ với SFTP; bảo mật đường truyền và chứng thư với FTP) không sửa được sau khi lưu.

Nút Sửa trên một kết nối lưu trữ tệp chỉ cho phép:

• đổi Tên và Mô tả;
• thay thông tin đăng nhập — để trống ô đó nếu muốn giữ nguyên thông tin đã lưu.

Biểu mẫu vẫn hiển thị điểm kết nối để bạn biết kết nối này trỏ tới đâu và được bảo vệ ra sao, nhưng các ô đó không sửa được.

Chú ý

Lý do không cho đổi: mỗi lần đọc, thư mục theo dõi phân giải lại kết nối này theo thời gian thực, và phần đã ghim chính là thứ khiến điều đó an toàn. Nếu đổi được đích, một lần chạy đang diễn ra sẽ nhận tệp của một máy chủ khác dưới đúng những tên đường dẫn cũ, và không có gì phát hiện ra. Muốn trỏ sang máy chủ khác thì tạo một kết nối mới.

Trang chi tiết của một kết nối lưu trữ tệp

Kết nối lưu trữ tệp không có ba nút Đồng bộ ngay, Kết nối lại và Kiểm tra. Hai nút đầu thuộc về kết nối OAuth; nút thứ ba thuộc về kết nối cơ sở dữ liệu. Một thư mục theo dõi tự làm mới theo lịch quét riêng của nó, và thông tin đăng nhập được dùng thật ở mỗi lượt quét.

Thay cho phần Hoạt động, trang chi tiết hiển thị phần Thư mục đang theo dõi — danh sách các thư mục theo dõi đang dùng kết nối này, mỗi dòng kèm số tệp đã ghi nhận và lần kiểm gần nhất. Nhấn vào một dòng để mở thư mục đó; Xem tất cả mở danh sách thư mục theo dõi đầy đủ.

Thu hồi vẫn có như với mọi kết nối khác. Sau khi thu hồi, các thư mục theo dõi trỏ vào máy chủ này không còn đọc được nữa và sẽ báo lỗi ở lượt kiểm tiếp theo.

Xem thêm: Thư mục theo dõi.