Power Automate và Power Apps

Trình kết nối AutomaDoc đưa các mẫu của bạn vào công cụ quy trình làm việc của Microsoft. Một luồng gửi giá trị cho các biến giữ chỗ của mẫu (từ một mục danh sách SharePoint, một hàng Dataverse, một hàng Excel, một câu trả lời biểu mẫu) và nhận lại tài liệu hoàn chỉnh, sẵn sàng để lưu vào thư viện tài liệu, đính kèm email hoặc đăng lên Teams.

Trình kết nối hoạt động trong Power Automate, Power Apps (thông qua một luồng), Azure Logic Apps và Copilot Studio. Nó được xây dựng trên API tài liệu, nên mọi thứ API làm với dữ liệu của bạn (tên, vòng lặp, hình ảnh, điều kiện) ở đây đều giống hệt.

Trước khi bắt đầu

Một mẫu. Tạo mẫu trong Cổng thông tin công ty tại Mẫu, trong phần bổ trợ Excel hoặc trong tiện ích Lark Base, với các biến giữ chỗ như {Customer}, {Invoice_No} hoặc một vòng lặp {#Items}…{/Items}. Trình kết nối hiển thị một ô nhập cho mỗi biến giữ chỗ, đọc từ lần tải lên gần nhất của mẫu.
Một khóa API của công ty. Quản trị viên của công ty bạn tạo khóa trong Cổng thông tin công ty, tại Công ty → Khóa API. Khóa bắt đầu bằng amk_ và chỉ hiển thị một lần: hãy sao chép và cất giữ ở nơi an toàn. (Khóa riêng của một mẫu không thể liệt kê các mẫu của bạn, nên trình kết nối cần khóa của công ty.)

Thêm trình kết nối

Khi trình kết nối AutomaDoc chưa có trong danh sách trình kết nối được chứng nhận, hãy thêm nó vào môi trường của bạn dưới dạng trình kết nối tùy chỉnh. Việc này làm một lần cho mỗi môi trường Power Platform.

Lấy định nghĩa của trình kết nối. Tải xuống Tải xuống định nghĩa trình kết nối, hoặc dùng địa chỉ của nó: https://api.automadoc.cc/api/v1/power-platform.swagger.json
Trong Power Automate, mở Data → Custom connectors (hoặc More → Discover all → Custom connectors), chọn New custom connector, rồi chọn Import an OpenAPI file (tệp bạn đã tải xuống) hoặc Import an OpenAPI from URL (dán địa chỉ). Đặt tên là AutomaDoc và chọn Continue.
Tab General được điền sẵn từ định nghĩa (máy chủ, URL cơ sở và mô tả): không cần thay đổi gì.
Trên tab Security, kiểm tra loại xác thực là API Key, tên tham số X-Webhook-API-Key và vị trí Header (đi kèm định nghĩa). Nếu nhãn tham số trống, hãy nhập API Key. Chọn Create connector.
Trên tab Test, chọn New connection, dán khóa API của công ty và tạo kết nối. Kiểm tra thao tác ListTemplates: nó trả về 200 kèm các mẫu của bạn.

Trong một luồng, thêm hành động và tìm AutomaDoc: nó nằm cùng các trình kết nối tùy chỉnh của bạn. Khi trình kết nối được chứng nhận đã được phát hành, hãy tìm AutomaDoc khi thêm hành động và dán khóa khi được yêu cầu kết nối.

Nếu chính sách ngăn mất dữ liệu (DLP) của tổ chức bạn chặn trình kết nối tùy chỉnh, quản trị viên Power Platform có thể cho phép trình kết nối này theo máy chủ của nó, api.automadoc.cc. Trang Power Automate của Cổng thông tin công ty có cùng các bước và nút tải xuống.

Hướng dẫn từng bước: một tài liệu cho mỗi mục SharePoint mới

Luồng này tạo một hóa đơn mỗi khi một mục được thêm vào danh sách SharePoint, và lưu tệp PDF vào thư viện tài liệu.

Điều kiện kích hoạt. Tạo một automated cloud flow với SharePoint → When an item is created, rồi chọn site và danh sách của bạn (ví dụ Invoices).
Tạo tài liệu. Thêm AutomaDoc → Generate a document.
- Template: chọn mẫu hóa đơn của bạn trong danh sách.
- Các ô nhập của mẫu hiện ra bên dưới. Ánh xạ từng ô từ nội dung động (dynamic content) của điều kiện kích hoạt: Invoice_No ← Title, Customer ← Customer, Total ← Amount, v.v.
- Output Format: pdf. Bước này chờ đến khi tài liệu sẵn sàng, rồi chuyển cho các bước tiếp theo Document ID, File Name, Status và Download URL của tài liệu.
Tải tài liệu xuống. Thêm AutomaDoc → Download document với Document ID ← Document ID từ bước trước.
Lưu tài liệu. Thêm SharePoint → Create file:
- Folder Path: thư viện của bạn, ví dụ /Shared Documents/Invoices.
- File Name: File Name từ Generate a document.
- File Content: File Content từ Download document.
Lưu luồng và thêm một mục vào danh sách. Tệp PDF xuất hiện trong thư viện sau vài giây.

Để gửi qua email thay vào đó, dùng Office 365 Outlook → Send an email (V2) với một tệp đính kèm: tên là File Name, nội dung là File Content.

Nhiều luồng dựng sẵn khác, cho một phê duyệt, một câu trả lời Microsoft Forms hoặc việc đính kèm tệp vào mục, có trong Công thức Power Automate.

Các khoản mục: vòng lặp trong mẫu

Một hàng bảng {#Items}…{/Items} trong mẫu xuất hiện dưới dạng ô nhập danh sách, Items, với mỗi cột là một trường. Để điền nó từ một danh sách khác (ví dụ các dòng của hóa đơn), hãy chuyển ô nhập sang chế độ entire array và truyền vào một mảng có các đối tượng dùng tên cột làm khóa, ví dụ được tạo bằng Data Operation → Select từ Get items:

Select: khóa ánh xạ	Giá trị
`Product`	Title
`Qty`	Quantity
`Price`	UnitPrice

Từ Dataverse hoặc Excel

Các bước sau điều kiện kích hoạt vẫn như vậy; chỉ điều kiện kích hoạt và nội dung động thay đổi:

Dataverse: When a row is added, modified or deleted (change type Added), rồi ánh xạ các cột của hàng vào các ô nhập của mẫu.
Excel Online (Business): For a selected row (chạy từ Excel), hoặc List rows present in a table theo sau là Apply to each: mỗi hàng một Generate a document sẽ tạo một tài liệu cho mỗi hàng.

Một tài liệu từ nhiều hàng

Một mẫu được thiết lập để tạo một tài liệu từ nhiều bản ghi (một danh sách, mỗi bản ghi một trang, nhãn) nhận một danh sách thay vào đó: ô nhập của nó là Records, mỗi hàng một phần tử, và bước này tạo một tài liệu từ tất cả các hàng. Truyền các hàng của List rows hoặc Get items qua một bước Select, như với các khoản mục. Tối đa 500 hàng cho mỗi tài liệu.

Power Apps

Tạo tài liệu trong một luồng và gọi luồng đó từ ứng dụng:

Tạo một instant cloud flow với điều kiện kích hoạt Power Apps (V2) và thêm các ô nhập văn bản cho những giá trị mà ứng dụng gửi.
Thêm Generate a document và ánh xạ các ô nhập đó; kết thúc bằng Respond to a Power App or flow trả về Download URL (hoặc lưu tệp như trên và trả về liên kết của tệp).
Trong ứng dụng, gọi luồng từ một nút: Set(doc, GenerateInvoice.Run(txtCustomer.Text, txtTotal.Text)); Launch(doc.downloadurl).

Luồng sẽ chờ tài liệu. Một ứng dụng gọi trực tiếp trình kết nối thì không phải chờ: nó nhận lại tài liệu khi tài liệu vẫn đang ở trạng thái processing, và phải gọi Get document status cho đến khi tài liệu hoàn tất.

Logic Apps và Copilot Studio

Cùng trình kết nối này hoạt động trong Logic Apps (Standard và Consumption), với cùng các hành động. Trong Copilot Studio, thêm Generate a document làm công cụ (tool) cho agent của bạn: agent điền các ô nhập của mẫu từ cuộc hội thoại và có thể đưa cho người dùng Download URL.

Cách bước tạo tài liệu chờ

Generate a document dùng cơ chế thăm dò mà các công cụ quy trình làm việc của Microsoft tự tuân theo: yêu cầu được trả lời 202 Accepted kèm một liên kết để thăm dò, và nền tảng đọc liên kết đó mỗi 5 giây cho đến khi tài liệu hoàn tất, rồi tiếp tục với tài liệu hoàn chỉnh. Một tài liệu thất bại sẽ làm bước đó thất bại, kèm lý do (một vòng lặp không bao giờ được đóng, một hình ảnh không tải được) trong đầu ra của bước. Một tài liệu thất bại không bao giờ đến bước tiếp theo như thể nó là một tệp: Get document status và Download document cũng thất bại với nó (DOCUMENT_FAILED).

Nếu bạn tắt cài đặt Asynchronous pattern của bước này, nó trả về ngay khi tài liệu vẫn đang processing. Hãy thêm Get document status với Document ID: bước này chờ tài liệu theo cùng cách. Nếu cũng tắt asynchronous pattern của bước đó, nó trả lời ngay; khi đó hãy tự chờ bằng Do until Status khác processing, bên trong chứa Delay (5 giây) và Get document status. Tài liệu thất bại sẽ làm Get document status thất bại (422), nên vòng lặp dừng ở lỗi đó và không bao giờ đọc được failed: hãy xử lý bằng Configure run after (has failed) ở bước tiếp theo, hoặc đặt vòng lặp trong một Scope.

Giới hạn

60 yêu cầu mỗi phút cho mỗi mẫu và 600 tài liệu mỗi phút cho mỗi công ty, dùng chung với API tài liệu và HTTP Trigger; 60 lần liệt kê mẫu mỗi phút cho mỗi công ty; 60 lần đọc trạng thái và 60 lần tải xuống mỗi phút cho mỗi tài liệu. Khi vượt giới hạn, bước đó trả về 429 và chính sách thử lại của nền tảng sẽ thử lại.
Ô nhập hình ảnh phải là địa chỉ web công khai (https://, hoặc http://). Liên kết SharePoint hoặc OneDrive cần đăng nhập thì không tải được; hãy chia sẻ hình ảnh bằng liên kết công khai hoặc lưu trữ ở nơi khác.
Tài liệu được giữ lại bao lâu tùy theo thời gian công ty bạn lưu trữ tài liệu đã tạo (do gói của bạn quy định). Hãy tải tệp xuống ngay trong cùng luồng thay vì lưu liên kết.
Gửi tài liệu đi ký và tệp đính kèm được gộp vào PDF có sẵn qua API tài liệu, không phải dưới dạng ô nhập của trình kết nối.

Khắc phục sự cố

Điều bạn thấy	Lý do
Danh sách mẫu trống hoặc kết nối thất bại với `COMPANY_KEY_REQUIRED`	Kết nối đang dùng khóa riêng của một mẫu; hãy tạo kết nối bằng khóa API của công ty
Một biến giữ chỗ không có ô nhập	Các ô nhập lấy từ lần tải lên gần nhất của mẫu; hãy tải mẫu lên lại
`QUOTA_EXCEEDED`	Đã hết tài liệu trong tháng này; hãy mua gói tài liệu hoặc suất
Bước thất bại với `DOCUMENT_FAILED`	Không thể tạo tài liệu; đầu ra của bước cho biết lý do
Download document thất bại với `DOCUMENT_NOT_READY`	Asynchronous pattern của bước tạo tài liệu đang tắt, nên tài liệu vẫn đang được tạo; hãy thêm Get document status trước bước tải xuống

Mọi trường hợp từ chối khác đều được liệt kê kèm lý do trong tài liệu tham khảo API tài liệu.