D.T Docs - #2 - Document Admin Workflows System

disciple-tools-theme/wp-admin/dt-settings/index.md

@@ -0,0 +1,10 @@
+# Settings (D.T)
+
+Settings (D.T) is the Disciple.Tools area in the WordPress Admin where you configure site-wide options. From the left sidebar, click **Settings (D.T)** to see the available tabs.
+
+## Available Settings
+
+- **[Storage](./storage/storage.md)**: Configure external S3-compatible storage for profile pictures, record images, and voice messages.
+- **[Workflows](./workflows/workflows.md)**: Automate actions when records are created or fields are updated (triggers, conditions, and actions).
+
+Each tab is described in its own section. Open the **Workflows** tab in the admin to manage workflows; open the **Storage** tab to manage storage connections.

disciple-tools-theme/wp-admin/dt-settings/storage/storage.md

@@ -106,3 +106,4 @@ If the test fails, check your credentials and bucket settings. For detailed setu
 - [Set up your S3 storage connection →](./storage-setup.md)
 - [Learn about user file upload features →](./storage-usage.md)
 - [Troubleshoot common issues →](./storage-troubleshooting.md)
+- [Configure Workflows (automation) →](../workflows/workflows.md)

disciple-tools-theme/wp-admin/dt-settings/workflows/accessing-workflows.md

@@ -0,0 +1,26 @@
+# Accessing the Workflows Page
+
+The Workflows page is part of Disciple.Tools Settings. You need permission to access Settings (D.T) to see and use Workflows.
+
+## From the Disciple.Tools Frontend
+
+1. Log in to your Disciple.Tools site with an account that has administration access.
+2. Open the WordPress Admin dashboard:
+   - On desktop: click the settings icon (⚙️) and select **Admin**.
+   - On mobile: tap the menu icon (☰) and select **Admin**.
+3. In the main left sidebar, click **Settings (D.T)**.
+4. Click the **Workflows** tab.
+
+![Workflows menu location in sidebar](./imgs/workflows-menu-location.png)
+
+## From the WordPress Admin Directly
+
+1. Log in to your site at the WordPress Admin URL (often `/wp-admin/`).
+2. In the left sidebar, click **Settings (D.T)**.
+3. Click the **Workflows** tab.
+
+The Workflows page URL includes `page=dt_options` and `tab=workflows`. If you have a direct link to Settings (D.T), you can add `&tab=workflows` to open Workflows.
+
+## Who Can Access Workflows?
+
+Only users with permission to manage Disciple.Tools settings can open the Workflows page. If you do not see **Settings (D.T)** or the **Workflows** tab in the sidebar, your role does not have access. Ask your site administrator to adjust your permissions if you need to manage workflows.

disciple-tools-theme/wp-admin/dt-settings/workflows/creating-a-workflow.md

@@ -0,0 +1,61 @@
+# Creating a Workflow
+
+Follow these steps to create a new workflow in Disciple.Tools. Before you start, decide which record type it applies to, when it should run (trigger), and what conditions and actions you want.
+
+## Prerequisites
+
+- You have opened the Workflows page and selected a post type (for example Contacts or Groups). See [Accessing the Workflows Page](./accessing-workflows.md) and [Workflows Page Overview](./workflows-overview.md).
+- You know the trigger (record created or field updated), the conditions (if any), and the actions you want.
+
+## Step 1: Select the Post Type
+
+If you have not already done so, click one of the post type buttons at the top (for example **Contacts** or **Groups**) so that the workflow list and design panel apply to that record type.
+
+## Step 2: Open the New Workflow Form
+
+Click the **New Workflow** button. The design panel appears with **Step 1** visible.
+
+## Step 3: Choose the Trigger (Step 1)
+
+1. Choose when the workflow should run:
+   - **Record Created**: Runs when a new record of this type is created.
+   - **Field Updated**: Runs when one or more fields on an existing record are updated.
+2. Click **Next** to go to Step 2.
+
+![Step 1: Trigger options](./imgs/workflow-step1-trigger.png)
+
+## Step 4: Add Conditions (Step 2)
+
+Conditions are optional. If you add them, the workflow runs only when every condition is true.
+
+1. In **fields**, select the field to check (for example Status or Assigned to).
+2. In **condition**, select the rule (for example Equals, Contains, or Has any value and not empty). The list of conditions depends on the field type you chose.
+3. If the condition needs a value (for example "Equals" needs a value to compare), enter or select the value in **value**. For "Has any value and not empty" and "Has no value or is empty" you do not enter a value.
+4. Click **Add** to add this condition to the table.
+5. Repeat for each condition you want. You can remove a row using the **Remove** button next to it.
+6. Click **Next** to go to Step 3.
+
+![Step 2: Conditions](./imgs/workflow-step2-conditions.png)
+
+## Step 5: Add Actions (Step 3)
+
+Actions are what the workflow does when the trigger and conditions are satisfied.
+
+1. In **fields**, select the field to change or the special action (for example a field like Status, or Comments).
+2. In **action**, select what to do (for example Updated To, Appended With, or Add Comment). The list of actions depends on the field you chose.
+3. If the action needs a value (for example "Updated To" needs the new value), enter or select it in **value**.
+4. Click **Add** to add this action to the table.
+5. Repeat for each action you want. You can remove a row using the **Remove** button next to it.
+6. Click **Next** to go to Step 4.
+
+![Step 3: Actions](./imgs/workflow-step3-actions.png)
+
+## Step 6: Name and Save (Step 4)
+
+1. In the **Name your workflow** field, enter a clear name so you can find it later in the workflow list.
+2. Check **enabled** if you want the workflow to run. If you leave it unchecked, the workflow is saved but will not run until you enable it.
+3. Click **Save**.
+
+![Step 4: Name and enabled](./imgs/workflow-step4-name.png)
+
+The workflow is now saved. It will run whenever the trigger fires and all conditions are true. To change it later, click its name in the workflow list. For more on triggers and conditions, see [Triggers and Conditions](./workflows-triggers-and-conditions.md). For action types, see [Actions](./workflows-actions.md).

disciple-tools-theme/wp-admin/dt-settings/workflows/default-workflows.md

@@ -0,0 +1,37 @@
+# Default Workflows
+
+Disciple.Tools includes built-in workflows for some record types. These are called **default** workflows. You can turn them on or off, but you cannot edit their trigger, conditions, or actions, or delete them.
+
+## What Default Workflows Exist?
+
+Default workflows depend on your site and record types. Common examples include:
+
+### Contacts
+
+- **Select In Church/Group Following Group Addition**: When the Groups field is updated and has a value, this workflow can append a milestone (for example "In Group") to the contact’s Milestones field. It is useful for tracking when a contact is linked to a group.
+
+### Groups
+
+- **Link Church Health Commitment -> Church Group Type**: When the Health Metrics field contains "Church Commitment," this workflow can set the Group Type to "Church."
+- **Link Church Group Type -> Church Health Commitment**: When the Group Type is set to "Church," this workflow can add "Church Commitment" to the Health Metrics field.
+- **Auto-Adding People Groups**: When the group has members (Members field is set), this workflow can add the people groups from those members to the group’s People Groups field. This uses a custom action so the group’s people groups stay in sync with its members.
+
+The exact names and availability may vary. Open the Workflows page, select **Contacts** or **Groups**, and look at the workflow list. Workflows with **Type** set to **Default** are built-in.
+
+![Workflow list showing Default type](./imgs/workflows-default-list.png)
+
+## Enabling or Disabling a Default Workflow
+
+Default workflows are often **disabled** by default so you can choose which ones to use.
+
+1. Open the Workflows page and select the post type (Contacts or Groups).
+2. In the list, find the default workflow by name and **Type: Default**.
+3. Click the workflow **name** to open the design panel.
+4. In Step 4, check **enabled** to turn the workflow on, or uncheck it to turn it off.
+5. Click **Save**.
+
+The workflow will run only when it is enabled. You cannot change its trigger, conditions, or actions; you can only enable or disable it.
+
+## Why Use Default Workflows?
+
+Default workflows encode common ministry patterns (for example linking group type and health metrics, or syncing people groups from members). Enabling them can save your team from doing the same steps manually. If you do not need a default workflow, leave it disabled.

disciple-tools-theme/wp-admin/dt-settings/workflows/editing-and-deleting-workflows.md

@@ -0,0 +1,38 @@
+# Editing and Deleting Workflows
+
+You can edit custom workflows, enable or disable any workflow, and delete only custom workflows. Default workflows provided by Disciple.Tools cannot be edited or deleted.
+
+## Editing a Workflow
+
+1. Open the Workflows page and select the correct post type (for example Contacts or Groups).
+2. In the workflow list, click the **name** of the workflow you want to edit. The design panel opens and shows all four steps with the current trigger, conditions, and actions.
+3. Change any step as needed:
+   - **Step 1**: Change the trigger (Record Created or Field Updated).
+   - **Step 2**: Add, change, or remove conditions using the **Add** and **Remove** buttons.
+   - **Step 3**: Add, change, or remove actions using the **Add** and **Remove** buttons.
+   - **Step 4**: Change the workflow name or the **enabled** checkbox.
+4. Click **Save** to store your changes.
+
+![Design panel open for editing](./imgs/workflow-edit-open.png)
+
+When you open a **Default** workflow, the design panel is read-only. You can only change whether it is **enabled** in Step 4 (or via the Enabled column in the list). You cannot change its trigger, conditions, or actions.
+
+## Enabling and Disabling a Workflow
+
+Only **enabled** workflows run when the trigger fires. To turn a workflow on or off:
+
+- **From the list**: The **Enabled** column shows a checkbox for each workflow. The checkbox is display-only in the list; to change the state, open the workflow and use Step 4, or enable/disable when editing a custom workflow in Step 4.
+- **From the design panel**: Open the workflow by clicking its name. In Step 4, check or uncheck **enabled**, then click **Save**.
+
+Default workflows can be enabled or disabled the same way; you just cannot edit their trigger, conditions, or actions.
+
+## Deleting a Workflow
+
+You can delete only **Custom** workflows. Default workflows cannot be deleted.
+
+1. Open the Workflows page and select the post type that contains the workflow.
+2. Click the **name** of the custom workflow you want to delete. The design panel opens.
+3. Click the **Delete** button. The **Delete** button appears only when a custom workflow is open.
+4. Confirm if prompted. The workflow is removed from the list.
+
+After deletion, the workflow no longer runs. Any past activity that was recorded as coming from that workflow may still show in the activity log, often under the name "D.T Workflow" if the workflow name is no longer available.

disciple-tools-theme/wp-admin/dt-settings/workflows/imgs/.gitkeep

@@ -0,0 +1,13 @@
+# Place workflow screenshots here:
+# - workflows-settings-tab.png
+# - workflows-menu-location.png
+# - workflows-overview.png
+# - workflow-step1-trigger.png
+# - workflow-step2-conditions.png
+# - workflow-step3-actions.png
+# - workflow-step4-name.png
+# - workflow-edit-open.png
+# - workflow-conditions-table.png
+# - workflow-actions-table.png
+# - workflows-default-list.png
+# - workflows-activity-log.png

disciple-tools-theme/wp-admin/dt-settings/workflows/workflows-actions.md

@@ -0,0 +1,59 @@
+# Workflow Actions
+
+Actions are what a workflow does when the trigger fires and all conditions are true. The actions available depend on the **field** you select; each field type supports certain action types.
+
+## Action Types by Field Kind
+
+### Update the Field to a Single Value
+
+For fields that store one value (text, number, yes/no, single choice, assigned user, or date):
+
+- **Updated To**: Set the field to the value you choose or enter. For dates you can often choose "Current" to use today’s date.
+- **Unset**: Clear the value. Available for date fields only.
+
+### Add or Remove Items in a List or Connection
+
+For fields that store multiple items (tags, multi-select, connections, locations, communication channels, and similar):
+
+- **Appended With** or **Add**: Add the value you choose to the field (for example add a tag or connect another record). The exact label may be "Appended With" or "Add" depending on the field.
+- **Removal Of**: Remove the value you choose from the field (for example remove a tag or disconnect a record).
+
+### Connection Fields
+
+For connection fields that link to another record type:
+
+- **Connect To**: Add a connection to the record you specify.
+- **Removal Of**: Remove the connection to the record you specify.
+
+### Comments
+
+For the **Comments** field:
+
+- **Add Comment**: Add a comment to the record. You type the comment text in the value field. You can use **tokens** to insert field values (see Comment tokens below).
+
+### Share
+
+For the **Share** field (who the record is shared with):
+
+- **Add Share**: Share the record with the user you select.
+- **Remove Share**: Remove sharing from the user you select.
+
+### Custom Actions
+
+If your site or a plugin provides **custom actions**, they appear in the action list. One built-in example is **Auto-Add People Groups** for Groups: when members are added to a group, it can add their people groups to the group’s people group field. Custom actions are configured by the system; you select them like any other action and set the field and value as shown in the design panel.
+
+![Actions table in workflow design](./imgs/workflow-actions-table.png)
+
+## Comment Tokens
+
+When you use **Add Comment** as an action, you can type comment text that includes **tokens** so Disciple.Tools inserts values from the record. This is useful for noting what changed or for tagging people.
+
+- Use curly braces and the field key: `{field_id}`. For example `{assigned_to}` for the Assigned to field.
+- Only **connection** and **user** type fields support tokens in comments.
+- Disciple.Tools replaces the token with the right value: for user fields it becomes an @mention (e.g. @[User Name](user-id)); for connection fields it becomes the linked record name or an @mention if that record corresponds to a user.
+
+Example: If you type "Hello {assigned_to}, status was updated." and the Assigned to field is set to a user, the comment will show "Hello @[Jane](123), status was updated." so that user is notified.
+
+## Running Order and Loops
+
+Disciple.Tools runs the actions you defined. If an action would not change anything (for example the field already has that value), the system may skip it to avoid unnecessary updates. Workflow runs are attributed in the activity log so you can see that a change came from a workflow rather than a user.

disciple-tools-theme/wp-admin/dt-settings/workflows/workflows-overview.md

@@ -0,0 +1,33 @@
+# Workflows Page Overview
+
+The Workflows page has three main areas: a post type selector, a workflow list, and a design panel where you create or edit a workflow.
+
+## Post Type Selector
+
+At the top you see the question **For what post type?** with buttons for each record type (for example Contacts, Groups). You must select a post type before you can add or change workflows. Click one of the buttons to choose which record type you are working with. The page reloads and shows the workflows for that type.
+
+## Workflow List (Add New Workflows or Modify Existing Ones)
+
+After you select a post type, a section appears titled **Add new workflows or modify existing ones on [Post Type Name]**.
+
+- **New Workflow**: Click this button to create a new workflow. The design panel opens with Step 1.
+- **Table columns**:
+  - **Enabled**: A checkbox indicating whether the workflow is active. Only enabled workflows run when the trigger fires.
+  - **Workflow**: The workflow name. Click a name to open the design panel and view or edit that workflow.
+  - **Type**: Either **Custom** (workflows you created) or **Default** (workflows provided by Disciple.Tools). Default workflows can only be enabled or disabled, not edited.
+  - **Updated Fields**: A list of fields that the workflow changes when it runs (from its actions).
+
+![Workflows page overview with post type and list](./imgs/workflows-overview.png)
+
+## Design Panel (Workflow Steps)
+
+The design panel is hidden until you click **New Workflow** or a workflow name. It shows a four-step flow:
+
+- **Step 1**: Choose the trigger (Record Created or Field Updated).
+- **Step 2**: Add one or more conditions (field, condition type, and value).
+- **Step 3**: Add one or more actions (field, action type, and value).
+- **Step 4**: Enter a name for the workflow and set whether it is enabled. Then click **Save** or **Delete** (Delete appears only for custom workflows).
+
+When you are creating a new workflow, the steps appear one after another as you click **Next**. When you open an existing workflow, all steps are visible so you can review or edit them.
+
+For full steps to create a workflow, see [Creating a Workflow](./creating-a-workflow.md).

disciple-tools-theme/wp-admin/dt-settings/workflows/workflows-triggers-and-conditions.md

@@ -0,0 +1,46 @@
+# Workflow Triggers and Conditions
+
+Triggers define when a workflow runs. Conditions narrow that down so the workflow runs only when certain rules are true.
+
+## Triggers
+
+You choose one trigger per workflow.
+
+### Record Created
+
+The workflow runs when a **new record** of the selected type is created (for example when someone creates a new Contact or Group). All condition checks use the new record’s data. Use this when you want to do something as soon as a record exists (for example set a default status or add a comment).
+
+### Field Updated
+
+The workflow runs when **one or more fields** on an existing record are updated. Disciple.Tools only runs the workflow if at least one of the fields you use in your **conditions** was part of that update (or, for a newly created record, has a value). This avoids running the workflow when unrelated fields change. Use this when you want to react to a specific field change (for example when Status changes to "Active" or when Assigned to is set).
+
+## Conditions
+
+Conditions are optional. If you add conditions, **all** of them must be true for the workflow to run. You can add multiple conditions; each one is a row in the conditions table.
+
+### Condition Types
+
+The condition dropdown depends on the **field** you select. Different field types support different conditions.
+
+- **Equals**: The field value equals the value you enter or select.
+- **Doesn't equal**: The field value does not equal the value you enter or select.
+- **Greater than**: The field value is greater than the value you enter. Available for number and date fields.
+- **Less than**: The field value is less than the value you enter. Available for number and date fields.
+- **Greater than or equals**: The field value is greater than or equal to the value you enter. Available for number and date fields.
+- **Less than or equals**: The field value is less than or equal to the value you enter. Available for number and date fields.
+- **Contains**: The field contains the value (for example text contains a word, or a multi-select list includes an option). Available for text and many list or connection-style fields.
+- **Doesn't contain**: The field does not contain the value.
+- **Has any value and not empty**: The field is set and not empty. You do not enter a value for this condition.
+- **Has no value or is empty**: The field is empty or not set. You do not enter a value for this condition.
+
+### Choosing a Condition Value
+
+For most conditions you must enter or select a **value** (for example the status to compare to, or a number). For **Has any value and not empty** and **Has no value or is empty**, no value is needed; the value field is hidden.
+
+The way you enter the value depends on the field type: some use a text box, some a dropdown of options, some a date picker, and some a search or typeahead for records or locations. Use the control that appears after you select the field and condition.
+
+![Conditions table in workflow design](./imgs/workflow-conditions-table.png)
+
+### Multiple Conditions
+
+If you add more than one condition, the workflow runs only when **every** condition is true. There is no option to run when "any" condition is true; all must match.