# Publish Configuration ## Table of Contents * [Overview](#overview) * [Getting Started](#getting-started) * [Configuring the Publish Target](#configuring-the-publish-target) * [Publish Target Name](#publish-target-name) * [Publish Connection String](#publish-connection-string) * [Clearing the Connection String](#clearing-the-connection-string) * [Publishing Reports](#publishing-reports) * [Publishing a Single Report Page](#publishing-a-single-report-page) * [Publishing a Report Group](#publishing-a-report-group) * [Publishing Forms](#publishing-forms) * [Publishing a Single Form](#publishing-a-single-form) * [Understanding Publish Results](#understanding-publish-results) * [Automatic Configuration Adjustments](#automatic-configuration-adjustments) * [Common Scenarios](#common-scenarios) * [Troubleshooting](#troubleshooting) ## Overview Publish Configuration is the mechanism that moves finalized report and form configuration from the administrative authoring environment to a separate production (public-facing) database. When your agency maintains two environments — one where administrators design and test configuration, and another that end users access — Publish Configuration keeps them in sync. Rather than recreating configuration manually in each environment, administrators trigger a publish action from within the portal. The system generates the necessary database scripts, applies environment-appropriate adjustments automatically, and executes them against the target database in a single transaction. If any part of the operation fails, the target database is left unchanged. Publish Configuration covers two types of content: * **Reports** — report pages, report groups, report lists, containers, and container cards. * **Forms** — form definitions, their questions, and answer choices. ## Getting Started Two separate permissions control publish operations: * **Reports: Publish** — required to publish report configuration (pages, groups, containers, cards). * **Forms: Publish** — required to publish form configuration. Both permissions are sub-permissions under the Reports and Forms sections respectively. If the Publish button is not visible on a report page, report group, or form, contact your administrator to verify that your account has been granted the appropriate permission. Before any publishing can occur, an administrator must configure a publish target in Site Settings. Until that configuration is in place, all publish operations will fail immediately with a message indicating that the connection string is not configured. See [Configuring the Publish Target](#configuring-the-publish-target) for setup steps. ## Configuring the Publish Target The publish target is configured per tenant from the Site Settings page, under the **Publish Settings** section. Both fields described below must be filled in together — you cannot provide one without the other. ### Publish Target Name The **Publish Target Name** is a human-readable label for the destination environment, such as "Production" or "Public Portal." This name appears in confirmation dialogs when an administrator initiates a publish operation, so it should clearly identify where data will be sent. Choose a name that will be unambiguous to anyone with publish permission. ### Publish Connection String The **Publish Connection String** is the SQL Server connection string pointing to the target database. When you enter a new connection string and save, the system validates it before saving: 1. It confirms that the connection can be established. 2. It checks that the target database contains the required tables (`AppStoreMessages` and `AppMessageTypes`). If either check fails, the save is rejected and an error is shown describing the problem. This prevents misconfigured connection strings from silently breaking publish operations later. Because the connection string may contain credentials, it is treated like a password field: * The field displays masked dots when a connection string is already saved, rather than revealing the stored value. * A help message reads: "A connection string is already configured. Leave unchanged to keep existing value." * Submitting the form without changing the field preserves the existing stored value. ### Clearing the Connection String If you need to remove the publish target — for example, to disable publishing temporarily or to reconfigure it — a **Clear existing connection string** button appears below the field whenever a connection string is already saved. Clicking this button, then saving the form, removes the stored connection string. After clearing, publish operations will fail until a new connection string is provided. Note: Clearing the connection string while leaving the Publish Target Name filled in (or vice versa) is not allowed. Both fields must either be provided together or both must be empty. ## Publishing Reports Report configuration can be published at two levels of granularity: individual report pages and report groups. Publishing at a finer level is useful when only a subset of configuration has changed and you want to limit the scope of the operation. ### Publishing a Single Report Page 1. Navigate to the report administration area and open the list of report pages. 2. Locate the page whose configuration you want to publish. 3. Click the **Publish** icon (the upload arrow) in that page's row. 4. A confirmation dialog appears asking: "Are you sure you want to publish the report configuration for **\[page name]** to **\[publish target name]**?" 5. Confirm to proceed. The operation runs in the background. When it completes, a notification appears at the top of the screen showing the result. A successful result message follows this pattern: > Report configuration published successfully. Successfully published N items: N reports, N pages, N groups, and N lists. N transformations applied. ### Publishing a Report Group 1. Navigate to the report group within the report administration area. 2. Locate the group you want to publish. 3. Click the **Publish** icon in that group's row. 4. Confirm the dialog in the same way as publishing a page. 5. The result notification reports how many reports, pages, groups, lists, containers, and container cards were included. ## Publishing Forms Form configuration publishing works in the same pattern as report publishing but scoped to a single form at a time. ### Publishing a Single Form 1. Navigate to the forms administration area. 2. Locate the form whose configuration you want to publish. 3. Use the publish action available on that form's row or detail view. 4. Confirm the dialog when prompted. 5. A result notification confirms the number of forms, questions, and answer choices that were published, along with the count of transformations applied. ## Understanding Publish Results After each publish operation, a notification summarizes what happened. The counts included in the message tell you exactly what was sent to the target database. For **report publishes**, the summary includes: * Number of reports * Number of report pages * Number of report groups * Number of report lists * Number of containers * Number of report group containers * Number of container cards * Number of script transformations applied For **form publishes**, the summary includes: * Number of forms * Number of questions * Number of answer choices * Number of script transformations applied The **script transformations applied** count reflects automatic adjustments made to the configuration before it is written to the target database. See [Automatic Configuration Adjustments](#automatic-configuration-adjustments) for details on what those adjustments are. If the publish operation fails, the notification displays the error message returned by the system. The target database is not partially updated — if any script in the operation fails, the entire batch is rolled back and the target is left unchanged. ## Automatic Configuration Adjustments When configuration is published to the target database, the system automatically adjusts certain settings that should behave differently in a public-facing environment versus the administrative authoring environment. These adjustments happen transparently — you do not need to manually change anything before publishing. Two adjustments are applied: * **Suppression behavior** — any item configured with "User Off" suppression in the authoring environment is changed to "Admin On" suppression in the published copy. This means items that are hidden from regular users in the source remain admin-only in the destination, rather than being completely disabled. * **Report Flags** — any report with flags enabled in the authoring environment has flags disabled in the published copy. The report flags feature is intended for internal use and is turned off before the configuration reaches the public environment. The transformation count in the publish result tells you how many items were affected by these rules in a given operation. A count of zero indicates that no items in the published batch had settings that required adjustment. ## Common Scenarios **Publishing after adding a new report group** After building and testing a new report group in the administrative environment, navigate to that group and use the publish action. Only that group's configuration is sent to the target, leaving other groups unchanged. **Republishing after a configuration change** If you update the layout of a report page or modify a form question, you can republish just the affected page or form. The published scripts use upsert-style operations, so republishing an already-published item updates it in place rather than creating a duplicate. **Validating a new publish connection string** When setting up a new target database, enter the connection string in Site Settings and attempt to save. If the target database is not reachable or is missing required tables, the system rejects the save and displays a specific error message. Address the connectivity or schema issue, then retry. **Temporarily disabling publishing** To prevent any publish operations from succeeding — for example, during a scheduled maintenance window on the target environment — clear the publish connection string in Site Settings. All publish attempts will fail immediately with a "not configured" message until the connection string is restored. ## Troubleshooting **"Publish connection string is not configured in site settings."** The publish target has not been set up, or the connection string was previously cleared. An administrator with access to Site Settings must enter a valid Publish Connection String and Publish Target Name, then save. Once saved, publishing will be available again. **"Both Publish Target Name and Publish Connect String must be provided together, or both must be empty."** You attempted to save Site Settings with one of the two publish fields filled in but not the other. Either provide both the target name and the connection string, or leave both empty. **"Target database is missing required tables: AppStoreMessages, AppMessageTypes"** The connection string is valid and the database is reachable, but it does not have the expected schema. Confirm that the target database is the correct one and that it has been provisioned with the required tables before configuring it as a publish target. **"Connection string is not correct, please verify the connection."** The publish connection string could not be used to open a database connection. Common causes include an incorrect server name, wrong credentials, a firewall rule blocking access, or the target SQL Server not being running. Verify the connection string details and network access, then re-enter the corrected string in Site Settings. **"Error publishing report config: \[error message]"** or **"Error publishing form config: \[error message]"** The publish operation started successfully but an error occurred while applying scripts to the target database. The target database was not modified (the transaction was rolled back). Review the error message for details — common causes include permission issues on the target database, a network interruption mid-operation, or a timeout on a large batch. If the issue is transient, retrying the publish operation is safe. **Publish button not visible** Your user account does not have the Reports: Publish or Forms: Publish permission. Contact your administrator to have the appropriate permission granted. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://nimble.docs.otised.com/guides/publish-configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.