Palantir Action：送出成功，哪些東西改好了？

This article is also available in English: When a Palantir Action Succeeds, What Has Changed?

Assign Employee 是 Palantir 官方文件舉的 action type 範例。它綁了四樣東西：

• 讓使用者輸入新角色的參數。
• 自動把員工與新主管建立關聯的規則。
• 通知新舊主管異動的副作用。
• 限定只有人資才能操作的送出條件。

人資按下送出之後，改角色、建關聯、發通知，算是一起完成嗎？如果這個 action 另外接了一個寫回外部系統的 webhook，其中一步出錯，其他步驟會跟著回復嗎？

官方文件對 action 的定義只有一句：

An action is a single transaction that changes the properties of one or more objects, based on a user-defined logic.

一個 action 是一筆交易。這句話可以被讀成「整包一起成功、一起失敗」。文件列出的機制，給的保證要窄得多。

本文認為，action type 的價值在前一半：把一次送出的條件和效果，寫進同一個定義。後一半有邊界。外部的副作用，不一定和物件修改一起成功，也不一定能一起撤銷。

這篇接續系列第一篇。第一篇看 Ontology 怎麼把資料、邏輯、動作與權限接在一起。這篇只跟著一次 Assign Employee 的送出走：送出前要過什麼，送出後寫到哪，出錯時怎樣，事後查得到什麼。

送出之前：誰能送，條件是什麼

action-types overview 頁說，action type 是使用者一次可以對物件、屬性值、關聯做的一組變更或編輯的定義，也包含送出時觸發的副作用。Assign Employee 的四樣東西，各對應定義裡的一個部分。參數是輸入，規則決定改什麼。送出條件決定送不送得出去，副作用讓資料送出 Foundry。規則描述不了的時候，可以改用 function 驅動整個邏輯。官方也強調，同一套 action 邏輯與驗證，能跨所有使用者應用一致地使用。

人資要送得出去，先要看得到。送出者必須看得到被編輯的 object type、link type 與它們的資料源，並通過 submission criteria（permissions 頁）。

submission criteria 能拿參數值的組合來判斷，把業務邏輯編碼進編輯權限裡。「只有人資才能操作」就是這一類條件。

另外有一個選用的 API 預檢：Validate Action。它回答「這組參數能不能跑這個 action」，回應裡有參數與 submission criteria 的評估結果。它有明講的限制（Validate Action API 頁）：

For performance reasons, validations will not consider existing objects or other data in Foundry.

主鍵是否重複、使用者 ID 是否存在這類要查現有資料才知道的事，預檢不會檢查。

所以預檢通過，不等於真的送出會成功。它是個可以呼叫的檢查端點，不是每次送出都要走的一關。實際送出時，仍要通過權限檢查和 submission criteria。

送出之後：新角色寫到哪

使用者對 Ontology 物件做的編輯，不會寫進物件類型背後的 backing dataset。要讓下游的 Foundry pipeline 讀到「資料源加編輯」的最新狀態，可以另外設定 materialization，把這個狀態物化成一份獨立的資料集。在 Object Storage v2 下，這是可選項。

官方文件對留存範圍講得很明白（materializations 頁）：只保證最新一版可用。原文是 “only the latest snapshot is guaranteed to be available”。

Object Storage v2 不保證保留歷史快照；需要保留時，得自己再接一個 transform。

寫到外部系統是另一條路，走 webhook。兩件事不要混在一起：編輯進 Ontology，webhook 改外部。

通知與外部系統：兩種 webhook，失敗的方向不同

side effects 分兩類：notification 與 webhook。Assign Employee 通知新舊主管，用的是前一類。notification 的內容，讀的是編輯套用之前的 Ontology 狀態，收件人看不到的資料不會進通知。如果預設要求全部收件人都有權限，而有人沒有，官方的說法是資料不改、通知也不發。

Webhook 才是真正寫到外部系統的地方，而且有兩種模式：

先看 writeback。它在物件變更之前執行，失敗就顯示給使用者，其他變更都不會發生。官方的說法是：

This behavior enables some degree of transactionality between Foundry and the external system.

只到「某種程度」。文件接著寫明：外部請求失敗，Foundry 一定不會改；但外部請求成功、Ontology 的變更卻失敗，仍然可能發生。這時外部系統已經改了，Ontology 這邊沒改成。文件另外說，writeback webhook 一失敗，整個 action 就停止套用。所以一個 action 只能設一個 writeback webhook。

再看 side effect。新加的 webhook 預設就是這個模式（set-up-a-webhook 頁）。它在物件改完之後才跑，失敗不會顯示給使用者，使用者甚至可能已經看到成功訊息，外部那一步才執行。一個 action 可以設多個，順序不保證。

出錯想撤回：revert 撤得掉什麼

action revert 常被想像成「整包撤銷」。官方文件寫得很清楚（action-reverts 頁）：

An action revert only reverts the edits to the object instance, but it will not revert side effects, such as notifications or webhooks, nor will it call them in the same way that the applied action would have.

這有三層限定：

• revert 只還原物件上的編輯。通知與 webhook 不會被撤銷，也不會用原來的方式重新呼叫。
• 物件在這之後只要又被別的編輯動過，即使動的是不同屬性，這個 action 就不能再 revert。
• revert 只支援 Object Storage v2。

放回 Assign Employee：就算物件編輯被 revert，新舊主管已經收到的通知，也不會因此收回。外部系統已經被 writeback 或 side effect 改過的部分，revert 也不會處理。

事後查帳：action log 記什麼，不記什麼

action log 是 action type 上可以配置的紀錄。配置之後，每次成功送出會多一筆紀錄，記下送出者的 Multipass 使用者 ID、時間戳，以及被改動物件的主鍵。官方文件對被改動的物件有一條明確的限制（action-log 頁）：

Note that storing properties of edited objects other than the primary key is not supported.

被編輯物件除了主鍵以外的屬性值，不在支援範圍內。

這不代表稽核只留得住主鍵。log 還可以另選存 summary、參數值，以及未被編輯物件的屬性。但這些都不等於被編輯屬性的「改前改後」。想看某個物件逐筆的編輯歷史，要靠另一個功能：user edit history。官方寫明，開啟之前發生的變更不會被追溯（user-edit-history 頁）。原文是：

Any changes prior to the activation of this feature will not be tracked.

不是人按的送出：回 200、自動觸發，也不等於做完

API 端有一個容易被忽略的細節：回 200，只代表伺服器收到並處理了請求，不代表 action 成功（Apply Action API 頁）。要看回應內容裡的 validation 結果。

Automate 的 action effect，會在條件觸發時自動跑 action，以 automation owner 的身分執行（action-effects 頁）。submission criteria 對 owner 驗。edit history 與 audit logs 也記 owner。owner 可以是第三方應用的服務帳號。

它的效果是 at-least-once，不是 exactly-once（effect-settings 頁）。同一個效果可能重複執行，官方建議把操作設計成冪等。

判讀：綁在同一個定義裡，不等於一起成敗

一次送出的條件和效果，掛在同一個 action type 定義上：送出條件、物件編輯、通知、webhook，還有配置好的 action log。這是 action type 的價值。

但前面幾節已經畫出邊界。在 writeback 模式下，外部系統成功了，Ontology 仍可能失敗。使用者看到成功時，side effect 可能還沒跑。revert 只管物件編輯。所以不能把一次送出讀成跨系統的全成或全敗。

單一功能在別處也找得到，Looker 的 Action Hub 就有寫回外部系統的功能。Palantir 把這幾件事放進同一個 action type 定義。本文沒有逐項實測別家產品，也不能由此判斷其他平台能不能做到同樣的整合。

所以，評估任何一套「表單送出」機制，可以問三件事。外部系統是在物件修改之前還是之後被呼叫？失敗時，哪些變更會被擋下，哪些會留在外面？事後能查到哪一種紀錄？

本系列下一篇：沒有 Palantir：一頁契約、一支測試、一份核准清單，各做到了 Ontology 的哪一格。

常見問題

Palantir 的 Action 送出後，資料會寫回原始資料集嗎？

不會。使用者編輯不會寫回物件類型背後的 backing dataset。要讓下游讀到「資料源加編輯」的最新狀態，可以另外設定 materialization；在 Object Storage v2 下，只保證最新一版可用。寫到外部系統走另一條路，是 webhook。

Action 的 webhook 失敗，會發生什麼事？

看模式。Writeback 模式的 webhook 在物件變更之前執行，失敗就不會有其他變更；但外部請求成功、Ontology 的變更仍可能失敗。Side effect 模式的 webhook 在物件改完之後才執行，失敗不會顯示給使用者，可能在使用者看到成功訊息之後才執行。

Action 可以 revert 嗎？會把整個 action 撤銷嗎？

revert 只還原物件實例上的編輯，不撤銷通知、webhook 等副作用，也不會用原來的方式重新呼叫它們。物件之後有任何其他編輯，即使是不同屬性，也不能再 revert；revert 只支援 Object Storage v2。

範圍與版本

• 本文引用的 Palantir 文件頁，都是 2026 年 8 月查閱的版本。Palantir 的文件頁面不標日期，所以不能用日後讀到的頁面，反推 8 月當時的內容。
• 引文後括號裡的頁名，是該句在 Palantir 文件中的出處。
• 2026 年 10 月 16 日的修訂，調整了結構與限定的寫法，沒有更新資料。