GetFlowDef API¶

Returns the complete definition of a workflow, including all step definitions and their task definitions.

Endpoint¶

/srv.asmx/GetFlowDef

Methods¶

• GET /srv.asmx/GetFlowDef?AuthenticationTicket=...&DomainName=...&WorkflowName=...
• POST /srv.asmx/GetFlowDef (form data)
• SOAP Action: http://tempuri.org/GetFlowDef

Parameters¶

Response¶

Success Response¶

<response success="true">
  <FlowDef
    FlowDefID="126"
    FlowName="ContractApproval"
    DomainId="45"
    DomainName="Corporate"
    ActiveFolderPath="/Corporate/Contracts"
    RequiresStartUpPlayers="false"
    Active="true"
    OnEndMoveToPath="/Corporate/Archive"
    OnEndEventUrl="https://erp.example.com/workflow-complete"
    Hide="False">
    <StepDef StepNumber="1" StepName="Review" OnStartMoveToFolderId="0" OnStartMoveToFolderPath="">
      <TaskDefs>
        <TaskDef
          TaskDefId="55"
          TaskName="LegalReview"
          DeadLine="48"
          RequiredAssigneeCount="0"
          SuperVisorId="7"
          SuperVisorName="John Smith"
          SupervisorNotificationOnDue="-1"
          Priority="5"
          AllowedStartTimeSpan="0"
          ReminderTimeSpan="0"
          righttype="2"
          OnCompleteNotice="False">
          <Requirements>
            <Requirement Name="LastestVersionRead" Definition="" RefObjectId="0" />
          </Requirements>
          <RightType RightTypeId="2" RightTypeName="READ" RightTypeText="Read Only" />
          <Permissions>
            <Permission Name="EditDocument" Value="False" />
            <Permission Name="ChangeFinishdate" Value="False" />
            <Permission Name="Postpone" Value="False" />
            <Permission Name="ChangePriority" Value="False" />
            <Permission Name="EditNextStep" Value="False" />
            <Permission Name="EditAllSteps" Value="False" />
          </Permissions>
          <instruction>Please review the contract carefully.</instruction>
          <AssigneeList>
            <Users>
              <User exists="true" UserID="12" Domain="" UserName="jane.doe" FirstName="Jane" LastName="Doe" Email="jane.doe@example.com" />
            </Users>
            <UserGroups>
              <group id="3" name="Legal" />
            </UserGroups>
            <SpecialUserRoles>
              <SpecialUserRole RoleId="-5" RoleDescription="DocumentOwner" />
            </SpecialUserRoles>
          </AssigneeList>
        </TaskDef>
      </TaskDefs>
    </StepDef>
    <Supervisors>
      <User id="7" UserName="john.smith" FullName="John Smith" />
    </Supervisors>
  </FlowDef>
</response>

Error Response¶

<response success="false" error="Session expired or invalid ticket" errorCode="4010" />

FlowDef Attributes¶

The <Supervisors> element lists the workflow-level supervisors: <User id="..." UserName="..." FullName="..."/> and <Group id="..." GroupName="..." DomainName="..."/>. Send a user back to UpdateWorkflowDefinition by its UserName (or as ~U<id>).

StepDef Attributes¶

UpdateWorkflowStepDef keeps the on-start folder when onStartMoveToFolderPath is left out, so a step can be renamed without sending it.

TaskDef Attributes¶

Both righttype and OnCompleteNotice are written with the names UpdateWorkflowTaskDef takes, so a <TaskDef> read here can be sent back as it stands; both reset when left out of an update.

TaskDef Child Elements¶

<Requirements>¶

Lists completion requirements. Each <Requirement> element has: - Name -" Requirement type (e.g. LastestVersionRead, Edit, Comments, Approval, SOXReview, ISOReview). - Definition -" Supplemental definition text (used for some requirement types). - RefObjectId -" Referenced object ID (used for some requirement types).

<RightType>¶

Describes the minimum document access right required for this task. Attributes: - RightTypeId — Numeric right type value (0=NOACCESS, 1=LIST, 2=READ, 3=ADD, 4=ADDREAD, 5=CHANGE, 6=FULLCONTROL). - RightTypeName — C# enum member name (e.g. READ, CHANGE, FULLCONTROL). - RightTypeText — Localized display label of the right type.

<Permissions>¶

Six named boolean permissions for the task assignee: - EditDocument -" Assignee may edit the document. - ChangeFinishdate -" Assignee may change the finish date. - Postpone -" Assignee may change the due date. - ChangePriority -" Assignee may change the task priority. - EditNextStep -" Assignee may change next-step routing. - EditAllSteps -" Assignee may change routing for all remaining steps.

<instruction>¶

Free-text instruction for the task assignee.

<AssigneeList>¶

Contains three sub-elements: - <Users> -" Individual users (<User exists="true" UserID="..." Domain="..." UserName="..." FirstName="..." LastName="..." Email="..." .../>). - <UserGroups> -" User groups (<group id="..." name="..."/>). - <SpecialUserRoles> -" Special roles such as document owner or submitter (<SpecialUserRole RoleId="..." RoleDescription="..."/>). RoleId -5 = DocumentOwner (the document owner at submit time), -8 = Submitter.

Required Permissions¶

Any authenticated user may call this API. Anonymous (unauthenticated) access is not permitted.

Example¶

GET Request¶

GET /srv.asmx/GetFlowDef
    ?AuthenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &DomainName=Corporate
    &WorkflowName=ContractApproval
HTTP/1.1
Host: yourserver

POST Request¶

POST /srv.asmx/GetFlowDef HTTP/1.1
Host: yourserver
Content-Type: application/x-www-form-urlencoded

AuthenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c&DomainName=Corporate&WorkflowName=ContractApproval

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Reads one definition with its steps and their task definitions. This is where the FlowDefID and TaskDefId values the other operations take come from.

const root = await call('GetFlowDef', {
  authenticationTicket: ticket,
  DomainName: 'Public',
  WorkflowName: 'Invoice approval'
});

const flowDef = root.querySelector('FlowDef');
console.log(flowDef.getAttribute('FlowDefID'), flowDef.getAttribute('Active'));

for (const step of root.querySelectorAll('StepDef')) {
  console.log(step.getAttribute('StepNumber'), step.getAttribute('StepName'));
  for (const taskDef of step.querySelectorAll('TaskDef')) {
    console.log('  ', taskDef.getAttribute('TaskDefId'), taskDef.getAttribute('TaskName'));
  }
}

Notes¶

• The response always includes the full set of step and task definitions.
• To list all workflows for a domain without step detail, use GetDomainFlows.
• To list workflows active on a specific folder, use GetFolderFlows.

Related APIs¶

• GetDomainFlows -" List all workflow definitions for a domain (without step detail).
• GetFolderFlows -" List workflow definitions active on a specific folder.
• CreateFlowDef -" Create a new workflow definition.
• ActivateFlowDef -" Activate a workflow definition.
• DeactivateFlowDef -" Deactivate a workflow definition to allow changes.
• AddFlowStepDef -" Add a step to a workflow definition.
• AddFlowTaskDef -" Add a task definition to a workflow step.
• DeleteWorkflow -" Permanently delete a workflow definition.

Error Codes¶

The errorCode values this operation returns, checked against a running server: