Skip to main content

Embedded Review

Embedded review shows the review screen of one transaction inside a page of your own product, in a frame. Your user checks the extracted data, corrects it, and approves, rejects or sends the transaction on, without leaving your product.

When to use this

Use embedded review when the people who review documents work in your product, not in DocAI Fabric: a case handler confirming an invoice inside your ERP, or an agent checking an ID inside your onboarding tool. If they can work in DocAI Fabric itself, they review in My Work, with no integration (see Human Review).

How it works​

  1. Your backend submits the document, as in Process Documents via API.
  2. It waits until the transaction's status is awaiting_input, which means the transaction waits at a Human Review step. Long-polling reports it the moment it happens. To be told instead, place a Notification step just before the Human Review step: it posts to your endpoint when the transaction gets there.
  3. Your page shows the review screen in a frame, at the address below.
  4. The reviewer reviews the transaction inside the frame and decides. The frame signs no one in (below).
  5. The frame tells your page it is done (below), so your page can close it or open the next review.
  6. Your backend sees the new status, or receives the completion webhook, and reads the results as usual.

The frame​

<iframe
src="https://<your DocAI Fabric address>/transaction?transactionId=<transaction id>&source=work_queue&dataset=production&tenant_id=<tenant id>&project_id=<project id>&embed=1"
title="Review"
referrerpolicy="strict-origin-when-cross-origin"
style="width: 100%; height: 800px; border: 0"
></iframe>
ParameterValue
transactionIdThe transaction to review.
source, datasetwork_queue and production: the review screen as the work queue opens a production transaction. For a transaction in the Playground, playground and playground.
tenant_id, project_idThe transaction's tenant and project, so a reviewer who works in several opens the right one. Your organization's own sites (below) need tenant_id.
embed1: the review screen alone, without the rest of the app.

Give each parameter once, as written here. A frame whose address repeats embed or tenant_id, or writes them another way, is not allowed on your organization's sites.

Keep referrerpolicy on the frame. It makes the browser tell DocAI Fabric which site the frame is on, even where your page is set to send no address, and DocAI Fabric allows the frame only for a site on the list. The frame then adds embed_origin, your site's address, to its own address, so a reload inside it is allowed too. Don't write embed_origin yourself; the frame sets it from the address your page sends.

With embed=1 the frame shows the transaction's pages, its data and the review actions, and nothing that leads elsewhere in DocAI Fabric: no menu, no Assistant, no other transactions. What the reviewer may see and change is what their role allows, as anywhere else.

The frame holds one transaction:

  • After an approve, reject or send-on, the frame says the review is submitted, and tells your page so. To review the next transaction, open a new frame from your product, or point this one at the next transaction's address.
  • While the reviewer works, the transaction is held for them, as in the work queue. If they leave it without deciding (the hold ends after a while without activity, or another reviewer takes it over), the frame says nothing was decided and offers to open the transaction again. What they changed is kept.
  • When your page removes the frame, the hold is released.

Messages from the frame​

The frame tells the page around it what happened, with the browser's postMessage. Each message is an object:

{ "source": "docaifabric", "version": 1, "type": "docaifabric.review.decided", "transaction_id": "…", "decision": "approved" }
typeWhenAlso carries
docaifabric.review.readyThe review screen opened, with the transaction in view.transaction_id
docaifabric.review.unavailableThe frame shows a card instead of the review. A ready follows if the review comes back (the reviewer opens it again, or signs in in another tab).transaction_id, reason: no_session (nobody is signed in, see below), closed (the reviewer left the transaction without deciding), no_access (the signed-in reviewer may not open it), not_found (the address names no transaction) or error (it could not be loaded); for a review link, expired (its time is up, or the person reloaded the frame) or withdrawn (it no longer works)
docaifabric.review.decidedThe reviewer approved, rejected or sent the transaction on.transaction_id, decision: approved, rejected or sent_on, and step_id: the Review step it was decided at
docaifabric.review.goneNothing is left to review: every document was deleted.transaction_id
docaifabric.review.expiringA review link's frame only: its link expires in two minutes.transaction_id, expires_at

The frame sends its messages only to your page's own address, which it learns from the address your page sends when it opens the frame (keep referrerpolicy on the frame, above): never to any other page, and they carry no document data and no personal data: only the transaction's id and what happened, which your backend already knows. Accept a message only when it comes from the frame, on DocAI Fabric's address:

<script>
window.addEventListener('message', (event) => {
const frame = document.querySelector('iframe[title="Review"]');
if (event.origin !== 'https://<your DocAI Fabric address>' || event.source !== frame.contentWindow) return;
const m = event.data;
if (!m || m.source !== 'docaifabric') return;
if (m.type === 'docaifabric.review.decided' || m.type === 'docaifabric.review.gone') {
// Close the frame, or set its src to the next transaction's address.
}
});
</script>

A message is a convenience for your page, not a record: your backend still reads the transaction's status and results through the API. The frame takes one message from your page, a review link's renewal (below). New types and reasons may be added; ignore one you do not know.

Preview

Review links are in Preview: ready to use, and they may still change based on feedback. The system administrator can switch them off for the deployment or an organization.

A review link shows the review screen of one transaction in a frame to a person who has no account in DocAI Fabric: your product's own user. Your backend requests the link with one of your integration keys, for the person and the transaction, and your page opens the frame at the address it returns. Nothing in the frame names DocAI Fabric: no name, no logo, no sign-in.

curl -X POST "https://<your DocAI Fabric address>/api/transactions/<transaction id>/embed-token" \
-H "X-API-Key: <integration key>" -H "Content-Type: application/json" \
-d '{"actions": ["view", "edit_fields", "review"],
"reviewer": {"id": "4417", "name": "J. Smith"},
"frame_origin": "https://portal.example.com",
"language": "it"}'
FieldValue
actionsWhat the person may do: view the transaction, edit_fields (correct its data, change a document's class, add or edit lookup records where the rule allows), review (approve, reject or send it on).
reviewerOptional: who the person is in your product, an id and a name. The name shows in the transaction's history, in Reporting and in the exports; your id keeps one person one reviewer across your keys. Without either, the key is the reviewer.
frame_originOptional: your page's site. The frame then opens only inside a page of that site, which must be on your organization's list (below).
languageOptional: the review screen's language, such as it. Without it the person's browser chooses.
ttl_secondsOptional: how long the link works, 30 minutes by default and 2 hours at most.

The answer has the link's url, the frame's address with the link in its fragment, and its expires_at. Set your frame's src to the url exactly as returned, keeping referrerpolicy. The link is a credential: give it only to the person's page, and never write it to a log.

The key. An integration key whose permissions are listed, never one with every permission. It needs Make review links and the permissions of the link's actions (view, edit data, approve and reject). With Edit catalog records the person may add and edit lookup records, where the lookup rule allows it in the viewer; with Re-run transactions, after changing a document's class they may extract it again under the new class; with System can learn from user, Memory may learn from their review. The key is checked on every request: revoke it, or take a permission away, and its links stop at once.

Editing and deciding. A link that edits or decides is made only while the transaction waits at a Human Review step whose Reviewers from an embedding product is on, and it works at that step only: once the transaction moves on, the link only shows it. A link that only views works for any production transaction.

Reloads. The link lives in the frame's memory only. If the person reloads the frame from the browser, the review ends: the frame posts docaifabric.review.unavailable with expired, and your page requests a new link. The frame's own recovery keeps the review.

Two minutes before a link expires, the frame posts docaifabric.review.expiring. To keep the review open, request a new link for the same transaction, person and step, with the same key and actions, and post it to the frame:

frame.contentWindow.postMessage(
{ source: 'docaifabric', type: 'docaifabric.review.renew', token: newLink.token },
'https://<your DocAI Fabric address>'
);

The frame takes the new link only from your page, only after it posted expiring, and only when the new link is for the same review: the same transaction, step, person (reviewer.id and name), key, actions and frame_origin (the frame keeps its language). The person keeps their edits and their place. If the frame cannot check the new link for a moment, it tries again, and takes another one you post meanwhile. Otherwise the review ends when the link expires, with docaifabric.review.unavailable and expired.

If DocAI Fabric cannot be reached for a moment when a link's frame opens, the frame posts docaifabric.review.unavailable with error, keeps trying, and posts docaifabric.review.ready once the review opens. A link that no longer works posts withdrawn instead.

Before it works on your site​

  • Your site must be on the list. Browsers show the frame only on sites DocAI Fabric allows. Someone in your organization with the Manage tenant permission adds your site's address under Sites that may show the review screen on the General tab of Organization Settings, for example https://portal.example.com: https://, the host, and a port if it is not the default, with no path. Within 30 seconds a frame on that site may show your organization's transactions, and only those, to the reviewers the next points describe. A frame already open stays as it is until it reloads.
  • The administrator may allow sites for every organization, or turn off the lists organizations add themselves. On a self-hosted deployment that is da admin embed (System Administration); when they are off, Organization Settings shows your list read-only.
  • The frame signs no one in. A frame opened with embed=1 never shows a sign-in form. Opened at the address above, it shows the review screen to a reviewer already signed in to DocAI Fabric on the same site as your product (for example portal.example.com and docai.example.com), with what their role allows, and to anyone else a card that asks them to open the review again from your product. For people who have no account, or a frame on another site (every frame on our cloud), your backend requests a review link.
  • A frame inside another site's frame is refused. The browser checks every page around the frame, and only your site is on the list.

Try it in the UI​

On the Agents & API page, the Embedded review tab lists the transactions of the current project that wait for review, in Production or in the Playground, shows one in a frame as your users would see it, shows the status your backend would read and each message the frame sends the page, offers the next waiting transaction once you decide, gives the frame's code with the listener, and lists your organization's sites. Its frame is on DocAI Fabric's own address, which is always allowed, so it tells you nothing about your own site's settings.

Next steps​