Every tool TaskTrain offers an MCP Client, such as Claude or ChatGPT: what each does, the Grant Scope it needs, and its inputs. A connected Client reads all of this itself; this page is for deciding what to authorize, and which Grant Scopes to give an Agent.
43 tools: 15 read-only and 28 that write. A User's Client is listed all of them; an Agent is listed 23 by default. This reference is current as of TaskTrain 4.5.0. Tools may change between releases.
Tool annotations
- Read-only
readOnlyHint: changes nothing. - Writes
readOnlyHint: false: changes data. - Destructive
destructiveHint: may delete or replace data. - Idempotent
idempotentHint: repeating the same call changes nothing further. openWorldHintisfalseon every tool, because each one acts only inside TaskTrain.
Who is offered which tools
- A User's Client is listed every tool. A call beyond its Grant Scopes is challenged with
insufficient_scope, so the Client may ask the User for more. - An Agent is listed only the tools its Grant Scopes reach.
account:read,portfolio:write,procedure:writeandlibrary:writeare never available to an Agent, which works Assignments and only reads Procedures, andassignment:writeis off until its Administrator turns it on. procedure:publishis opt-in for a User and never available to an Agent. It allows changes to a Published Procedure.
Calls and answers
- A User or an Agent may make 120 calls a minute. MCP is a Paid Plan feature.
- A paged list reads 25 items unless the call names a
limit. A full page also answersnextCursor. - A refused call is an error result whose structured content holds
code,statusCode,reason,entityId,fieldErrorListandunmetCriterionList.
Grant Scope organization:read
AccountRead
An Account by its accountId: yours or another member's, such as an Assignee or Requestor named elsewhere. With organizationId instead, your own Account in that Organization; name one, not both. A User finds an organizationId with UserReadOrganizationList. An Agent, which acts in one Organization, may name neither: this answers its own Account, and so its Organization's _id. It answers the Account's Organization, with the time zone its day falls in (UTC when timeZone is null), whether a Human or an Agent holds it, and an Agent's kind and Grant Scopes. Another member's emailAddress reads null to an Agent.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: organization:read. Organization found from: organizationId, accountId.
| Input | Type | Required | Description |
|---|---|---|---|
accountId | string | No | The Account, by its _id: the caller's own or another member's, in an Organization the caller belongs to; give this or organizationId, not both |
organizationId | string | No | The Organization to read the caller's own Account in; give this or accountId, not both |
AccountReadActivityList
An Agent's Activity, newest first, by the Agent's accountId: each change it made in its Organization, the Client it came through, and the Assignment and task, or Procedure and step, it was made to, then each other task a status change moved. An Agent reads its own, and an Administrator of its Organization any Agent's; a Human's Account answers activityList: null. It lists only the Agent's own changes: what others changed on its tasks, a Return among them, is in that Assignment's Activity (AssignmentReadActivityExport). An entry's subjectList names each record as it reads now, not as it read then, so a renamed one reads its later name on earlier entries, and a step deleted since reads the name it had when deleted: the entry for its deletion, newer, names the same _id. Only a description keeps a name it was written with, such as a task's in a status change; one for a wait on a step deleted since says the step was deleted, without its name. An entry's typeName is the operation that made the change, so a value changed by capturing it again reads FieldValueCreate. Times are UTC; to list one day, convert its start from the Organization's time zone (AccountRead gives it) and page until dateTime is earlier. Pages with pagination.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: organization:read. Organization found from: accountId.
| Input | Type | Required | Description |
|---|---|---|---|
accountId | string | Yes | The Agent whose Activity to read, by its Account's _id: your own, or, as an Administrator of its Organization, any of its Agents' |
pagination | object | No | One page of the list: limit items after the one whose _id is after, in the list's order. A call naming no limit reads 25. An answer with more to come carries nextCursor, the next call's after; one without it is the last page. Pass only a nextCursor an answer gave: any other _id is not refused, and may answer the start of the list or an empty page. |
pagination.limit | integer | No | How many items the page holds, at least one Default: 25 |
pagination.after | string | No | The _id of the last item of the page before; absent for the first page |
AccountReadAssignmentList
Your Assignments in an Organization, newest assigned first: those you are the Assignee or Requestor of, or hold or approve a task of. assignmentStatusList picks them by the Assignment's own status, every open one unless named. An Assignment never reads PendingApproval: while an Approval task awaits its approver, its Assignment reads InProgress, so AccountReadAssignmentTaskList is where to find what awaits approval. An Assignment can read Completed over a task Rejected, which counts as closed, and over its Exit Criteria unmet, which never refuse a Skip: progress counts its Rejected tasks in rejectedCountTotal, and exitCriterionStateList gives isMet: false for each Exit Criterion or Required Output unmet, null for one in prose. startedBy says what started each, and sourceAssignment the Assignment a Hand-off Trigger started it from, null where you may not read that one, so two a Trigger named alike are told apart. Pages with pagination.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: organization:read. Organization found from: organizationId.
| Input | Type | Required | Description |
|---|---|---|---|
organizationId | string | Yes | The Organization whose Assignments to list |
assignmentStatusList | string[] | No | Which Assignments to list, by each Assignment's own status, which follows its tasks' statuses One of: NotStarted, InProgress, Skipped, OnHold, PendingApproval, Completed, Approved, RejectedDefault: ["NotStarted","InProgress","OnHold"] |
pagination | object | No | One page of the list: limit items after the one whose _id is after, in the list's order. A call naming no limit reads 25. An answer with more to come carries nextCursor, the next call's after; one without it is the last page. Pass only a nextCursor an answer gave: any other _id is not refused, and may answer the start of the list or an empty page. |
pagination.limit | integer | No | How many items the page holds, at least one Default: 25 |
pagination.after | string | No | The _id of the last item of the page before; absent for the first page |
AccountReadAssignmentTaskList
Your tasks in an Organization, across its Assignments or, with assignmentId, on one, in the order they were created, which need not be the order of the work: AssignmentRead gives that, and a task's criteria hold what must wait. Each comes with its Assignment, the parentAssignmentTask it is a sub-task of (null on a top-level task; AssignmentTaskRead names it), whether it is Ready, every criterion it is held to with whether each is met, the Fields it binds, as its Assignment froze them when it started, and the values captured. assignmentTaskStatusList picks the statuses, NotStarted, InProgress, OnHold and Rejected unless named. Naming PendingApproval also lists what awaits your approval, whose approverAccount is you, for you to decide signed in to TaskTrain, where it is in your Assignment Inbox. A task submitted with no approver found awaits no one's approval here, though its Assignee finds it among their own tasks: its comment thread names the Portfolio's Human Administrators and Leads who may decide it, each of whom is emailed and finds it in their Comments Inbox in TaskTrain. A task is Ready (isReady) when it is Not Started and every Entry Criterion is met, so you may start it; a task with sub-tasks is Ready when one beneath it is, since starting it starts only those; a started task reads isReady: false. A task may close when no entry of its entryCriterionStateList or exitCriterionStateList reads isMet: false, and the last open task of an Assignment, or the approval that would complete it, when none of the Assignment's own does, which AssignmentRead gives, though an Approval task is submitted whatever they read; a prose criterion reads isMet: null, is judged by whoever works the task, and never holds a close. A Required Input the task's step binds reads in both lists, and a Required boundary Input only in entryCriterionStateList, where one the task's step binds as a Required Input too reads twice; each holds the task's start and its close, a started task's too, as every unmet Entry Criterion does. An Approval task a person returned or reopened for revision reads In Progress, and one they rejected reads Rejected until they reopen it: AssignmentTaskRead tells these apart and gives the note. Pages with pagination.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: organization:read. Organization found from: organizationId.
| Input | Type | Required | Description |
|---|---|---|---|
organizationId | string | Yes | The Organization whose tasks to list |
assignmentTaskStatusList | string[] | No | The statuses of the tasks to list One of: NotStarted, InProgress, Skipped, OnHold, PendingApproval, Completed, Approved, RejectedDefault: ["NotStarted","InProgress","OnHold","Rejected"] |
assignmentId | string | No | The Assignment whose tasks to list; absent lists them across every Assignment |
pagination | object | No | One page of the list: limit items after the one whose _id is after, in the list's order. A call naming no limit reads 25. An answer with more to come carries nextCursor, the next call's after; one without it is the last page. Pass only a nextCursor an answer gave: any other _id is not refused, and may answer the start of the list or an empty page. |
pagination.limit | integer | No | How many items the page holds, at least one Default: 25 |
pagination.after | string | No | The _id of the last item of the page before; absent for the first page |
AccountReadCommentThreadList
Your Comments Inbox in an Organization: each comment thread you follow that holds a comment you have not read, newest first by the last comment added, changed or removed, so a reply to you leads, with its Assignment, its task when it is on one, and its comments, unreadChildIdList naming those you have not read. You follow every thread on an Assignment you request or are the Assignee of, or of which you work or approve a task, and one a comment mentions you in. A thread joins your Inbox when it starts, and a comment someone else adds marks it unread again. Mark it read with AccountUpdateCommentThreadViewStatus once you have answered or acted on it; accountViewStatusList with Read lists those too. Answer a comment in its thread with CommentThreadCreateComment. Pages with pagination.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: organization:read. Organization found from: organizationId.
| Input | Type | Required | Description |
|---|---|---|---|
organizationId | string | Yes | The Organization whose Comments Inbox to read |
accountViewStatusList | string[] | No | Whether to list the threads holding a comment not yet read, those read, or both One of: Unread, Read, ArchivedDefault: ["Unread"] |
pagination | object | No | One page of the list: limit items after the one whose _id is after, in the list's order. A call naming no limit reads 25. An answer with more to come carries nextCursor, the next call's after; one without it is the last page. Pass only a nextCursor an answer gave: any other _id is not refused, and may answer the start of the list or an empty page. |
pagination.limit | integer | No | How many items the page holds, at least one Default: 25 |
pagination.after | string | No | The _id of the last item of the page before; absent for the first page |
AccountReadPortfolioList
The Portfolios of an Organization where you hold Portfolio Access, for an Agent as for a person: Active ones unless portfolioStatusList names others. Each holds the _id that PortfolioReadLibrary and ProcedureImport name it by, its name, description and status, and the Portfolio Access you hold. Pages with pagination.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: organization:read. Organization found from: organizationId.
| Input | Type | Required | Description |
|---|---|---|---|
organizationId | string | Yes | The Organization whose Portfolios to list |
portfolioStatusList | string[] | No | Which Portfolios to list, by status One of: Active, ArchivedDefault: ["Active"] |
pagination | object | No | One page of the list: limit items after the one whose _id is after, in the list's order. A call naming no limit reads 25. An answer with more to come carries nextCursor, the next call's after; one without it is the last page. Pass only a nextCursor an answer gave: any other _id is not refused, and may answer the start of the list or an empty page. |
pagination.limit | integer | No | How many items the page holds, at least one Default: 25 |
pagination.after | string | No | The _id of the last item of the page before; absent for the first page |
AccountReadProcedureList
The Procedures in the Portfolios of an Organization where you hold Portfolio Access, oldest first, for an Agent as for a person: Published ones unless procedureStatusList names others, such as Draft to find a Draft you or another author imported, readable with Associate Portfolio Access or more. A Participant of an Assignment may also read its Procedure with ProcedureRead, by the id the Assignment gives, though it is not listed here and its _callerAccess answers no portfolioAccess. searchTerm narrows the list to the Procedures holding every word of it, ignoring case, within a longer word too, so "9" finds "R9", each in any of a Procedure's name, objective, description, keywords, sectors, functions or step names. Each item holds its _id, name, objective, description, status, estimatedDuration and Portfolio, not its steps or Roles: read one with ProcedureRead before starting it with AssignmentCreate. Pages with pagination.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: organization:read. Organization found from: organizationId.
| Input | Type | Required | Description |
|---|---|---|---|
organizationId | string | Yes | The Organization whose Procedures to list |
searchTerm | string | No | Words to find, ignoring case, each in any of a Procedure's name, objective, description, keywords, sectors, functions or step names, within a longer word too; a Procedure holding every word is listed, and absent lists every one |
procedureStatusList | string[] | No | The statuses of the Procedures to list One of: Draft, Published, ArchivedDefault: ["Published"] |
pagination | object | No | One page of the list: limit items after the one whose _id is after, in the list's order. A call naming no limit reads 25. An answer with more to come carries nextCursor, the next call's after; one without it is the last page. Pass only a nextCursor an answer gave: any other _id is not refused, and may answer the start of the list or an empty page. |
pagination.limit | integer | No | How many items the page holds, at least one Default: 25 |
pagination.after | string | No | The _id of the last item of the page before; absent for the first page |
Grant Scope account:read
UserReadOrganizationList
The Organizations this Client may act in, and your Account in each: its _id is what an Assignee or Requestor names you by. Also the Grant Scopes this Client holds (_callerAccess.grantScopeList), which is how to tell whether you hold procedure:publish before changing a Published Procedure.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only, User only. Grant Scope: account:read. Names no Organization.
No inputs.
Grant Scope portfolio:read
PortfolioReadLibrary
What a Portfolio's Procedures may name by id: the Fields, Materials and Tools of its Library and its Organization's, and the Organization's Positions with the member who holds each. Read it before importing a Procedure into the Portfolio with ProcedureImport, binding an entry by its _id rather than writing a new one of the same name, or to find who may fill a Role. An entry an import creates goes in the Portfolio's Library; one of the Organization's is created only in TaskTrain, by a Workspace Administrator or Lead. Needs Portfolio Access to the Portfolio.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: portfolio:read. Organization found from: portfolioId.
| Input | Type | Required | Description |
|---|---|---|---|
portfolioId | string | Yes | The Portfolio to read |
Grant Scope portfolio:write
PortfolioCreate
Create a Portfolio in the Organization organizationId, to import Procedures into with ProcedureImport. Needs Lead or Administrator Workspace Access in the Organization, which AccountRead gives. You become its Portfolio Administrator, and no one else holds Portfolio Access to it until a person gives it in TaskTrain. Each call creates another Portfolio, even under a name one already has: before retrying a call that failed, look for the Portfolio with AccountReadPortfolioList. It answers the Portfolio with the _id that ProcedureImport and PortfolioReadLibrary name it by.
Annotations: Writes, User only. Grant Scope: portfolio:write. Organization found from: organizationId.
| Input | Type | Required | Description |
|---|---|---|---|
organizationId | string | Yes | The Organization to create it in |
name | string | Yes | Its name, 1 to 77 characters, not all of them blank; omitted, it starts unnamed |
description | string | No | Its description, plain text of up to 444 characters |
PortfolioUpdateDescriptors
Rename the Portfolio portfolioId, or rewrite its description or its detail (as HTML); an argument left out keeps what the Portfolio has, and a null or empty description or detail clears it. Needs Administrator Portfolio Access to the Portfolio, which its creator holds and AccountReadPortfolioList shows. It answers the Portfolio as it now reads.
Annotations: Writes, Idempotent, User only. Grant Scope: portfolio:write. Organization found from: portfolioId.
| Input | Type | Required | Description |
|---|---|---|---|
portfolioId | string | Yes | The Portfolio to change |
name | string | No | Its new name, 1 to 77 characters, not all of them blank; omitted keeps it, and null is refused |
description | string | null | No | Its new description, plain text of up to 444 characters; omitted keeps it, and null or empty clears it |
detail | string | null | No | Its new detail, as HTML, kept to the markup TaskTrain's rich-text editors make; omitted keeps it, and null or empty clears it |
Grant Scope procedure:read
ProcedureExport
A Procedure written out whole, steps included, in the format named: a Strands SOP to follow, a Claude Skill (the SOP's Markdown, named as a skill file), an MCP prompt, JSON or YAML, in content: a JSON document arrives as the object it holds, any other as its text. JSON and YAML may be edited and imported back with ProcedureImport, which takes the document as text and ignores what TaskTrain derives rather than reads: the Procedure's own id, status and revision time, Position titles and members, Tool interfaces, governance, the Triggers that start it, criterion statements, relationship labels, the derived lists of Tools and Materials, and a parent step's Fields, each marked as derived from the sub-step that binds it or, as an Input, tests it in a criterion though none produces it; an Input reads Required there where a sub-step every Assignment works tests it in an Exit Criterion, whatever the sub-step's own binding says. An export to an Agent leaves out each member's email address rather than reading it null. It answers the whole Procedure at once, with no paging, so long instructions can make it large: ProcedureRead reads the summary and lists the steps, ProcedureStepRead one step whole, and AssignmentTaskRead one task of an Assignment. Exporting needs Portfolio Access to the Procedure's Portfolio: a Participant of an Assignment without it reads the Procedure with ProcedureRead and ProcedureStepRead. An SOP, Skill or prompt numbers the steps in an order their waits allow, so none comes before a step it waits on or one producing a Field it tests: that order can differ from the Procedure's own, which ProcedureRead, JSON and YAML give and Activity counts positions by. An MCP prompt's arguments leave out a File Input, which a person attaches, though its text lists it. Where the exporter may read its Portfolio's Triggers, as a Guest or a Public Portfolio's reader may not, it names each Scheduled Trigger by when TaskTrain starts an Assignment and the Field values it gives, and each Manual Trigger by the condition a person starts one on; a Hand-off Trigger is the automatic relationship that carries it. Governance's Agent-assigned steps are those whose Role's default Position, or own Position, an Agent holds: a step whose own Role has no default Position is listed apart, as assigned to a Role filled at each start, an Agent or a person. A Published Procedure's SOP, Skill or prompt names no related Draft, such as a change proposed to it, which no one may start yet; JSON and YAML name every relationship.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: procedure:read. Organization found from: procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureId | string | Yes | The Procedure to export |
format | string | No | The format to write it in A format ProcedureExport writes a Procedure in.One of: StrandsSOP, ClaudeSkill, MCPPrompt, JSON, YAMLDefault: "StrandsSOP" |
ProcedureRead
A Procedure's summary, by its procedureId: its objective, description, detail (its overview, as HTML) and status, its boundary Fields, its own Exit Criteria, which hold every Assignment of it, each with the test its comparison sets, the Roles to staff when starting it with each Role's default Position, who an Assignment goes to when a start names no Assignee (defaultAssigneeRole, or else the member of defaultAssigneePosition; with neither, the start must name one), its relationships to other Procedures, each end with its status, since one may be a Draft that proposes a change and no one may start yet, and a Precedes one with the handOffTrigger that starts the later Procedure when an Assignment of the earlier completes meeting its own Exit Criteria with no Rejected task, which a person sets in TaskTrain: it names the Assignment it starts assignmentName, staffs its Roles as its roleFillList says, gives each Field in fieldValueList the same value every time, and carries across only the values its fieldMappingList maps, each from an Output of the earlier Procedure's own fieldBindingList, not a step's, to an Input of the later one's, so a value only a step captures, or one the earlier Procedure takes in as an Input, is carried once it binds the Field as an Output too, which a boundary may beside its Input; a Field it neither maps nor gives starts empty, so a step waiting on its value waits until it is captured, or a person Skips it; without one, a relationship starts nothing, so AssignmentCreate starts the later one, given its values again; the scheduledTriggerList that starts it on a repeating schedule, each every interval of its unit from dateTimeStart, with the name, staffing and Field values it gives each Assignment and why it last failed; its Resources, the Tools named on the Procedure itself in toolList (each step names its own, which ProcedureStepRead gives, and ProcedureExport gathers both), the Materials named on it in materialReferenceList, Input or Output, which steps name likewise, its keywords, sectors and functions, and its steps in order, three levels deep, each by the _id and name ProcedureStepRead takes to read it whole and the ProcedureStep tools take to change it, with the Role that works it (defaultAssigneeRole) and the Role that approves it (approverRole), which no Agent's Account may fill; ProcedureStepRead gives a Position named in place of either. A step's sub-steps beyond the third level, which an older Procedure may have, are read with ProcedureStepRead.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: procedure:read. Organization found from: procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureId | string | Yes | The Procedure to read |
ProcedureStepRead
One step of the Procedure procedureId, by the procedureStepId ProcedureRead lists, or a step's procedureStepList gives for each of its sub-steps. It reads the step whole: its instructions (detail, as HTML), who works it and who approves it, its Field bindings, Entry Criteria and Exit Criteria, each by the _id the ProcedureStep tools take to change or remove it, its Resources, Tools and Materials, and its direct sub-steps. A step with sub-steps binds no Field of its own: derivedFieldBindingList gives what its sub-steps take in and give out, and a step without sub-steps its own bindings: an Output is left out only when nothing but its sub-steps uses it, and an Input or Output reads as optional when only a sub-step that waits on a Field's value takes or produces it, since a person Skips that sub-step in an Assignment whose value does not call for it, and an Input reads Required where a sub-step every Assignment works tests it in an Exit Criterion, which no task closes without. A Field a sub-step only tests in a criterion is in that sub-step's criteria, not here, though ProcedureExport lists it among the parent's Inputs, Required where a sub-step every Assignment works tests it in an Exit Criterion; and toolList and materialReferenceList are the step's own, while ProcedureExport gathers its sub-steps' too. It reads the Procedure as it is now, whose status says whether a change to the step would change at once what new Assignments start from; an open Assignment's task keeps the copy of the step it started with, which AssignmentTaskRead reads. A Participant of an Assignment of the Procedure may read its steps, as ProcedureRead, without Portfolio Access, though not export it.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: procedure:read. Organization found from: procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureId | string | Yes | The Procedure the step belongs to |
procedureStepId | string | Yes | The step to read |
Grant Scope procedure:write
ProcedureImport
Import a Procedure document, the JSON or YAML ProcedureExport writes, edited or written anew, into the Portfolio portfolioId. Export one first to learn the shape: a document is {"tasktrain": {"formatVersion": …}, "procedure": {…}}, with the version an export gives, which is checked before any other rule, its boundary Fields in procedure.fieldList, its steps in procedure.procedureStepList, each with its sub-steps in a procedureStepList of its own and its criteria in entryCriterionList and exitCriterionList, and its keys are its own, which differ from the ProcedureStep tools' inputs: a fieldList entry names its Field by id, with direction and isRequired; a comparison its Field by fieldId, with operator and a comparand of {"kind": "Constant", "value": …}, {"kind": "Field", "fieldId": "…"} or {"kind": "RelativeDate", "offsetDayCount": …}; and an Entry Criterion of kind TaskStatus its step by targetStepId, with expectedTaskStatus, as one of kind FieldValue gives a comparison. This is the only tool that changes the Procedure's own name, criteria, boundary Fields and Roles. An entry naming an existing Field keeps that Field's name and choices, which warningList reports if the document gave others (FieldNameIgnored, FieldOptionListIgnored), and is refused if it gives another type: FieldDefinitionUpdate changes a Field's choices or type. Without procedureId it creates a Draft, a Procedure of its own that nothing ties to any other, so publishing it replaces nothing; with one it replaces that Procedure's content, keeping each step, Role and criterion whose id the document repeats and removing those it leaves out. A step or Role it keeps, and the Procedure itself, take only what the document gives them: a key left out of any is cleared, but for a Role's isRequired, so repeat each whole to keep it as it is; warningList counts the steps and Roles a document leaves out, and the steps it repeats with a key left out or empty, names each Role it so repeats, and names the keys (ContentRemoved). A document whose procedure.dateTimeRevised, which ProcedureExport writes, is earlier than the Procedure's last change undoes any change made since that it does not hold, which warningList says (DocumentOutOfDate) unless the import changes nothing: read changeList, and where a change is not your edit, export the Procedure again and edit that; one without it, such as one written by hand, is warned the same, as nothing tells which changes it holds. Replacing a Published Procedure needs the procedure:publish Grant Scope, and a dry run is refused without it; an Archived one is replaced only once a person unarchives it, signed in to TaskTrain, which makes it a Draft; a User's Client finds whether it holds it in UserReadOrganizationList. An entry named by a key of the document's own, such as a new step's "id": "sanctions-check", is created: a step or Role the Procedure holds, given under such a key, is created anew and the held one removed, and a Material, Tool or Resource so given is created beside any of its name, never matched to it, as its name, unlike a Field's, need not be unique, each of which warningList says. Steps nest at most three levels deep, and every authoring rule is checked before anything is written. It dry-runs unless isDryRun is false: read changeList and warningList, fix what they report, then import; a warning about a step names it in procedureStepId; a dry run's ids for new entries are provisional, and its warnings read as done though nothing was written. A Changed entry names the fields that differ (changedFieldList), by the names ProcedureStepRead gives them, so a step's Tools read toolList, a Created Procedure, step or Role those it sets, such as its approver and Materials, and each criterion and Field binding created, changed or removed is listed with the Procedure or step it is on (parentEntityId), as each sub-step is with the step it is under; a list of a step's Field bindings or criteria its changedFieldList names with no such entry listed beneath it holds the same entries in another order. A roleList entry gives an id, a name, an optional description, isRequired, which a new Role takes as true when it is left out and a Role the Procedure holds keeps, and an optional defaultPosition as {"id": "…"}; the Procedure's own Exit Criteria are in procedure.exitCriterionList, each a description, a comparison or both, as a step's are. A step's approver is approverRole, by the id of a roleList entry, or approverPosition, each an object: {"id": "…"}. A reference in another shape, or any other key that reads as an approver or a sign-off, refuses the document, which reports every rule it breaks; any other key it does not know is ignored, and warningList names it. A step naming both keeps approverRole, and warningList names the other. An approverPosition whose id is no Position of this Organization, which PortfolioReadLibrary lists, becomes a Required Role named by its title, or "Approver" with none, that every Assignment must staff, and warningList says so. An Account's _id, which PortfolioReadLibrary lists beside its Position's, given as an approverPosition refuses the document, and given as a defaultAssigneePosition or a Role's defaultPosition is left out, which warningList says, each naming the Position whose _id to give instead. A task submitted while its approver Position is vacant or its approver Role unfilled goes to the Portfolio's Human Administrators and Leads, who are named in its comment thread and emailed, and any of whom may decide it, signed in to TaskTrain. On the Procedure or a step, defaultAssigneePosition or defaultAssigneeRole, each an object with an id, names who works it: a key an export writes only when set. A new Field gives, in the fieldList entry that binds it, an id of the document's own, a name of 1 to 33 letters and digits, with no space, starting with a lowercase letter, an optional label, the words a form shows, and a type of Text, Number, Date, Boolean, Select, MultiSelect or File, Text when absent, and a Select or MultiSelect its choices in optionList, or it is refused. A new Field, Material, Tool or Resource is created in the Portfolio's Library: an Organization Library entry is created only in TaskTrain, by a Workspace Administrator or Lead, and a document binds one by its _id. An existing Select or MultiSelect with no options may be bound only as optional: bound as Required, it refuses the document; bound as optional, it is imported and warningList names it. An export's toolList, supplyList and deliverableList are derived: author a Tool in toolReferenceList, as {"id": "…", "name": "…"}, a Material in materialReferenceList, as {"material": {"id": "…", "name": "…"}, "direction": "Input"}, each by its id alone when PortfolioReadLibrary lists it; a step taking a Material as an Input uses it up, so it is no Deliverable after that step, which warningList says where the document lists it in deliverableList, unless that step gives it as an Output too, as one that reads or revises it without using it up does, or the Procedure's own materialReferenceList gives it as an Output. A Resource goes in resourceList, by its id alone when the Portfolio holds it, as ProcedureRead and ProcedureStepRead give it, or, when it is new, as {"id": "…", "name": "…", "type": "Linked", "payload": "<URL>"}, or with a type of Embedded and HTML as its payload; one of type Attached, a file, is not attached, and becomes a link that warningList names, and any other type is refused. The Procedure's own objective, description and detail, its estimatedDuration, in words such as "2 hours", and its categorizationList (sectorList, functionList and keywordList) are imported as the document gives them. A new Field bound in several places is created once: give its name, type and optionList in any fieldList entry binding it, and its id alone in the others; a new Material, Tool or Resource named in several places gives its name, or a Resource its payload, in any one of them and its id alone in the others. A parent step binds no Field of its own: warningList names each its fieldList gives, which is left out, so bind it on a sub-step, or a comparison testing it is refused; and a comparison in its Exit Criteria is refused, since it closes with its last sub-step. A relationshipList entry relates the Procedure to the one its procedureId names, by a type of Precedes, Alternative or SeeAlso, with an optional description: the Procedure imported is the one that Precedes, so to say that one Procedure comes before another, put the entry in the earlier one's document, naming the later, and changeList names a relationship by its type and the Procedure it names, as Precedes "…"; a relationship the document leaves out is removed, which warningList says (ContentRemoved), unless a Hand-off Trigger fires on it, which keeps it (RelationshipKept) until a person deletes the Trigger in TaskTrain; and an entry with no valid type is left out and named in warningList, as is one an export marks isInbound, another Procedure's relationship to the one exported, unless the import is onto that Procedure, so only that Procedure's document removes it, and leaving it out of this one changes nothing; one relating it to a Procedure it relates to already, by the same type, keeps that relationship, with or without its id; a Draft proposing a change to a Published Procedure relates to it by SeeAlso, saying what it changes, and warningList notes a Procedure of the same name it relates to nothing. A Hand-off Trigger, which a person sets in TaskTrain to start the later Procedure when an Assignment of the earlier completes, is not imported, and a relationship starts nothing by itself. A Precedes loop, two Procedures each preceding the other, is accepted, as a recurring cycle is one; only Hand-off Triggers refuse a loop. A document's status is not applied. warningList also lints each step's detail and the Procedure's description and detail for RFC 2119 wording (LintWarning, LintInfo): advice, which changes nothing and may be left. Needs Lead or Administrator Portfolio Access to the Portfolio. A person publishes a Draft.
Annotations: Writes, Destructive, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: portfolioId, procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
portfolioId | string | Yes | The Portfolio the Procedure is, or will be, in |
content | string | Yes | The document's text |
format | string | No | The document's format A format ProcedureImport reads: one ProcedureExport writes the whole Procedure in.One of: JSON, YAMLDefault: "JSON" |
procedureId | string | No | The Procedure whose content the document replaces; omitted to create a new Draft |
isDryRun | boolean | No | Whether to report what the import would do and write nothing Default: true |
ProcedureStepAddEntryCriterion
Make the step procedureStepId wait before its task may start: kind TaskStatus waits for the task of targetProcedureStepId to reach expectedTaskStatus or go past it, so a wait for InProgress stays met once its target closes, though not once it is Skipped, and a wait for Skipped is met by Skipped alone; FieldValue waits for a comparison of a Field bound in the same Procedure to pass, which a Field with no value never does, whatever the operator. Each kind refuses the other's keys. A TaskStatus wait, unless for InProgress, is also unmet while a task beneath its target is Rejected. A wait no Assignment could meet is refused, as is one for PendingApproval, Approved or Rejected on a step with no approver, which only ProcedureImport sets. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
kind | string | Yes | TaskStatus waits for another step's task to reach a status; FieldValue waits for a Field's value to pass a test An Entry Criterion kind an author adds to a step: not RequiredField, which a Required Input binding implies TaskStatus: Waits until a target task of the same Assignment has reached an expected statusFieldValue: Waits until a Comparison is satisfied |
targetProcedureStepId | string | No | TaskStatus: the step waited on |
expectedTaskStatus | string | No | TaskStatus: In Progress, Pending Approval, Completed, Approved or Skipped The statuses a TaskStatus Entry Criterion may wait for: Pending Approval and Approved only on an Approval step's task InProgress: Work has begunPendingApproval: Submitted, awaiting its ApproverCompleted: The work is doneApproved: Its Approver signed it offSkipped: Closed without the work being done |
comparison | object | No | FieldValue: the test waited on |
comparison.fieldDefinitionId | string | Yes | The Field tested, bound in the same Procedure |
comparison.operator | string | Yes | How it is tested: an operator the Field's type offers How a Comparison tests its Field's value against its comparand, which is one value of the Field's type unless the member says otherwise. Number and Date order; Text compares exactly; Select, MultiSelect and Boolean test membership or truth. A Field with no value fails every test, NotEqual and DoesNotInclude included.IsOneOf: Compares with a list of the Field's optionsIncludesAnyOf: Compares a MultiSelect with a list of its options, met when it holds at least one of themIsTrue: Takes no comparandIsFalse: Takes no comparand |
comparison.comparand | object | No | Omitted for IsTrue and IsFalse |
comparison.comparand.kind | string | Yes | Which of the fields below gives what the Field is compared with: Constant a value, Field another Field, RelativeDate a date relative to today What a Comparison's Field is compared with. One of: Constant, Field, RelativeDate |
comparison.comparand.value | string or number or boolean or array | No | Constant: a value of the Field's type, or for IsOneOf a list of its options. A Date's is an ISO 8601 date; a date-time is stored as the date it is written with |
comparison.comparand.fieldDefinitionId | string | No | Field: another Field of the same type, bound in the same Procedure |
comparison.comparand.offsetDayCount | integer | No | RelativeDate: days after today, or before it when negative, today being the date in the Organization's timeZone, or in UTC while it has none |
description | string | No | What the wait is for, in words |
ProcedureStepAddExitCriterion
Add an Exit Criterion to the step procedureStepId: what must hold before its task closes. One with a description alone is prose, judged by whoever works the task; a comparison tests a Field bound in the same Procedure and holds the task until it passes, which a Field with no value never does, whatever the operator, so the task's close needs a value: a parent step's derived Inputs and ProcedureExport read the Field Required, though the step's own binding, whose Required also holds the task's start, keeps what it was given. A step with sub-steps takes no comparison: put it on a leaf sub-step, or on the Procedure itself, whose own criteria, boundary Fields, Roles and name only ProcedureImport changes. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
description | string | No | What a person checks; required without a comparison, optional with one, which then states the criterion |
comparison | object | No | The test the Assignment's values must satisfy before the step's task closes; omitted for prose |
comparison.fieldDefinitionId | string | Yes | The Field tested, bound in the same Procedure |
comparison.operator | string | Yes | How it is tested: an operator the Field's type offers How a Comparison tests its Field's value against its comparand, which is one value of the Field's type unless the member says otherwise. Number and Date order; Text compares exactly; Select, MultiSelect and Boolean test membership or truth. A Field with no value fails every test, NotEqual and DoesNotInclude included.IsOneOf: Compares with a list of the Field's optionsIncludesAnyOf: Compares a MultiSelect with a list of its options, met when it holds at least one of themIsTrue: Takes no comparandIsFalse: Takes no comparand |
comparison.comparand | object | No | Omitted for IsTrue and IsFalse |
comparison.comparand.kind | string | Yes | Which of the fields below gives what the Field is compared with: Constant a value, Field another Field, RelativeDate a date relative to today What a Comparison's Field is compared with. One of: Constant, Field, RelativeDate |
comparison.comparand.value | string or number or boolean or array | No | Constant: a value of the Field's type, or for IsOneOf a list of its options. A Date's is an ISO 8601 date; a date-time is stored as the date it is written with |
comparison.comparand.fieldDefinitionId | string | No | Field: another Field of the same type, bound in the same Procedure |
comparison.comparand.offsetDayCount | integer | No | RelativeDate: days after today, or before it when negative, today being the date in the Organization's timeZone, or in UTC while it has none |
ProcedureStepAddFieldBinding
Bind a Library Field to the step procedureStepId, which must have no sub-steps: an Input its task reads, or an Output it captures. isRequired, false when left out, makes an Input hold the task's start and its close until it has a value, and an Output hold its close; it is refused for a Select or MultiSelect Field with an empty optionList, since no value of it could be captured. PortfolioReadLibrary lists the Fields, and ProcedureImport creates a new one. A step binds a Field at most once each way: binding it again so is refused, naming the binding to change with ProcedureStepUpdateFieldBinding. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
fieldDefinitionId | string | Yes | The Library Field to bind, of the Procedure's Portfolio or its Organization |
direction | string | Yes | Input: the step's task reads the value; Output: the task captures it Whether a reference consumes (Input) or produces (Output) what it points at — a Field binding or a Material reference. A property of the reference, never the definition; distinct from Role (responsibility). One of: Input, Output |
isRequired | boolean | No | Input: the task waits for a value; Output: the task cannot close without one |
valueGuidance | string | No | What to enter, where this step needs more than the Field's own guidance |
ProcedureStepCreate
Add a step to the Procedure procedureId, one that exists: ProcedureImport creates a Procedure, with no procedureId. The step goes at procedureStepIndexPath, one index per level from the top: [2] is the third top-level step, [1, 0] the first sub-step of the second; the steps at and after it move down one, and the number of steps at a level adds it last there. Steps nest at most three levels deep, and a step that binds Fields or tests a Field before it closes takes no sub-step. The server creates the step's id, which the other ProcedureStep tools name it by. Who works or approves a step, the Procedure's own criteria and Roles, and a Field, Material or Resource new to the Portfolio Library are set only by ProcedureImport; a step no Role or Position works gives its task to the Assignee of the task above it, or of the Assignment. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. No step of an Archived Procedure changes until a person unarchives it, signed in to TaskTrain, which makes it a Draft. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureId | string | Yes | The Procedure the step belongs to |
procedureStepIndexPath | integer[] | Yes | Where the step goes, one index per level from the top, each counting from 0: [2] is the third top-level step, [1, 0] the first sub-step of the second; the steps at and after it move down one. Its last index may also be the number of steps at its level, which adds the step last; a larger one is refused |
name | string | Yes | The step's name, 1 to 111 characters, not all of them blank |
detail | string | No | The step's instructions, as HTML, kept to the markup TaskTrain's rich-text editors make, a table included; omitted, it has none |
ProcedureStepDelete
Delete a step of the Procedure procedureId, with the steps under it; its later siblings move up one, and any other step's wait on it is removed, as is every criterion, of a step or the Procedure, left reading a Field only the deleted steps bound; removedCriterionList names each such criterion and states it in its description: its author's words, if any, then its test. A Field the deleted steps alone produced, which another step or the Procedure still reads, as a Required Input or in a criterion, is then captured on the Assignment, or by a task that binds it, and the answer does not say so: read ProcedureRead's bindings and criteria after. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Destructive, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureId | string | Yes | The Procedure the step belongs to |
procedureStepId | string | Yes | The step to delete, with the steps under it |
ProcedureStepRemoveEntryCriterion
Remove one Entry Criterion of the step procedureStepId, by its entryCriterionId, so its task no longer waits on it. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Destructive, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
entryCriterionId | string | Yes | The criterion, by its own id |
ProcedureStepRemoveExitCriterion
Remove one Exit Criterion of the step procedureStepId, by its exitCriterionId. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Destructive, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
exitCriterionId | string | Yes | The criterion, by its own id |
ProcedureStepRemoveFieldBinding
Unbind one Field from the step procedureStepId, by its fieldBindingId, which ProcedureStepRead gives as each Field binding's _id; ProcedureExport gives it beside each Field of the step, whose id is the Field's own. A removal that leaves a wait no Assignment could meet is refused, as is one that leaves a criterion reading a Field the Procedure then binds nowhere. A criterion reading the Field, on any step or the Procedure, stays while the Procedure still binds it anywhere, its own boundary included, and the answer does not say so: removing the only Output binding leaves no step producing the Field, which is then captured on the Assignment, or by a task that binds it, so read ProcedureRead's bindings and criteria after. A criterion of this step's own may still test the Field, whose value its task then no longer shows. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Destructive, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
fieldBindingId | string | Yes | The binding, by its own id |
ProcedureStepUpdateDescriptors
Rename a step of the Procedure procedureId, or rewrite its instructions (detail, as HTML); an argument left out keeps what the step has, and a null detail clears it, while a step's name cannot be null or blank. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureId | string | Yes | The Procedure the step belongs to |
procedureStepId | string | Yes | The step to change |
name | string | No | Its new name, 1 to 111 characters, not all of them blank; omitted keeps it, and null is refused |
detail | string | null | No | Its new instructions, as HTML, kept to the markup TaskTrain's rich-text editors make, a table included; omitted keeps them, and null or empty clears them |
ProcedureStepUpdateEntryCriterion
Change one Entry Criterion of the step procedureStepId, by its entryCriterionId; an argument left out keeps what it has, and a changed kind clears what only the old kind used. description is kept whatever else changes, a target or a kind included: restate it when it no longer says what the criterion waits for. Nothing compares a wait with the Materials the step takes in, so a changed wait may no longer follow the step that produces one of them, and the answer does not say so: read the step's Materials with ProcedureStepRead. A wait is met as ProcedureStepAddEntryCriterion says. A null description clears it, and null clears nothing else: a criterion always keeps its kind and what it waits on. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
entryCriterionId | string | Yes | The criterion, by its own id |
kind | string | No | A changed kind clears what only the old kind used; omitted keeps it, and null is refused An Entry Criterion kind an author adds to a step: not RequiredField, which a Required Input binding implies TaskStatus: Waits until a target task of the same Assignment has reached an expected statusFieldValue: Waits until a Comparison is satisfied |
targetProcedureStepId | string | No | TaskStatus: the step waited on; omitted keeps it, and null is refused |
expectedTaskStatus | string | No | TaskStatus: In Progress, Pending Approval, Completed, Approved or Skipped; omitted keeps it, and null is refused The statuses a TaskStatus Entry Criterion may wait for: Pending Approval and Approved only on an Approval step's task InProgress: Work has begunPendingApproval: Submitted, awaiting its ApproverCompleted: The work is doneApproved: Its Approver signed it offSkipped: Closed without the work being done |
comparison | object | No | FieldValue: the test waited on; omitted keeps it, and null is refused |
comparison.fieldDefinitionId | string | Yes | The Field tested, bound in the same Procedure |
comparison.operator | string | Yes | How it is tested: an operator the Field's type offers How a Comparison tests its Field's value against its comparand, which is one value of the Field's type unless the member says otherwise. Number and Date order; Text compares exactly; Select, MultiSelect and Boolean test membership or truth. A Field with no value fails every test, NotEqual and DoesNotInclude included.IsOneOf: Compares with a list of the Field's optionsIncludesAnyOf: Compares a MultiSelect with a list of its options, met when it holds at least one of themIsTrue: Takes no comparandIsFalse: Takes no comparand |
comparison.comparand | object | No | Omitted for IsTrue and IsFalse |
comparison.comparand.kind | string | Yes | Which of the fields below gives what the Field is compared with: Constant a value, Field another Field, RelativeDate a date relative to today What a Comparison's Field is compared with. One of: Constant, Field, RelativeDate |
comparison.comparand.value | string or number or boolean or array | No | Constant: a value of the Field's type, or for IsOneOf a list of its options. A Date's is an ISO 8601 date; a date-time is stored as the date it is written with |
comparison.comparand.fieldDefinitionId | string | No | Field: another Field of the same type, bound in the same Procedure |
comparison.comparand.offsetDayCount | integer | No | RelativeDate: days after today, or before it when negative, today being the date in the Organization's timeZone, or in UTC while it has none |
description | string | null | No | What the wait is for, in words; omitted keeps it, and null or empty clears it |
ProcedureStepUpdateExitCriterion
Change one Exit Criterion of the step procedureStepId, by its exitCriterionId; an argument left out keeps what it has, and a null comparison leaves it prose, which needs a description saying what a person checks: give one in the same call if it has none. description is kept when the comparison changes: restate it when it no longer says what is checked. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
exitCriterionId | string | Yes | The criterion, by its own id |
description | string | null | No | Omitted keeps it; null clears it, which only a criterion with a comparison may |
comparison | object | null | No | Null to clear it, leaving prose |
comparison.fieldDefinitionId | string | Yes | The Field tested, bound in the same Procedure |
comparison.operator | string | Yes | How it is tested: an operator the Field's type offers How a Comparison tests its Field's value against its comparand, which is one value of the Field's type unless the member says otherwise. Number and Date order; Text compares exactly; Select, MultiSelect and Boolean test membership or truth. A Field with no value fails every test, NotEqual and DoesNotInclude included.IsOneOf: Compares with a list of the Field's optionsIncludesAnyOf: Compares a MultiSelect with a list of its options, met when it holds at least one of themIsTrue: Takes no comparandIsFalse: Takes no comparand |
comparison.comparand | object | No | Omitted for IsTrue and IsFalse |
comparison.comparand.kind | string | Yes | Which of the fields below gives what the Field is compared with: Constant a value, Field another Field, RelativeDate a date relative to today What a Comparison's Field is compared with. One of: Constant, Field, RelativeDate |
comparison.comparand.value | string or number or boolean or array | No | Constant: a value of the Field's type, or for IsOneOf a list of its options. A Date's is an ISO 8601 date; a date-time is stored as the date it is written with |
comparison.comparand.fieldDefinitionId | string | No | Field: another Field of the same type, bound in the same Procedure |
comparison.comparand.offsetDayCount | integer | No | RelativeDate: days after today, or before it when negative, today being the date in the Organization's timeZone, or in UTC while it has none |
ProcedureStepUpdateFieldBinding
Change one Field binding of the step procedureStepId, by its fieldBindingId, which ProcedureStepRead gives as each Field binding's _id; ProcedureExport gives it beside each Field of the step, whose id is the Field's own. An argument left out keeps what it has, and a null valueGuidance clears it, while null is refused for the others. A change that leaves a wait no Assignment could meet is refused, as is one that leaves a criterion reading a Field the Procedure then binds nowhere, and one of the Field or isRequired that leaves the binding requiring a Select or MultiSelect Field with an empty optionList, since no value of it could be captured. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureStepId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureStepId | string | Yes | The step |
fieldBindingId | string | Yes | The binding, by its own id |
fieldDefinitionId | string | No | Another Library Field to bind instead; omitted keeps it, and null is refused |
direction | string | No | Input: the step's task reads the value; Output: the task captures it; omitted keeps it, and null is refused Whether a reference consumes (Input) or produces (Output) what it points at — a Field binding or a Material reference. A property of the reference, never the definition; distinct from Role (responsibility). One of: Input, Output |
isRequired | boolean | No | Input: the task waits for a value; Output: the task cannot close without one; omitted keeps it, and null is refused |
valueGuidance | string | null | No | What to enter, where this step needs more than the Field's own guidance; omitted keeps it, and null or empty clears it |
ProcedureUpdateProcedureStepListOrder
Move a step of the Procedure procedureId, with the steps under it, to procedureStepIndex among the sub-steps of parentProcedureStepId, or among the top-level steps when that is left out, counting from 0; the steps at and after that place move down one, and the number of steps there besides it moves it last. Activity names the place counting from 1, as a person reads it; a move to the place the step holds already changes nothing, and Activity records none. It answers the Procedure's steps in their new order, a step's place in its list being its index, three levels deep; a step's sub-steps beyond the third level, which an older Procedure may have, are read with ProcedureStepRead. On a Published Procedure it needs the procedure:publish Grant Scope, and it changes at once, with no dry run, what new Assignments start from; open Assignments keep what they started with, and the answer reads the Procedure's status. ProcedureImport changes many steps at once, and reports them first.
Annotations: Writes, Idempotent, User only. Grant Scope: procedure:write. Also checks procedure:publish (opt-in). Organization found from: procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureId | string | Yes | The Procedure the step belongs to |
procedureStepId | string | Yes | The step to move, with the steps under it |
parentProcedureStepId | string | No | The step to move it under; omitted to move it to the top level |
procedureStepIndex | integer | Yes | Its place among its new siblings, counting from 0; the steps at and after it move down one. It may also be the number of steps at its new level besides it, which moves it last; a larger one is refused |
Grant Scope library:write
FieldDefinitionUpdate
Change a Field of a Portfolio's Library or of its Organization's, by its fieldDefinitionId, the _id PortfolioReadLibrary lists, and task and Procedure reads give each Field they bind: its name, label, description or valueGuidance, its type, or a Select's or MultiSelect's choices, given whole in optionList. One left out keeps its value, and null clears a label, description, value guidance or a Field of another type's choices. The Field changes for every Procedure binding it, so under a Grant lacking the procedure:publish Grant Scope, changing one a Published Procedure binds is refused (GrantScopeMissing): give a Draft a new Field instead, with ProcedureImport. An open Assignment keeps the Field as it started with it, so a new type or a removed choice waits until none binds it, the refusal naming each you may read by name and id for a Portfolio's Field, and counting them for an Organization Library's, and either is refused where a value captured for it, a criterion comparing it, a Trigger's fixed value or a Hand-off Trigger carrying its value would break, each refusal naming everything that holds it, beside choices left empty or blank. A Hand-off Trigger holds the two Fields it pairs to the same choices, so an added choice is refused too while one pairs this Field with another that lacks it; otherwise it is taken at once by every Procedure binding it, and by an Assignment only once one starts after, as an open one keeps the choices it started with. A Hand-off Trigger and a criterion name the Field by its _id, so a new name or label keeps each. A name is letters and digits, starting with a lowercase letter, unique in its Library and among the Fields each Procedure binding it binds, and an Organization Library Field's name is kept once a value is captured for it. An export names a Field by its name, so a document exported before a rename reads the old name as a new Field. Needs Lead or Administrator Portfolio Access to its Portfolio, or Lead or Administrator Workspace Access for an Organization Library's Field. What the Field holds already changes nothing. It answers the Field with usageProcedureList, each Procedure you may read whose boundary binds it, and usageProcedureStepList, each step you may read that binds it, with its Procedure: together, every Procedure the change reached.
Annotations: Writes, Idempotent, User only. Grant Scope: library:write. Also checks procedure:publish (opt-in). Organization found from: fieldDefinitionId.
| Input | Type | Required | Description |
|---|---|---|---|
fieldDefinitionId | string | Yes | The Field to change |
name | string | No | Its new name, letters and digits starting with a lowercase one, unique in its Library and among the Fields each Procedure binding it binds; omitted keeps it. An Organization Library Field's name is kept once a value is captured for it. A Procedure export names a Field by its name, so a document exported before a rename reads the old name as a new Field |
label | string | null | No | The words a form shows for it; omitted keeps them, null clears them |
description | string | null | No | What it records; omitted keeps it, null clears it |
type | string | No | Its new type; omitted keeps it. Refused once a value is captured for it, while an open Assignment binds it, or where a criterion compares it The data type of a FieldDefinition — drives the capture control, export JSON-Schema mapping, and the operators a Comparison offers. Signature (e-signature) and Reference (entity-picker) are deferred. One of: Text, Number, Date, Boolean, Select, MultiSelect, File |
optionList | string[] | null | No | A Select's or MultiSelect's choices, whole, replacing those it has; omitted keeps them, and null or an empty list clears them from a Field of another type. A choice may not be removed while a captured value, an open Assignment, a criterion or a Trigger's fixed value uses it |
valueGuidance | string | null | No | What to capture, shown beside its control; omitted keeps it, null clears it |
Grant Scope assignment:read
AssignmentRead
An Assignment with its task tree, three levels deep as a Procedure nests, each task with its status, start and due dates, whether they show a time of day (isTimeSet), and Assignee; its Role fills; every Field value captured on it, with the task each was captured on; its comment threads, those on the Assignment and those on its tasks, each naming its task when it is on one; and in exitCriterionStateList, what the Assignment itself is held to: the Procedure's own Exit Criteria and its Required boundary Outputs, each with whether it is met, which refuse the close of its last open task while one reads isMet: false. startedBy says what started it, and sourceAssignment the Assignment a Hand-off Trigger started it from, null where you may not read that one; a note of type HandOff on its own comment thread says what its completion started, or why it started nothing. A comment's payload is HTML, but a note of type Approval is plain text: an approver's, which has an approvalAction, and the one with neither author nor approvalAction that names who may decide a task submitted with no approver found. AssignmentTaskRead reads one task whole: its criteria, Fields, Guide, comments and direct sub-tasks, which reach the fourth level an older Procedure may have.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: assignment:read. Organization found from: assignmentId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | Yes | The Assignment to read |
AssignmentReadActivityExport
An Assignment's Activity, and every task's in it, as one JSON document to keep as evidence, in activityExport: each change once, oldest first, with who made it and the Client it came through: an entry made in TaskTrain itself has no client, and one no person or Agent made, such as a Trigger's start, no account. It records that a comment was made, not its text, which AssignmentRead reads. A start names the dates, Priority, Tags and Description it set, and a later change of a date or a Field's value names the one it replaced. The document names the Assignment this one was handed off from, by its id, whose own export holds the work before it, and by its id each Assignment a hand-off started from this one, whose own export holds the work after it. An entry names a record as it reads now, not as it read then, so a renamed one reads its later name on earlier entries, by the same id; only a description keeps a name it was written with, such as a task's in a status change. An export to an Agent leaves out each member's email address, in an entry's description as in who made it.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: assignment:read. Organization found from: assignmentId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | Yes | The Assignment to read |
AssignmentTaskRead
One task, by its assignmentTaskId and the assignmentId of the Assignment it is on: its Guide (the Resources its step names to work from, not those of a step above it, which AssignmentTaskRead of that task gives), the Tools its step is performed with and how software reaches a Digital one, the Materials it uses (Input) and makes (Output), whether it is Ready, every criterion it is held to with whether each is met, the Fields it binds as its Assignment froze them and their values, an Input's being the one its producer captured (a boundary Field's value is on AssignmentRead, with what the Assignment itself is held to, which can refuse the close of its last open task though this task's own criteria are met), the task it is a sub-task of (parentAssignmentTask), its direct sub-tasks, by name and status, which this tool reads in turn for those beneath them, and its comment thread, a Return, Reject or Reopen for Revision of an Approval task and its note among the comments, where approvalAction says which of them it was: Return, Reject or Reopen, or Approve for an approval, whose payload is empty when the approver left no note; TaskTrain asks an approver for a note on a Return and on a Reject. A sub-task that a Return of the Approval task above it sent back carries the Return's note too, as Reopen, though it needs no approval of its own. A note's payload is plain text, and any other comment's HTML. An Approval task's approver is approverAccount once it is submitted, found again at each submission; before the first, the member of approverPosition, or whoever fills approverRole on the Assignment, which AssignmentRead names, or no one, when the Role is unfilled. A Return or a Recall leaves it set while the task is back In Progress, and reopening a decided task clears it. Null once submitted means none was found: a note in its comment thread with no author and no approvalAction names the Portfolio's Human Administrators and Leads who may decide it. A task keeps the copy of its step it started with: its name, detail, criteria and Fields stay as they were when its Assignment started, though the Procedure changes after; a criterion's fieldDefinition reads the Field as its Library holds it now, so after a rename it reads the new name beside a binding that keeps the old. procedureStep names the step it was copied from, with the Tools and Materials that step names now; ProcedureStepRead reads that step as it reads now, not this task's copy.
What is withheld from you reads null; an empty list means there are none.
Annotations: Read-only. Grant Scope: assignment:read. Organization found from: assignmentTaskId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | Yes | The Assignment the task is on |
assignmentTaskId | string | Yes | The task to read |
Grant Scope assignment:write
AssignmentCreate
Start an Assignment of a Published Procedure, read first with ProcedureRead. Give its boundary Fields in fieldValueList, each by its FieldDefinition _id, and staff its Roles in roleFillList, each by the Role's _id; a Role left out is staffed by its default Position's holder, and no Agent's Account may fill a Role that approves a step, whoever starts it (ApproverClosedToAgent). A required boundary Input left out does not refuse the start: every task then waits on it until FieldValueCreate captures it on the Assignment, and the answer says so, each top-level task giving whether it isReady and, in entryCriterionStateList, each thing it waits on, met or not; a task with sub-tasks is Ready once one beneath it is, which AssignmentRead shows. Name the Assignee in assigneeAccountId unless the Procedure's default staffing, which ProcedureRead gives, names one: a person or an Agent starting a Procedure with none is refused (AssigneeRequired). You are the Requestor unless requestorAccountId names another. Starting needs Portfolio Access to the Procedure's Portfolio and the assignment:write Grant Scope, which an Agent holds only when its Administrator gives it; without either, the start is refused. A start's name, dates, staffing and Field values are judged together: a blank name, a dateTimeDue before its dateTimeStart, a Role the Procedure lacks, an Agent filling an approving Role, a required Role left unstaffed, named with its _id (RequiredRoleUnstaffed), as is one an Agent's refused fill would leave so, a missing Assignee, a value for a File Field, which a person attaches in TaskTrain (FileCaptureClosedToClient), and every other Field value refused are answered at once. A Procedure that another Precedes starts here as any other does, and the relationship starts nothing by itself: a Hand-off Trigger, which a person sets in TaskTrain and ProcedureRead gives, also starts it when an Assignment of the earlier Procedure completes, carrying across only the values its Field mappings map, each from a boundary Output of the earlier Procedure; started here, it holds the values the earlier Assignment captured only as fieldValueList gives them. A Scheduled Trigger, which ProcedureRead gives too, starts a Procedure on a repeating schedule. It notifies the people it staffs. Its dates, which each task takes, show their time of day with isTimeSet, and the date alone without it, though the time given is kept: a date alone reads in each viewer's own time zone, so give its midday in UTC to read as that date from UTC-11 to UTC+11. An optional boundary Input that a task binds as a Required Input is not asked for here, and holds that task until it is captured, which AssignmentRead shows. Once it has started, AssignmentUpdateAssignmentTaskAssignee changes who works a task, and AssignmentUpdateRoleFillList who fills a Role. It answers the Assignment with its priority, dates, Requestor and Role fills, a Role left unstaffed with a null account, whose steps' tasks go to the task above them, or else to the Assignee, and its top-level tasks: AssignmentRead reads its whole task tree.
Annotations: Writes, Agent: opt-in. Grant Scope: assignment:write. Organization found from: procedureId.
| Input | Type | Required | Description |
|---|---|---|---|
procedureId | string | Yes | The Published Procedure to assign |
name | string | Yes | The Assignment's name, 1 to 111 characters, not all of them blank, telling it apart from the Procedure's other Assignments |
description | string | No | What this Assignment is for; omitted, it has none |
priority | string | No | Absent makes it Normal Possible priorities for an Assignment One of: Lowest, Low, Normal, High, Highest |
dateTimeStart | string | No | When work is planned to start; omitted, no start is planned |
dateTimeDue | string | No | When the work is due; omitted, it has no due date |
isTimeSet | boolean | No | Whether its dates, and each task's, show their time of day; omitted, they show the date alone, though a time given is kept |
assigneeAccountId | string | No | Absent, the Procedure's default staffing names the Assignee; a person or an Agent starting a Procedure with none names one |
requestorAccountId | string | No | Absent makes the caller the Requestor |
tagList | string[] | No | Labels to find the Assignment by; omitted, it has none |
roleFillList | object[] | No | Who fills each of the Procedure's Roles, each named by its _id in ProcedureRead's roleList. A Role left out is filled by its defaultPosition's holder, and one named with no Account stays unfilled; a Role the Procedure requires must end up filled, and one it lacks is refused. |
roleFillList.procedureRoleId | string | Yes | The Procedure's Role to fill |
roleFillList.accountId | string | No | Omitted when the Role is intentionally unstaffed on this Assignment |
fieldValueList | object[] | No | Boundary Field values captured at kickoff. Each entry must name a FieldDefinition bound on the Procedure's boundary; an unbound entry, or one whose value its Field's type cannot take, is rejected rather than silently dropped, though a number given for a Text, Select or MultiSelect Field is taken as its digits. |
fieldValueList.fieldDefinitionId | string | Yes | The Field to capture, bound on the Procedure's boundary |
fieldValueList.value | string or number or boolean or array | No | The value, typed by the Field's type: a string for Text or Select (one of its options), a number, an ISO 8601 date (a date-time is stored as the date it is written with), a boolean, or a list of strings for MultiSelect; a number given for Text, Select or MultiSelect is taken as its digits. An entry with no value, or an empty one, is skipped, leaving the Field empty |
AssignmentUpdateRoleFillList
Re-staff the Roles of the Assignment assignmentId. roleFillList gives every Role's fill whole, as AssignmentRead's roleFillList reads them now, each by its Role's _id, which ProcedureRead gives, with the member's accountId, or none to leave the Role unstaffed: a Role left out is left unstaffed. A Role the Procedure lacks, a required Role it would leave unstaffed that was staffed, and an Agent's Account filling a Role that approves a step (ApproverClosedToAgent) are refused together, and nothing changes. Each task whose step a re-staffed Role works moves to its new member, or to the task above it where the Role is left unstaffed, when its work is not yet submitted or closed and no one gave it another Assignee since; a step that names a Position keeps its task's Assignee. An Approval task's approver is found again at each submission, so re-staffing the Role that approves it changes who decides it from its next submission. Each member a task moves to finds it in their Assignment Inbox. Fills each Role holds already change nothing. It needs the assignment:write Grant Scope and is open to the Assignment's Assignee and anyone holding Administrator or Lead Portfolio Access, and its refusal names whom to ask in a comment thread by their part: AssignmentRead names who holds each. AssignmentUpdateAssignmentTaskAssignee changes who works one task. It answers the Assignment's Role fills and its task tree with each task's Assignee, three levels deep.
Annotations: Writes, Destructive, Idempotent, Agent: opt-in. Grant Scope: assignment:write. Organization found from: assignmentId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | Yes | The Assignment whose Roles to re-staff |
roleFillList | object[] | Yes | Every Role's fill, whole: a Role left out is left unstaffed |
roleFillList.procedureRoleId | string | Yes | The Procedure's Role to fill |
roleFillList.accountId | string | No | Omitted when the Role is intentionally unstaffed on this Assignment |
Grant Scope fieldValue:write
FieldValueCreate
Capture a Field's value, naming only where it lands: assignmentId for a Field of the Procedure's boundary, or assignmentTaskId for one the task's step binds. While a task that binds the Field as Output is open, only such a task may capture it. Capturing on a Not Started task does not start it. Once every such task has closed without a value, or where no task binds it as Output, as with a boundary Input, it is captured on the Assignment or on any open task that binds it, while the Assignment is open, so a closed step does not protect an Output it left empty, and a task binding a boundary Input can change the value the Assignment started with, even while an Approval task awaits its approver, who is told nothing. A capture naming a closed task is refused (TaskClosedToCapture), saying where to capture the Field instead, as is a first capture on a closed Assignment (AssignmentClosedToCapture). A capture on a task whose step does not bind the Field is refused (FieldNotBoundOnTask), naming where it is captured instead. A Field nothing in the Assignment binds is refused. A value must fit the Field's type and choices as they were when the Assignment started, which it keeps. A Date Field's value keeps the date it is written with, its time and offset dropped, unlike a task's dates, which are moments stored in UTC. Name the Field by its FieldDefinition _id, which task and Procedure reads give as fieldDefinition._id, never by a binding's own _id. An Assignment holds one value per Field: capturing it again changes that value where it was first captured, wherever you name now among the Assignment and its open tasks. A value held anywhere but on the open task that produces its Field is changed only by naming that task (ProducedByOpenTask). The answer's assignmentTask gives where it is held, null for the Assignment, and the value is frozen while that task stays closed, or while the Assignment does for a value on the Assignment (ValueFrozen); capturing the value it holds changes nothing. A first capture is open to the Assignee of the Assignment or task, the Requestor for a boundary Input, and anyone holding Administrator, Lead or Associate Portfolio Access, staffed or not, though changing or deleting another's is not open to Associate Access: see FieldValueUpdate. A File Field is attached by a person in TaskTrain, on an open task that binds it, or on the Assignment for a boundary Field, and refused here, telling a person to attach it signed in, or an Agent whom to ask: a step's File Field left empty once every task binding it has closed is attached by reopening one of those tasks while the Assignment is open.
Annotations: Writes. Grant Scope: fieldValue:write. Organization found from: assignmentId, assignmentTaskId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | No | The Assignment a Procedure-boundary value is captured on; give this or assignmentTaskId, not both |
assignmentTaskId | string | No | The task a step's value is captured on; give this or assignmentId, not both |
fieldDefinitionId | string | Yes | The Field to capture |
value | string or number or boolean or array | Yes | The value, typed by the Field's type: a string for Text or Select (one of its options), a number, an ISO 8601 date (a date-time is stored as the date it is written with), a boolean, or a list of strings for MultiSelect; a number given for Text, Select or MultiSelect is taken as its digits |
FieldValueDelete
Clear a captured Field: delete its value, by the fieldValueId that FieldValueCreate answered or a task read gives. A value a closed task or Assignment holds is frozen and cannot be deleted. Clearing a Required Field holds work again, and the answer does not say so: a Required boundary Input holds the start and the close of every open task, those that were Ready included, a started one's too, though a started one may still move between In Progress and On Hold; a Required Input a task binds holds that task's start and its close; and a Required Output holds its task's close. Who may delete is who may change it: see FieldValueUpdate. While a task that binds the Field as Output is open, only such a task may change it, so a value held anywhere else is refused here (ProducedByOpenTask): change it with FieldValueCreate, naming that task, or delete it once that task closes. A File Field's value is deleted by a person in TaskTrain, and refused here, telling a person to remove it signed in, or an Agent whom to ask.
Annotations: Writes, Destructive, Idempotent. Grant Scope: fieldValue:write. Organization found from: fieldValueId.
| Input | Type | Required | Description |
|---|---|---|---|
fieldValueId | string | Yes | The captured value to delete |
FieldValueUpdate
Change a captured Field value, by its fieldValueId, to a new value of the Field's type. To clear the Field, delete the value with FieldValueDelete. The value it already holds changes nothing, and no Activity records it. A value is frozen while the task it was captured on stays closed, or, captured on the Assignment, while the Assignment does. Reopening that task opens the value again, even while an Approval task reading it awaits its approver, which stays submitted and tells its approver nothing; Activity records the change. While a task that binds the Field as Output is open, only such a task may change it: a value held anywhere else is refused here (ProducedByOpenTask) and changed with FieldValueCreate, naming that task. It is open to the Assignee of the Assignment or task, the Requestor for a boundary Input, the Account whose capture or change it holds, with Associate Portfolio Access, and anyone holding Administrator or Lead Portfolio Access, staffed or not; a refusal names each of them by their part, to ask in a comment thread: AssignmentRead names who holds each. A File Field's value is replaced by a person in TaskTrain, and refused here, telling a person to replace it signed in, or an Agent whom to ask. The answer's assignmentTask gives the task holding the value, null for the Assignment.
Annotations: Writes, Idempotent. Grant Scope: fieldValue:write. Organization found from: fieldValueId.
| Input | Type | Required | Description |
|---|---|---|---|
fieldValueId | string | Yes | The captured value to change |
value | string or number or boolean or array | Yes | The new value, typed by the Field's type: a string for Text or Select (one of its options), a number, an ISO 8601 date (a date-time is stored as the date it is written with), a boolean, or a list of strings for MultiSelect; a number given for Text, Select or MultiSelect is taken as its digits |
Grant Scope assignmentTask:write
AssignmentUpdateAssignmentTaskAssignee
Change who works a task, by its assignmentTaskId, or, with none, who is the Assignee of the Assignment assignmentId itself, to the member assigneeAccountId, a person or an Agent of the Assignment's Organization, by the Account _id a task, a Role fill or a Position's member gives. updateChildren true gives every task beneath the same Assignee, each sub-task of the task or every task of the Assignment; left false, it changes only the one named. A task keeps its status and its approver, whoever works it: AssignmentUpdateRoleFillList changes who fills a Role. The new Assignee finds the work in their Assignment Inbox and is emailed it; one left with no task of the Assignment to work or approve loses it from theirs. An Assignee each record reached holds already changes nothing. An Agent hands a task it should not work back to a person this way. A change is open to the Assignee of the Assignment or the task, and anyone holding Administrator or Lead Portfolio Access, and its refusal names whom to ask in a comment thread by their part: AssignmentRead names who holds each. It answers the Assignment's task tree with each task's Assignee, three levels deep; AssignmentTaskRead reads a fourth.
Annotations: Writes, Idempotent. Grant Scope: assignmentTask:write. Organization found from: assignmentId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | Yes | The Assignment, or the one the task is on |
assignmentTaskId | string | No | The task to reassign; omitted, the Assignment's own Assignee changes |
assigneeAccountId | string | Yes | The member, a person or an Agent of the Assignment's Organization, the work goes to |
updateChildren | boolean | No | Whether every task beneath goes to the same member: each of the task's sub-tasks, or every task of the Assignment Default: false |
AssignmentUpdateAssignmentTaskDateTime
Set, move or clear the start and due dates of a task, by its assignmentTaskId, or, with none, of the Assignment assignmentId itself. Give each as an ISO 8601 date-time, stored in UTC, its offset converted, unlike a Date Field's value, which keeps the date it is written with: one left out keeps its value, and null clears it. updateChildren true gives the dates given, and whether they show their time, to every task beneath as well, each sub-task of the task or every task of the Assignment; left out, it changes only the one named. With updateChildren and no isTimeSet, every task beneath takes the display the one named shows, as its Activity entry says. isTimeSet says whether TaskTrain shows the dates' time of day or only the date, which each viewer reads in their own time zone, so a date meant alone is given as its midday in UTC, such as 2026-11-20T12:00:00Z, to read as that date from UTC-11 to UTC+11; left out, the one named keeps its own. A due date before the start is refused, but nothing compares a task's dates with its parent's, the Assignment's, or those of a task waiting on it. Dates and a display that each record reached holds already change nothing, and no Activity records them. AssignmentCreate gives every task the Assignment's dates when it starts; this changes them after. A change is open to the Assignee of the Assignment or the task, and anyone holding Administrator or Lead Portfolio Access, and its refusal names whom to ask in a comment thread by their part: AssignmentRead names who holds each. Its Activity entry names each date set, with its display where given, and each cleared. It answers the Assignment's dates and its task tree with each task's, three levels deep; AssignmentTaskRead reads a fourth.
Annotations: Writes, Idempotent. Grant Scope: assignmentTask:write. Organization found from: assignmentId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | Yes | The Assignment, or the one the task is on |
assignmentTaskId | string | No | The task whose dates change; omitted, the Assignment's own change |
dateTimeStart | string | null | No | When the work starts; omitted keeps it, null clears it |
dateTimeDue | string | null | No | When the work is due; omitted keeps it, null clears it |
updateChildren | boolean | No | Whether the dates given reach every task beneath: each of the task's sub-tasks, or every task of the Assignment Default: false |
isTimeSet | boolean | No | Whether TaskTrain shows the dates' time of day, or only the date; omitted keeps it |
AssignmentUpdateAssignmentTaskStatus
Move a task to a status, or, with no assignmentTaskId, the whole Assignment, which takes InProgress, OnHold, Completed or Skipped. A whole-Assignment Completed or Skipped need not close it: Completed closes every open task no criterion holds, worked or not, and submits each Approval task instead, Skipped passes over each Approval task and its sub-tasks, which stay open, and the Assignment's own status, derived from its tasks, can then read InProgress, or NotStarted beside Skipped tasks; a Skipped that closes every task reads Completed where any task was Completed, and its exitCriterionStateList shows each Exit Criterion it passed over. InProgress and OnHold leave a task a wait holds, and one awaiting its approver, as it was, so after OnHold too the Assignment can read InProgress. Read the answer's tree, since no error says what stayed open; the move's Activity entry, which AccountReadActivityList reads, names each task it moved, apart from any moved before, and each it left open. It answers the Assignment's whole task tree, however few tasks it moved, three levels deep; AssignmentTaskRead reads a fourth, which an older Procedure may have. A task takes those statuses too, but naming an Approval task with Skipped is refused, and a task with no sub-tasks also takes NotStarted, and may go from NotStarted to Completed in one move. An Approval task that waits on a Skipped task has no other way on: reopen that task, once its own waits are met, and finish it. A task's move is open to its Assignee and the Assignment's, its Approver, and anyone holding Administrator or Lead Portfolio Access, staffed or not; the whole Assignment's only to its Assignee and to those holding Administrator or Lead Portfolio Access, not to its Requestor. A refusal names whom to ask in a comment thread by their part: AssignmentRead names who holds each. Completed on an Approval task submits it to its approver. The Assignment's own criteria, which AssignmentRead gives, never hold a submission, even one that leaves only approvals open, but they hold the Approve that would complete the Assignment: its approver may Return or Reject it until they are met. PendingApproval does the same on an Approval task with no sub-tasks, and is refused on any other task. An Approval task with sub-tasks submits itself when its last open sub-task closes, so a returned one, of which its approver may have reopened only some sub-tasks, goes back to its approver then: answer the Return first, and reopen any other sub-task the Return's note asks to be revised, which its Assignee may while the Approval task is back In Progress. Its Assignee may Recall a submitted Approval task with no sub-tasks by InProgress, which emails the approver; one with sub-tasks is not Recalled. Approved and Rejected are the approver's, signed in to TaskTrain, where the task is in their Assignment Inbox: through a Client or by an Agent they are refused (SignOffRequiresSignedInUser), as are a Return and reopening a closed Approval task. Only an Approval task takes a Return, from PendingApproval. Any other closed task with no sub-tasks may be reopened, unless it is under an Approval task submitted or decided, whose approver sends the work back; a closed parent reopens by reopening a sub-task, which it follows. Reopening or resetting a task that a submitted Approval task waits on, or one a task above it waits on, leaves it submitted and tells its approver nothing, and its Approve is refused until that task closes again. Reopening a task reopens each task above it, and a closed Assignment, one closed over a Rejected task too, which stays Rejected, so a task waiting on one of those, such as a returned Approval task's resubmission, waits again until it closes. An Entry Criterion holds a task's close as well as its start: an unmet wait refuses its Completed, PendingApproval or Approved, though it was met when the task started, as when a Field it tests was cleared since. A refusal names each unmet criterion, a wait with the status its task has now. A Skipped task reopens only once every Entry Criterion it waits on is met; NotStarted resets it. An Assignment closes with a task Rejected, so it can read Completed over one; its Hand-off Triggers then start nothing. A parent with a Rejected sub-task can read Completed likewise, but a wait on it, unless for InProgress, stays unmet until that sub-task is reopened or the waiting task is Skipped. So does a wait on a Rejected Approval task: an Agent, which may neither reopen it nor Skip past a wait, asks a person to reopen it for revision or to Skip what waits. A task with sub-tasks carries the status to every open sub-task beneath it, except one an unmet criterion holds, and its own status then follows them, as the Assignment's follows its tasks: it reads OnHold only once no sub-task is left Not Started or under way, so InProgress with one held beside one Not Started, and NotStarted with nothing begun beside Skipped ones. To work on one part, move that sub-task. A wait on another task's status is judged by the status the same move gives that task, so a sub-task waiting on a sibling the move closes is closed with it. No criterion holds a Human's Skip, through a Client too, the Assignment's own Exit Criteria included, so a person closes an Assignment by Skipping what is left of it, and by submitting each Approval task left, which its approver may Reject; a step that waits on a Field's value is never passed over by itself, so a person Skips it where the value does not call for it; an Agent's Skip is refused whole when it would pass an unmet criterion on any task it reaches or on the Assignment, and the refusal names each such criterion and who may make the Skip: the task's Assignee and the Assignment's, each where a person, and the Portfolio's Human Administrators and Leads. A refusal of a task that waits on a Field's value says the same of a Skip where it will not be needed, as a Completed that moves nothing says how to close the work without what is held, and one that leaves only tasks awaiting their approvers names them, as each approver closes the work, with what the Assignment still needs where that holds the Approve completing it. The answer's exitCriterionStateList gives what the Assignment is held to, so a Skip that closed it past a criterion shows isMet: false. A change an unmet criterion refuses, or that would move no task, writes nothing, and the refusal says what holds it; repeating the status a target already holds writes nothing and answers as it stands.
Annotations: Writes, Idempotent. Grant Scope: assignmentTask:write. Organization found from: assignmentId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | Yes | The Assignment the task is on |
assignmentTaskId | string | No | The task to move; absent, the Assignment itself moves, and its tasks with it |
status | string | Yes | The status to move it to The status of a task, or of an Assignment, whose status follows its tasks' NotStarted: Open; no work has begunInProgress: Open; work has begunSkipped: Closed without the work being doneOnHold: Open; work is pausedPendingApproval: Open; submitted, awaiting its ApproverCompleted: Closed; the work is doneApproved: Closed; its Approver signed it offRejected: Closed; its Approver refused it |
Grant Scope discussion:write
AccountUpdateCommentThreadViewStatus
Mark a comment thread read in your Comments Inbox, by the commentThreadId AccountReadCommentThreadList gives, once you have answered or acted on its comments: it then lists only under Read, until someone else comments in it. accountId is your own Account in the thread's Organization, as AccountRead gives it. A thread your Inbox does not hold is refused. Marking a read thread read changes nothing.
Annotations: Writes, Idempotent. Grant Scope: discussion:write. Organization found from: accountId.
| Input | Type | Required | Description |
|---|---|---|---|
accountId | string | Yes | The caller's own Account, in the Organization of the thread |
commentThreadId | string | Yes | The thread to mark read |
CommentThreadCreate
Start a comment thread on a task, or on an Assignment, naming only the one it lands on: what was done, where a value came from, an answer to a Return. An Assignment holds any number of threads, a task one: once a task has one, this is refused with the thread's id, and CommentThreadCreateComment adds to it. The answer names the Assignment the thread is on, and the task when it is on one. The thread's comments are in discussionList, each with its replies in a discussionList of its own; a comment made here has the type Embedded, and a decision's note Approval. AssignmentRead reads back an Assignment's threads, and AssignmentTaskRead a task's. payload is the comment's text, as HTML, kept to the formats TaskTrain's comment editor makes: paragraphs, headings, emphasis, lists, quotes, code, links and images, so a table keeps only its text; one that shows nothing once kept to them is refused. Commenting is open to the Assignment's Assignee and Requestor, the Assignee or Approver of any of its tasks, and anyone holding Administrator, Lead or Associate Portfolio Access, staffed or not. The thread's followers are notified: the Assignment's Requestor and Assignee, and the Assignee and approver of each of its tasks, so a person who is none of these learns of it only by reading the Assignment. The answer's followerList names them: each but the comment's author finds it unread in their Comments Inbox, which AccountReadCommentThreadList reads, and a person is emailed it where they take comment emails.
Annotations: Writes. Grant Scope: discussion:write. Organization found from: assignmentId, assignmentTaskId.
| Input | Type | Required | Description |
|---|---|---|---|
assignmentId | string | No | The Assignment to start a thread on; give this or assignmentTaskId, not both |
assignmentTaskId | string | No | The task to start its thread on; give this or assignmentId, not both |
payload | string | Yes | The comment's text, as HTML, kept to the markup TaskTrain's comment editor makes. A comment that shows nothing once kept to it, and has no attachment, is refused |
CommentThreadCreateComment
Add a comment to a comment thread, by its commentThreadId, or, with replyToCommentId, a reply to one of its comments, not to a reply, as replies are one level deep: what was done, where a value came from, an answer to a Return. AssignmentTaskRead gives a task's thread, and AssignmentRead every thread. payload is the comment's text, as HTML, kept to the formats TaskTrain's comment editor makes; one that shows nothing once kept to them is refused. The answer is the thread, with the new comment in it, and its followerList: each follower but the comment's author finds it unread in their Comments Inbox, which AccountReadCommentThreadList reads, and a person is emailed it where they take comment emails.
Annotations: Writes. Grant Scope: discussion:write. Organization found from: commentThreadId.
| Input | Type | Required | Description |
|---|---|---|---|
commentThreadId | string | Yes | The thread to add to |
replyToCommentId | string | No | A comment in the thread to reply to, not itself a reply, as replies are one level deep; absent adds the comment to the thread itself |
payload | string | Yes | The comment's text, as HTML, kept to the markup TaskTrain's comment editor makes. A comment that shows nothing once kept to it, and has no attachment, is refused |
Server instructions
What the server tells a Client's model before it calls anything. Some Clients don't show these, so each tool description also says what its caller needs.
For a User's Client
TaskTrain runs an Organization's Procedures as Assignments, each a tree of tasks. Start with UserReadOrganizationList for the Organizations this Client may act in and your Account in each. Find a Procedure with AccountReadProcedureList; read it with ProcedureRead, or whole as an SOP with ProcedureExport; start it with AssignmentCreate. Your tasks are in AccountReadAssignmentTaskList, and AssignmentTaskRead reads one with its direct sub-tasks. Capture Fields with the FieldValue tools, comment with the CommentThread tools, finding replies in AccountReadCommentThreadList, and move a task with AssignmentUpdateAssignmentTaskStatus, which moves each open sub-task no criterion holds. An Approval Task a person returned or reopened for revision reads In Progress, and one they rejected reads Rejected until they reopen it. Each note is in its comment thread: answer it there first, since completing the task, or its last open sub-task, submits it again. Times are in UTC; AccountRead gives an Organization's timeZone. What names you as approver is in AccountReadAssignmentTaskList under PendingApproval: approving, returning, rejecting and reopening a closed Approval Task stay with a signed-in User. One submitted with no approver lists a null approverAccount: its comment thread names who may decide it. To change one step, read it with ProcedureStepRead by its id from ProcedureRead, and use the ProcedureStep tools. To change many, export it as JSON with ProcedureExport, edit it, and import it back with ProcedureImport onto the same procedureId; without one, it creates a Draft. It dry-runs until isDryRun is false. AccountReadPortfolioList lists Portfolios; read PortfolioReadLibrary first, and bind its entries by _id. A person publishes a Draft. To import into a new Portfolio, create it with PortfolioCreate. Changing a Published Procedure needs the procedure:publish Grant Scope; without it, import the change as a new Draft related to the original. AssignmentReadActivityExport writes an Assignment's Activity as JSON, for evidence.
For an Agent
You act as the Agent "<Agent name>", Account <Account id>, of the Organization "<Organization name>", <Organization id>, and in no other. TaskTrain runs an Organization's Procedures as Assignments, each a tree of tasks. Pass that Organization's _id where a tool asks for an organizationId. Find a Procedure with AccountReadProcedureList; read it with ProcedureRead, or whole as an SOP with ProcedureExport; start it with AssignmentCreate. Your tasks are in AccountReadAssignmentTaskList, and AssignmentTaskRead reads one with its direct sub-tasks. Capture Fields with the FieldValue tools, comment with the CommentThread tools, finding replies in AccountReadCommentThreadList, and move a task with AssignmentUpdateAssignmentTaskStatus, which moves each open sub-task no criterion holds. An Approval Task a person returned or reopened for revision reads In Progress, and one they rejected reads Rejected until they reopen it. Each note is in its comment thread: answer it there first, since completing the task, or its last open sub-task, submits it again. Times are in UTC; AccountRead gives an Organization's timeZone. An Agent never approves, rejects or returns a task, nor reopens a closed Approval Task: a signed-in User does. It starts Assignments only with the assignment:write Grant Scope. It reads Procedures, Portfolios and their Libraries, and never changes one: a person authors them. You may change or clear a value you captured while its task is open. Ask the person a refusal names in the task's comment thread, where you also say a step reads wrong or is missing; hand a task you should not work to a person with AssignmentUpdateAssignmentTaskAssignee. AccountReadActivityList reads what you have done.
Related Articles
Step-by-Step