# User Guide This guide explains how to build and use applications in Conductor. Server installation, TLS, backups, and upgrades belong in the [Installation Guide](INSTALL.md) and [Operations Guide](OPERATIONS.md). Account, credential, and publication administration belong in the [Administrator Guide](ADMIN_GUIDE.md). ## Roles and entry points | Visitor | What they can do | |---|---| | Administrator | Author projects, manage stored credentials, test REST actions, inspect execution history, manage users, and publish applications. | | User | Sign in, open restricted or public applications from the application catalog, and change their own password. | | Anonymous visitor | Open public applications by URL. | There is no public registration page. An administrator creates accounts. Conductor ships with no default username or password. On a brand-new installation, the first visitor sees **Set up Conductor** instead of the sign-in form. That one-time screen creates the initial administrator: enter a unique username, an optional display name and contact email, and a confirmed password of at least 12 characters. The new administrator is signed in automatically. If the screen is not present, setup has already been completed; ask an existing administrator for an account. ## Sign in and change your password Open the HTTPS URL supplied by your administrator and sign in with your username and password. After five failed attempts for the same username and client address within one minute, login is temporarily throttled. Users can expand **Change my password** below the application catalog. The new password must contain at least 12 characters and differ from the current password. A successful change keeps the current browser signed in and revokes the user's other sessions. Administrators reset passwords from **Users**. Profile fields are administrator-managed in this release. ## Administrator workspace Administrators see these areas in the sidebar: - **Visual Editor** builds pages and components. - **JSON Editor** edits the same canonical project document directly. - **Preview** runs the current in-memory project without saving runtime state. - **Actions & Bindings** defines REST requests, stored-credential references, variables, and response mappings. - **Execution History** shows recent sanitized REST executions. - **Publishing** creates and updates runnable application snapshots. - **Users** manages local accounts and sessions. The **Projects** sidebar item is a placeholder in v1.0.0. Create, save, and load projects from the toolbar in **Visual Editor** or **JSON Editor**. ## Build a first application This small workflow creates a page with an input, a button, and a JSON result. 1. Open **Visual Editor** and select **New**. 2. Click the project name in the toolbar and give it a meaningful name. 3. In the page ribbon, set the page name and URL slug. Slugs use lowercase letters, numbers, and single hyphens, such as `lookup`. 4. Click **Text Input**, **Button**, and **JSON Viewer** in the component palette. Move or resize them on the canvas and give each a clear name in **Selection**, such as `itemId`, `lookupButton`, and `resultViewer`. 5. Open **Actions & Bindings**, expand **REST Actions**, and add an action. Choose the HTTP method, enter an absolute `http` or `https` endpoint, and use `{{components.itemId.value}}` in a supported request field when the endpoint needs the entered value. 6. Return to **Visual Editor**, select the button, and assign its click event to the action. 7. In **Actions & Bindings**, add a response binding from `actions..response.body` to `components.resultViewer.value` with trigger `onSuccess`. 8. Open **Preview**, enter a value, and click the button. Resolve any validation errors before continuing. 9. Select **Save**. Later edits use **Update**. The dot beside the project name means there are unsaved changes. 10. Ask an administrator to publish the saved project, or use **Publishing** if you are an administrator. Use a harmless test API while learning. A Conductor action is a real server-side HTTP request. ## Projects and unsaved changes - **New** starts a new in-memory document. - **Save** validates and creates the project in SQLite. - **Update** validates and replaces the saved project. - **Load** opens the project picker and loads a saved project. - Clicking the project name in the toolbar renames it. New and Load ask before discarding unsaved changes. Failed validation, saving, or loading leaves the last valid in-memory project intact. Preview includes current unsaved edits, but Preview activity never saves component values, responses, loading states, or errors. ## Pages Use the Visual Editor page ribbon to: - add, duplicate, reorder, or delete pages; - change the page name and URL slug; - choose the default page; - include or hide a page in automatic navigation; and - assign page lifecycle actions. A project always has at least one page. Page slugs must be unique. Hiding a page from navigation is not an access-control rule; anyone allowed to use the application can still open its direct URL. Lifecycle actions behave as follows: - `onLoad` runs on the first entry to the page during the current loaded session. - If a page has no `onLoad` action, `onEnter` is the first-entry fallback. - `onEnter` runs when the visitor returns to an already visited page. - A full browser reload starts a new runtime session. ## Components Click a palette item to add it to the active page. Select a component to edit its name, position, size, visibility, type-specific properties, and basic appearance. Component names must be unique within a page. Project-wide unique names are recommended because request templates and binding paths identify components by name without a page qualifier. | Component | Main use | |---|---| | Label | Static text or a response-bound value. | | Button | Run one REST action or navigate to another page when clicked. | | Text Input | Collect one line of text for a request template. | | Text Area | Collect or display multi-line text. | | Checkbox | Collect or display a Boolean value. | | Radio Group | Choose one configured option. | | Dropdown | Choose one configured option; its option list can be populated by a response binding. | | Table | Display configured or response-bound rows and expose the selected row at runtime. | | JSON Viewer | Display formatted configured data or a REST response. | | Status Panel | Display a value plus loading or error state. | | Card | Display a titled block of content. | A button's guided click event runs an action or navigates; it does not do both. Deleting a referenced component displays the references that will be affected before confirmation. ## REST actions and request values REST actions are project-level and support `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. Each action defines: - a stable action ID, name, and optional description; - an absolute endpoint URL; - an authentication type and compatible stored-secret reference when required; - allowed headers, query parameters, and path substitutions; and - an optional request body for methods that send one. Use the editor's template suggestions to place runtime values in supported request fields: ```text {{components.itemId.value}} {{variables.environment}} ``` Component values resolve from the page that invoked the action. Variables resolve by name. Treat a page-scoped variable as belonging only to its declared page; v1.0.0 does not yet enforce that ownership when resolving every runtime reference. Do not put passwords, tokens, or API keys into templates, headers, URLs, or project JSON; select a compatible stored secret instead. **Test Action** runs the current action configuration through the backend proxy. It is useful for static requests. It does not inject interactive Preview values, so exercise template-driven requests from **Preview**. Conductor blocks private and internal destinations unless the server operator has approved the exact origin. See [Proxy Security](PROXY_SECURITY.md) for allowed headers, limits, redirects, and error behavior. ## Stored credentials Administrators create credentials in **Actions & Bindings → Secrets**. Supported shapes are Basic authentication, Bearer token, API-key header, and API-key query parameter. Credential values are encrypted server-side and are never displayed again after submission. Projects store only opaque references. Replacing a value requires entering the new credential fields once; deleting a credential is blocked while a saved project action references it. More detail is in the [Administrator Guide](ADMIN_GUIDE.md#manage-stored-credentials) and [Secrets Security Model](SECRETS.md). ## Variables and response bindings Variables have a type (`string`, `number`, `boolean`, `object`, or `array`), an optional default, and either global or page scope. Keep page-scoped variables on their declared page. Runtime values survive navigation within one loaded session and reset on full reload. They are not written back to the project document. Response bindings run after a successful action and use ordinary dot-separated object paths, not JSONPath. Common sources are: ```text actions..response actions..response.body actions..response.body. ``` Supported targets are: | Target | Compatible destination | |---|---| | `components..value` | Label, Text Area, Checkbox, Radio Group, JSON Viewer, or Status Panel | | `components..options` | Dropdown; response must be an array of strings or string `{ "label": ..., "value": ... }` objects | | `components..rows` | Table; response must be an array of objects | | `variables.` | A declared runtime variable; the response value is assigned without coercion or a runtime type check | Use `onSuccess` for action-response bindings. Table selection uses `components..selectedRow` with `onChange`. The guided response-binding editor creates action-response bindings only; use the **JSON Editor** to add a Table-selection binding, and keep the Table name project-wide unique. Wildcards, filters, transforms, action chains, and arbitrary reactive graphs are not executed in v1.0.0. ## Preview and validation Preview is a read-only runtime view of the current canonical project. It can change ephemeral component and variable values while the Preview remains loaded, but it does not alter or save the authored defaults. Validation summaries appear in the Visual Editor, Actions & Bindings, JSON Editor, and Preview. Errors block Apply, Save, and Publish. Warnings usually identify compatibility fields that remain readable but are not executed. Fix the named path or reference and validate again. ## JSON Editor The JSON Editor edits the same project document as the Visual Editor. 1. Make changes in the text area. 2. Select **Apply** to parse and validate them. 3. Return to the Visual Editor or Preview to inspect the result. 4. Select **Save** or **Update** to persist it. **Revert** discards the JSON Editor's local draft and returns to the current in-memory project. Invalid JSON or semantic references never replace the last valid project. The canonical format is documented in [Project Schema](SCHEMA.md); prefer the visual editors for shapes they support. ## Published applications Publishing creates an immutable snapshot of a saved project: - `/apps/` opens its default page. - `/apps//` opens a refreshable deep link. - Public applications are available anonymously and may contain only anonymous REST actions. - Restricted applications are available to any enabled signed-in user and may use stored credentials. Saving the source project does not change the live snapshot. Use **Republish** to release the current saved version. **Unpublish** makes the URL unavailable without deleting the source project. See the [Administrator Guide](ADMIN_GUIDE.md#publish-and-withdraw-applications). ## Troubleshooting and limitations - If an action is blocked, read its safe error code and ask the server operator before requesting an internal-origin exception. - If a deep link returns a proxy 404, the reverse proxy is not forwarding all paths to Conductor. - If an old interface remains after an upgrade, perform a hard refresh. - If Apply, Save, or Publish fails, correct the validation path shown in the interface; the last valid project remains intact. See [Troubleshooting](TROUBLESHOOTING.md) for remedies and [Known Limitations](KNOWN_LIMITATIONS.md) for the full v1.0.0 boundary.