Workflow object allows users to manage workflows in Maximizer CRM.
A workflow consists of a series of task templates that are scheduled sequentially, enabling users to predefine and execute both custom and predefined processes as part of their daily work.
Below are some considerations for Workflow:
-
The workflow name is mandatory and must be unique within the database.
-
The workflow tag is an optional unique textual identifier. Once defined, it cannot be modified.
HowTo's
Workflows — how-to guide
A workflow automates a repeatable sequence of tasks against an AbEntry (a company or individual). This guide builds one end to end and shows how to watch it run.
The pieces
- Workflow — the definition. On its own it does nothing; it needs task templates before it can run.
- Workflow Task Template — describes a task the workflow should create: its subject, who it is assigned to, and when it is due. A workflow needs at least two templates before it can start.
- Workflow Stage (optional) — groups templates into ordered phases. Use stages when the work happens in distinct rounds; skip them for a simple checklist.
- Workflow Instance — created automatically when you start a workflow on a record. It is read-only and is how you track a run: which step or stage it is on, and whether it has finished.
How it flows
- Create the workflow.
- Add its task templates (and stages, if you want phases).
- Start the workflow on an AbEntry. The engine creates the first real task(s) from your templates.
- Read the workflow instance to see progress.
- Complete each task. Completing a task tells the engine to create the next one and move the run forward, until the last task finishes the workflow.
Two walkthroughs
- 1. Task workflow (no stages) — the simplest setup: an ordered list of tasks.
- 2. Workflow with stages — the same idea, grouped into phases.
> Each step saves the keys it creates as collection variables and reuses them in the next step, so you can run a folder from top to bottom. You need a valid auth token and a {{BaseURL}} for your instance; use sample data.
>
> Looking for triggers, branching, or automatic field updates? See _ WorkflowAction → HowTo's.
1. Task workflow (no stages)
Task workflow (no stages)
The simplest workflow: an ordered list of task templates, no stages. When you start it on an AbEntry, the engine creates tasks from those templates. With IsSequential = true the next task is created only after the current one is completed; with false all tasks are created at once.
Run the steps in order:
-
Create the workflow
2–3. Add two task templates (a workflow needs at least two before it can start) -
Create a company to run it on
-
Start the workflow
-
Track progress on the workflow instance
-
Read the current task
-
Complete the task to create the next one
> For the complete field list on each object, see that object's CRUD and FieldOptions examples. For completing the final task (and passing a result when branching is set up), see Task V2 → HowTo's → Complete tasks that are part of a workflow.
1 - Create the workflow
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
"Workflow": {
"Data": {
"Key": null,
"Name": "Guide task workflow {{$randomInt}}",
"Description": "Sample task workflow created from the how-to guide.",
"TAG": "GUIDE_TASK_{{$randomInt}}",
"IsSequential": true // true: the next task is created only after the current one is completed; false: all tasks are created at once
}
}
}2 - Add task template 1 (Sequence 1)
First task in the workflow. The due date is built from the offset: DateOffsetUnit 3 = Days, so this task is due 2 days after the workflow starts, at the Time given (the date part of Time is ignored). The alarm fires AlarmOffsetValue before the due date (AlarmOffsetUnit 2 = Hours). See WorkflowTaskTemplate → FieldOptions for all unit and option values, and WorkflowTaskTemplate → CRUD for the full field list.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
"WorkflowTaskTemplate": {
"Data": {
"Key": null,
"WorkflowKey": "{{WF_Key}}",
"Sequence": 1,
"Subject": "Call the client and introduce yourself",
// AssignedToExpression - who the created task is assigned to. Three forms:
// "AccountManager" -> the AbEntry's Account Manager (an expression, resolved when the task is created)
// "WorkflowStarter" -> the user who starts the workflow (an expression)
// a user UID -> a specific user by login ID, e.g. "MASTER"
"AssignedToExpression": "AccountManager",
"Priority": "Hi",
"IconType": 1,
// Due date = a start point + (DateOffsetValue x DateOffsetUnit).
// The start point is the workflow start date for the first task, or the previous task's completion date for later tasks.
"DateOffsetUnit": 3, // unit for the due-date offset: 3 = Days, 4 = Weeks, 5 = Months
"DateOffsetValue": 2, // how many of those units: here, due 2 days after the start point
"Time": "1900-01-01T09:00:00Z", // time of day for the due date; only the time is used, the date part is ignored
// The reminder (alarm) fires this far BEFORE the due date.
"AlarmOffsetUnit": 2, // unit for the alarm offset: 1 = Minutes, 2 = Hours, 3 = Days, 4 = Weeks
"AlarmOffsetValue": 6 // how many of those units: here, 6 hours before the due date
}
}
}3 - Add task template 2 (Sequence 2)
Second task. Because the workflow is sequential, this task is created only after task 1 is completed, and its due date is measured from that completion date (here 5 days after), not from the workflow start.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
// A workflow needs at least two task templates before it can start.
"WorkflowTaskTemplate": {
"Data": {
"Key": null,
"WorkflowKey": "{{WF_Key}}",
"Sequence": 2,
"Subject": "Send the welcome package",
// This time we assign to whoever starts the workflow. See task template 1 for all AssignedToExpression options.
"AssignedToExpression": "WorkflowStarter",
"Priority": "Hi",
"IconType": 1,
"DateOffsetUnit": 3, // 3 = Days, 4 = Weeks, 5 = Months
"DateOffsetValue": 5, // due 5 days after task 1 is completed (the start point for a later task is the previous task's completion)
"Time": "1900-01-01T09:00:00Z", // time of day only; the date part is ignored
"AlarmOffsetUnit": 2, // 1 = Minutes, 2 = Hours, 3 = Days, 4 = Weeks
"AlarmOffsetValue": 6 // reminder 6 hours before the due date
}
}
}4 - Create a company to run it on
Creates the AbEntry the workflow runs on and saves its key as the parent for the Start step. We set an Account Manager (here the built-in MASTER user; use any active user's UID) so that tasks assigned with "AccountManager" have someone to go to. See AbEntry → HowTo's for more ways to create and find records.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
// A workflow runs against an AbEntry. Here we create a sample company and give it an Account Manager,
// which the "AccountManager" task assignment needs in order to resolve when the workflow starts.
"AbEntry": {
"Data": {
"Key": null,
"Type": "Company",
"CompanyName": "Guide Sample Co {{$randomInt}}",
"AccountManager": "VXNlcglNQVNURVI="
}
},
"Compatibility": {
"AbEntryKey": "2.0"
}
}5 - Start the workflow
// POST https://api.maximizer.com/octopus/WorkflowStart
// Authorization: Bearer <token>
{
// Starts the workflow on the record and creates the first task.
// The same workflow cannot be started twice on the same record while it is still running.
"Workflow": {
"Data": {
"Key": "{{WF_Key}}",
"ParentKey": "{{WF_ParentKey}}"
}
}
}6 - Track progress (read the workflow instance)
The workflow instance is the live record of the run. WorkflowTaskTemplateKey is the step it is currently on, and Completed becomes true only once the last task is finished. WorkflowInstance is read-only.
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"WorkflowInstance": {
"Scope": {
"Fields": {
"Key": 1,
"WorkflowKey": 1,
"WorkflowTaskTemplateKey": 1,
"ParentKey": 1,
"Completed": 1,
"Creator": 1,
"CreationDate": 1
}
},
"Criteria": {
"SearchQuery": {
"WorkflowKey": { "$EQ": "{{WF_Key}}" }
}
}
}
}7 - Read the current task
Reads the tasks the workflow created for this run. We filter by WorkflowKey and pick the first one still open, then save its key to complete next. Note the Configuration.Drivers override: it reads tasks with the SQL searcher so the workflow fields (WorkflowKey, WorkflowTaskTemplateKey, WorkflowInstanceKey) come back on the task. See Task V2 → HowTo's for more on tasks.
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"Task": {
"Scope": {
"Fields": {
"Key": 1,
"Activity": 1,
"Completed": 1,
"AbEntryKey": 1,
"WorkflowKey": 1,
"WorkflowTaskTemplateKey": 1,
"WorkflowInstanceKey": 1
}
},
"Criteria": {
"SearchQuery": {
"WorkflowKey": { "$EQ": "{{WF_Key}}" }
}
}
},
"Compatibility": {
"TaskObject": "2.0"
},
"Configuration": {
"Drivers": {
"ITaskSearcher": "Maximizer.Model.Access.Sql.TaskSearcher"
}
}
}8 - Complete the task to advance
// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
// Completing a task tells the engine to create the next one. Repeat steps 6-8 to walk through the workflow.
// The last task finishes the run (the instance's Completed becomes true). If the workflow has branch actions, the final task also needs Options["Workflow/Result"] - see Task V2 -> HowTo's -> Complete tasks that are part of a workflow.
"Task": {
"Data": {
"Key": "{{WF_TaskKey}}",
"Completed": true
}
},
"Compatibility": {
"TaskObject": "2.0"
}
}2. Workflow with stages
Workflow with stages
A staged workflow groups its task templates into ordered stages. Stages run in their Sequence order, and each stage can run its own tasks one at a time or all at once (IsSequential on the stage). The run moves to the next stage once the current stage's tasks are done, and finishes when the last task of the last stage is completed.
One thing to know: a task template is attached to a stage by setting the template's WorkflowKey to the stage's key (not the workflow's key). The steps below do this for you.
Run the steps in order:
-
Create the workflow
2–3. Add two stages
4–7. Add two task templates to each stage -
Create a company to run it on
-
Start the workflow
-
Track progress (the instance shows the current stage and step)
-
Complete tasks to move through the stages
> For the complete field list on each object, see that object's CRUD and FieldOptions examples. For completing tasks, see Task V2 → HowTo's → Complete tasks that are part of a workflow.
1 - Create the workflow
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
"Workflow": {
"Data": {
"Key": null,
"Name": "Guide staged workflow {{$randomInt}}",
"Description": "Sample staged workflow created from the how-to guide.",
"TAG": "GUIDE_STAGED_{{$randomInt}}",
"HasStages": true // marks this as a staged workflow
}
}
}2 - Add stage 1 (Sequence 1)
Stages run in their Sequence order. IsSequential controls whether the tasks inside this stage are created one at a time or all at once.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
"WorkflowStage": {
"Data": {
"Key": null,
"WorkflowKey": "{{WFS_Key}}",
"Name": "Stage 1 - Intake",
"Description": "First phase of the workflow.",
"Sequence": 1,
"IsSequential": true // run this stage's tasks one at a time
}
}
}3 - Add stage 2 (Sequence 2)
The run reaches this stage only after every task in stage 1 is completed.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
"WorkflowStage": {
"Data": {
"Key": null,
"WorkflowKey": "{{WFS_Key}}",
"Name": "Stage 2 - Review",
"Description": "Second phase of the workflow.",
"Sequence": 2,
"IsSequential": true
}
}
}4 - Add task template to stage 1 (Sequence 1)
First task of stage 1. Sequence orders the tasks within the stage. See WorkflowTaskTemplate → FieldOptions and CRUD for the full field list.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
// Attach a template to a stage by setting WorkflowKey to the STAGE's key (not the workflow's key).
"WorkflowTaskTemplate": {
"Data": {
"Key": null,
"WorkflowKey": "{{WFS_Stage1Key}}",
"Sequence": 1,
"Subject": "Collect the client's documents",
// AssignedToExpression - who the created task is assigned to. Three forms:
// "AccountManager" -> the AbEntry's Account Manager (an expression, resolved when the task is created)
// "WorkflowStarter" -> the user who starts the workflow (an expression)
// a user UID -> a specific user by login ID, e.g. "MASTER"
"AssignedToExpression": "AccountManager",
"Priority": "Hi",
"IconType": 1,
// Due date = a start point + (DateOffsetValue x DateOffsetUnit). Start point = workflow/stage start, or the previous task's completion date.
"DateOffsetUnit": 3, // 3 = Days, 4 = Weeks, 5 = Months
"DateOffsetValue": 2, // due 2 units after the start point
"Time": "1900-01-01T09:00:00Z", // time of day only; the date part is ignored
"AlarmOffsetUnit": 2, // 1 = Minutes, 2 = Hours, 3 = Days, 4 = Weeks
"AlarmOffsetValue": 6 // reminder fires this far before the due date
}
}
}5 - Add task template to stage 1 (Sequence 2)
Second task of stage 1, still attached to the stage 1 key.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
"WorkflowTaskTemplate": {
"Data": {
"Key": null,
"WorkflowKey": "{{WFS_Stage1Key}}",
"Sequence": 2,
"Subject": "Verify the documents",
"AssignedToExpression": "WorkflowStarter", // goes to the user who starts the workflow (see step 4 for all options)
"Priority": "Hi",
"IconType": 1,
"DateOffsetUnit": 3, // 3 = Days, 4 = Weeks, 5 = Months
"DateOffsetValue": 3,
"Time": "1900-01-01T09:00:00Z",
"AlarmOffsetUnit": 2, // 1 = Minutes, 2 = Hours, 3 = Days, 4 = Weeks
"AlarmOffsetValue": 6
}
}
}6 - Add task template to stage 2 (Sequence 1)
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
// Attached to stage 2 by using the stage 2 key.
"WorkflowTaskTemplate": {
"Data": {
"Key": null,
"WorkflowKey": "{{WFS_Stage2Key}}",
"Sequence": 1,
"Subject": "Review and approve",
"AssignedToExpression": "MASTER", // a specific user by UID (login ID), here the built-in MASTER user; see step 4 for the expression options
"Priority": "Hi",
"IconType": 1,
"DateOffsetUnit": 3, // 3 = Days, 4 = Weeks, 5 = Months
"DateOffsetValue": 2,
"Time": "1900-01-01T09:00:00Z",
"AlarmOffsetUnit": 2, // 1 = Minutes, 2 = Hours, 3 = Days, 4 = Weeks
"AlarmOffsetValue": 6
}
}
}7 - Add task template to stage 2 (Sequence 2)
Last task of the last stage. Completing this one finishes the whole workflow.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
"WorkflowTaskTemplate": {
"Data": {
"Key": null,
"WorkflowKey": "{{WFS_Stage2Key}}",
"Sequence": 2,
"Subject": "Notify the client of the outcome",
"AssignedToExpression": "AccountManager", // back to the AbEntry's Account Manager (see step 4 for all options)
"Priority": "Hi",
"IconType": 1,
"DateOffsetUnit": 3, // 3 = Days, 4 = Weeks, 5 = Months
"DateOffsetValue": 3,
"Time": "1900-01-01T09:00:00Z",
"AlarmOffsetUnit": 2, // 1 = Minutes, 2 = Hours, 3 = Days, 4 = Weeks
"AlarmOffsetValue": 6
}
}
}8 - Create a company to run it on
The AbEntry the workflow runs on. We set an Account Manager (here the built-in MASTER user; use any active user's UID) so tasks assigned with "AccountManager" have someone to go to. See AbEntry → HowTo's for more ways to create and find records.
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
// The AbEntry the workflow runs on. We set an Account Manager so that "AccountManager" tasks can resolve.
"AbEntry": {
"Data": {
"Key": null,
"Type": "Company",
"CompanyName": "Guide Sample Co {{$randomInt}}",
"AccountManager": "VXNlcglNQVNURVI="
}
},
"Compatibility": {
"AbEntryKey": "2.0"
}
}9 - Start the workflow
// POST https://api.maximizer.com/octopus/WorkflowStart
// Authorization: Bearer <token>
{
// Starts the workflow and creates the first task(s) of stage 1.
"Workflow": {
"Data": {
"Key": "{{WFS_Key}}",
"ParentKey": "{{WFS_ParentKey}}"
}
}
}10 - Track progress (read the workflow instance)
For a staged workflow the instance shows both WorkflowStageKey (the current stage) and WorkflowTaskTemplateKey (the current step). Watch WorkflowStageKey move from stage 1 to stage 2 as you complete tasks. Completed becomes true after the last task of the last stage.
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"WorkflowInstance": {
"Scope": {
"Fields": {
"Key": 1,
"WorkflowKey": 1,
"WorkflowStageKey": 1,
"WorkflowTaskTemplateKey": 1,
"ParentKey": 1,
"Completed": 1
}
},
"Criteria": {
"SearchQuery": {
"WorkflowKey": { "$EQ": "{{WFS_Key}}" }
}
}
}
}11 - Read the current task
Reads the open task for the current stage and saves its key so the next step can complete it. The Configuration.Drivers override reads tasks with the SQL searcher so the workflow fields come back on the task.
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"Task": {
"Scope": {
"Fields": {
"Key": 1,
"Activity": 1,
"Completed": 1,
"AbEntryKey": 1,
"WorkflowKey": 1,
"WorkflowTaskTemplateKey": 1,
"WorkflowInstanceKey": 1
}
},
"Criteria": {
"SearchQuery": {
"WorkflowKey": { "$EQ": "{{WFS_Key}}" }
}
}
},
"Compatibility": {
"TaskObject": "2.0"
},
"Configuration": {
"Drivers": {
"ITaskSearcher": "Maximizer.Model.Access.Sql.TaskSearcher"
}
}
}12 - Complete the task to advance
// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
// Completing a task creates the next one. When a stage's tasks are all done, the run moves to the next stage.
// Repeat steps 10-12 until the last task of the last stage is completed and the instance shows Completed = true.
// If the workflow has branch actions, the final task also needs Options["Workflow/Result"] - see Task V2 -> HowTo's -> Complete tasks that are part of a workflow.
"Task": {
"Data": {
"Key": "{{WFS_TaskKey}}",
"Completed": true
}
},
"Compatibility": {
"TaskObject": "2.0"
}
}MetaData
Read Workflow metadata (simple)
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"Schema": {
"Scope": {
"Fields": 1
},
"Criteria": {
"SearchQuery": {
"Key": {
"$TREE": "/Workflow"
}
}
}
},
"Compatibility": {
"SchemaObject": "1.0"
}
}Read Workflow metadata (more)
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"Schema": {
"Scope": {
"Fields": {
"Key": 1,
"Alias": 1,
"Type": 1,
"Name": 1,
"AppliesTo": 1,
"Sortable": 1,
"Queryable": 1,
"Mandatory": 1,
"Attributes": 1,
"DisplayValue": 1
}
},
"Criteria": {
"SearchQuery": {
"Key": {
"$TREE": "/Workflow"
}
}
}
},
"Compatibility": {
"SchemaObject": "1.0"
}
}Workflow CRUD
Create - Workflow
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
"Workflow": {
"Data": {
"Key": null, // Will be generated automatically
"Name": "KYC", // Mandatory - Unique
"Description": "This is the workflow for Annual KYC review",
"TAG": "KYC_WORKFLOW" // Optional - Unique
}
}
}Update - Workflow
// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
"Workflow": {
// If the workflow has been used already we don't allow update (for now)
"Data": {
"Key": "V29ya2Zsb3cJMjUwODE0MDAwMDAwMDAxMTM4MTUwV0YJMA==", // Mandatory
"Name": "New KYC",
"Description": "This is the new workflow for Annual KYC review"
}
}
}Read - Workflow
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"Workflow": {
"Scope": {
"Fields": {
"Key": 1,
"Name": 1,
"Description": 1,
"IsSequential": 1,
"HasStages": 1,
"TAG": 1
}
},
"Criteria": {
"SearchQuery": {},
"Top": 3
}
}
}Delete - Workflow
// POST https://api.maximizer.com/octopus/Delete
// Authorization: Bearer <token>
{
"Workflow": {
// If the workflow has been used already we don't allow deletion (for now)
"Data": {
"Key": "UHJvY2Vzc1N0YWdlU2V0dXAJMjUwMTAyMDAwMDAwMDE4NTg0Njg0UFMJMg==" // Mandatory
}
}
}Start - Workflow
// POST https://api.maximizer.com/octopus/WorkflowStart
// Authorization: Bearer <token>
{
// Creates the first task.
// Ensures the same workflow is not already active for the provided ParentKey, or for the combination of ParentKey and WithKey when WithKey is provided.
// If WithKey is provided, verifies that the parent key of the UdoKey matches the ParentKey sent here.
// Ensures the workflow task templates have the correct sequence.
"Workflow": {
"Data": {
"Key": "V29ya2Zsb3cJMjUwODI4MDAwMDAwMDAyNDYyMTI5V0YJMA==", // Mandatory
"ParentKey": "QWJFbnRyeQkyMjA1MDUyNTIyMjczODY2NDAwMjlDCTA=", // Mandatory, for now only supports AbEntryKey
"WithKey": "VWRvCTI1MTEwNzAwMDAwMDAwNjE4MjE0M1VPCTA=" // Optional, for now only supports UdoKey
}
}
}