Inspect and Restore Workflow History¶
Paginate candidate history within a workflow authoring conversation and restore a selected compiled candidate as a new proposal for review.
Task flow¶
Pass the conversation context ID (
WORKFLOW_CONTEXT_ID) from the authoring task and paginate candidate history by authoring task.Select a compiled candidate (
okis true) from the returned entries and record its source task ID and source artifact ID.Submit a restoration request with a unique request identifier (
RESTORE_REQUEST_ID) to obtain a new artifact ID, proposal ID, and reset test state.Review and retest the restored proposal in the original conversation before accepting and publishing it.
Prerequisites¶
Complete the endpoint, personal access token, and workspace setup in Use the SDK.
Conversation context ID (
WORKFLOW_CONTEXT_ID): retain the conversation context ID from the original workflow authoring task; history queries aggregate candidates by authoring conversation, whereas workflow IDs, standalone conversation record IDs, and execution IDs identify different resources.Restoration request ID (
RESTORE_REQUEST_ID): generate and save a unique idempotency identifier before calling restore; keep the same identifier and source selection when retrying after an uncertain network outcome, and generate a new identifier when selecting a different source candidate.
Read history with task-based pagination¶
The example below reads up to 10 pages, requesting 20 authoring tasks per page. A single authoring task may produce multiple candidate entries or zero visible entries; advance pagination using the returned task total (total_tasks) and page size (limit), stopping once the offset reaches or exceeds total_tasks.
import os
import moi_product_sdk as sdk
client = sdk.new_with_personal_access_token(
os.environ["PRODUCT_API_BASE_URL"], os.environ["PRODUCT_API_KEY"]
)
workflows = client.workspace(os.environ["WORKSPACE_ID"]).workflows()
context_id = os.environ["WORKFLOW_CONTEXT_ID"]
entries = []
offset = 0
for _ in range(10):
page = workflows.history(context_id, 20, offset)
entries.extend(page.items)
for entry in page.items:
print(entry.candidate_ref.task_id, entry.candidate_ref.artifact_id,
entry.status, entry.candidate.test_status, entry.created_at)
offset += page.limit
if offset >= page.total_tasks:
break
if page.limit <= 0:
raise RuntimeError("Invalid task pagination")
else:
raise RuntimeError("History page budget reached; continue at the returned task offset")
print("Candidate entries:", len(entries), "Task offset:", offset)
package main
import (
"context"
"fmt"
"os"
sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)
func main() {
ctx := context.Background()
client, err := sdk.NewWithPersonalAccessToken(
os.Getenv("PRODUCT_API_BASE_URL"),
os.Getenv("PRODUCT_API_KEY"),
)
if err != nil {
panic(err)
}
defer client.Close()
workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
if err != nil {
panic(err)
}
workflows := workspace.Workflows()
contextID := os.Getenv("WORKFLOW_CONTEXT_ID")
var entries []*sdk.WorkflowHistoryEntry
offset, complete := 0, false
for pageIndex := 0; pageIndex < 10; pageIndex++ {
page, err := workflows.History(ctx, contextID, 20, offset)
if err != nil {
panic(err)
}
entries = append(entries, page.GetItems()...)
for _, entry := range page.GetItems() {
fmt.Println(entry.GetCandidateRef().GetTaskId(), entry.GetCandidateRef().GetArtifactId(),
entry.GetStatus(), entry.GetCandidate().GetTestStatus(), entry.GetCreatedAt())
}
offset += int(page.GetLimit())
if offset >= int(page.GetTotalTasks()) {
complete = true
break
}
if page.GetLimit() <= 0 {
panic("Invalid task pagination")
}
}
if !complete {
panic("History page budget reached; continue at the returned task offset")
}
fmt.Println("Candidate entries:", len(entries), "Task offset:", offset)
}
Restore a selected historical candidate¶
Select a compiled candidate from the history entries collected above (uncompiled source snapshots cannot be restored) and pass its source task ID (RESTORE_TASK_ID) and source artifact ID (RESTORE_ARTIFACT_ID). Restoration creates a new pending proposal under the source task and returns a new artifact_id, a new confirmation proposal ID, and a reset test status; subsequent testing and acceptance must use the newly returned artifact_id and proposal ID.
source_task = os.environ["RESTORE_TASK_ID"]
source_artifact = os.environ["RESTORE_ARTIFACT_ID"]
selected = next((entry for entry in entries
if entry.candidate_ref.task_id == source_task
and entry.candidate_ref.artifact_id == source_artifact
and entry.candidate.ok), None)
if selected is None:
raise RuntimeError("Choose a compiled candidate from the history page")
restored = workflows.restore_history(sdk.WorkflowHistoryRestoreRequest(
context_id=context_id, request_id=os.environ["RESTORE_REQUEST_ID"],
candidate_ref=sdk.WorkflowCandidateRef(source_task, source_artifact),
))
print("Restored reference:", restored.candidate_ref.task_id, restored.candidate_ref.artifact_id)
print("Proposal:", restored.candidate.proposal_id, "State:", restored.status,
"Tests:", restored.candidate.test_status)
sourceTask, sourceArtifact := os.Getenv("RESTORE_TASK_ID"), os.Getenv("RESTORE_ARTIFACT_ID")
found := false
for _, entry := range entries {
if entry.GetCandidateRef().GetTaskId() == sourceTask &&
entry.GetCandidateRef().GetArtifactId() == sourceArtifact &&
entry.GetCandidate().GetOk() {
found = true
}
}
if !found {
panic("Choose a compiled candidate from the history page")
}
restored, err := workflows.RestoreHistory(ctx, sdk.WorkflowHistoryRestoreRequest{
ContextID: contextID,
RequestID: os.Getenv("RESTORE_REQUEST_ID"),
CandidateRef: sdk.WorkflowCandidateRef{TaskID: sourceTask, ArtifactID: sourceArtifact},
})
if err != nil {
panic(err)
}
fmt.Println("Restored reference:", restored.GetCandidateRef().GetTaskId(), restored.GetCandidateRef().GetArtifactId())
fmt.Println("Proposal:", restored.GetCandidate().GetProposalId(), "State:", restored.GetStatus(), "Tests:", restored.GetCandidate().GetTestStatus())
Restoration leaves the source candidate unchanged and does not automatically accept, publish, or overwrite the saved live workflow. The restored proposal starts with a fresh test state; review its configuration, rerun tests, and obtain approval in the original conversation before proceeding to Confirm and Publish Workflow Proposals. Inspect current and saved_workflow separately when reading history responses (either field may be absent): an acceptance record indicates prior approval only, and a saved workflow version may predate that acceptance or originate from another conversation targeting the same workflow.