ZenotiHelp

V2-to-V3 form conversion and adoption

ZTZenoti Docs Team Updated October 26, 2026 8 min readGuide

When your organization has existing forms built with the legacy form builder, you can convert them to the form builder format and adopt the converted versions as your active forms. This article explains how to monitor the conversion pipeline, review converted forms, and adopt them so that all form associations carry over automatically.

Audience: Zenoti administrators who manage form definitions and are transitioning legacy forms to the form builder.


On this page


Before you begin

  • The form builder must be enabled for your organization. Contact your Zenoti representative to confirm this setting is active.

  • Only the following form types are eligible for conversion: Service, Guest, Membership, Tag, and related HTML-based form types. Forms already built in the form builder are not eligible — they are already in the current format.

  • You need the following permissions to adopt converted forms:

    Permission: Edit under CustomFields in the Administrator section of the security role — Required to manage form definitions and perform adoption actions.

  • Verify that the legacy forms you intend to adopt are not currently in use in active appointments before proceeding. Adoption voids the legacy conversion record and migrates all associations to the new form.

  • Forms that have failed conversion repeatedly are excluded from automatic retry after three failed attempts. If a form you need is not converting, see Troubleshooting.

How the conversion pipeline works

The conversion pipeline processes legacy HTML forms in batches and stores the results in a conversion cache. Understanding this pipeline helps you know what to expect when monitoring progress and resolving issues.

The pipeline works as follows:

  1. Batch retrieval — The system retrieves the next batch of unconverted legacy forms across your organization. By default, batches contain up to 25 forms. Forms that have already been successfully converted or that have reached the retry limit are excluded.

  2. Conversion — Each form in the batch is converted to the form builder format. The result — including the converted form definition and a count of components — is stored in the conversion cache.

  3. Status tracking — Each conversion attempt is recorded with one of two statuses:

    • Completed — The form converted successfully and is ready for review and adoption.
    • Failed — The conversion attempt did not succeed. The system records the failure and retries the form in a future batch, up to a maximum of three attempts.
  4. Retry cap — After three failed attempts, a form is excluded from future automatic batch processing. You can still request manual intervention by contacting Zenoti support.

  5. Adoption — Once you review a converted form and are satisfied with the result, you adopt it. Adoption marks the conversion record as adopted, voids it from the active cache, and migrates all form associations from the legacy form to the new form builder version.

Note: The conversion pipeline runs automatically in the background. You do not need to trigger it manually. Your role is to review completed conversions and adopt them when ready.

Steps

Identify forms eligible for conversion

Before reviewing conversion results, confirm which of your legacy forms are candidates for conversion.

  1. Navigate to Configuration > Forms.
  2. Open the form management section and review your existing forms.
  3. Identify forms that were built using the legacy form builder. These are the forms eligible for conversion to the form builder format.
  4. Note the form names and types so you can match them against conversion results.

Tip: Forms built in the form builder already use the current format and do not appear in the conversion candidate list.

Monitor conversion status

The conversion cache stores results for all forms that have been processed. Use this view to track which forms have converted successfully and which require attention.

  1. Navigate to Configuration > Forms.
  2. Locate the section that lists converted forms for your organization.
  3. Review the status of each form:
    • Forms with a Completed status are ready for adoption.
    • Forms with a Failed status have encountered conversion errors. Check the attempt count — forms that have reached three failed attempts require manual intervention.
  4. For each completed form, review the converted form definition to confirm the layout and component count match your expectations before adopting.

Important: Do not adopt a converted form without reviewing it first. Once adopted, the legacy form's associations are migrated to the new form and the conversion record is voided. This action cannot be automatically reversed.

Adopt a converted form

Adoption replaces the legacy form with the converted form builder version and transfers all active form associations.

  1. Navigate to Configuration > Forms.
  2. Locate the converted form you want to adopt in the conversion results list.
  3. Confirm the form status shows Completed.
  4. Select the form and choose the option to adopt it.
  5. Review the confirmation prompt. The prompt will indicate that:
    • The conversion record will be marked as adopted and removed from the active conversion cache.
    • All active form associations and tag form associations from the legacy form will be migrated to the new form builder version.
    • The original legacy associations will be voided.
  6. Confirm the adoption.

Important: Adoption executes the association migration as a single transaction. If any part of the migration fails, the entire operation rolls back and neither the adoption nor the association changes are saved. If you see an error after confirming adoption, no data has changed — retry the adoption or contact Zenoti support.

After adoption, the new form builder version becomes the active form for all associated services and tags. The legacy form remains in your form list but its associations are now voided.

Worked example

Your organization has a legacy intake form called New Guest Health History associated with three services: Swedish Massage, Deep Tissue Massage, and Hot Stone Massage. The form also has two tag form associations.

After the conversion pipeline completes, you see New Guest Health History listed with a Completed status and a component count of 14. You open the converted preview, confirm all fields are present, and proceed with adoption.

After adoption:

  • The form builder version of New Guest Health History is now associated with Swedish Massage, Deep Tissue Massage, and Hot Stone Massage.
  • Both tag form associations now point to the new form builder version.
  • The legacy form's associations are voided.
  • The conversion record is marked as adopted and no longer appears in the active conversion cache.

What happens to form associations after adoption

When you adopt a converted form, the system migrates two types of associations:

Association type What is migrated
Form associations (service forms) All active associations between the legacy form and services are copied to the new form builder version. The original associations are voided.
Tag form associations All active tag form associations for the legacy form are copied to the new form builder version. The original associations are voided.

Both migration types execute within a single transaction. If either migration fails, the entire adoption rolls back.

Note: Only active associations are migrated. Associations that were already voided before adoption are not carried over.

After adoption, verify your form associations by navigating to the relevant service records and confirming the new form builder version appears in the associated forms list.

For service-level custom field data entry and form associations from the service perspective, see Configure service custom fields and forms.

Tips

  • Review converted forms before adopting. The conversion pipeline translates legacy HTML form layouts into form builder components. In most cases the conversion is accurate, but complex legacy layouts may require minor adjustments after adoption. Open the converted form in the form builder to review field order, labels, and conditional logic before committing to adoption.
  • Adopt forms during low-traffic periods. Although adoption is transactional and rolls back on failure, performing adoptions when appointment volume is low reduces the risk of conflicts with forms that are actively being filled.
  • Check component counts as a quick validation signal. The conversion cache records the number of components in the converted form. If the component count is significantly lower than the number of fields in your legacy form, review the converted form carefully before adopting — some fields may not have converted as expected.
  • Adopt forms in batches by type. If you have many legacy forms to convert, work through them by form type (for example, all service forms first, then tag forms). This makes it easier to verify associations after adoption.
  • After adoption, update any form builder customizations. Adoption migrates associations but does not apply any post-conversion edits. If you need to adjust field visibility, conditional logic, or component settings in the adopted form, open it in the form builder after adoption.

Troubleshooting

A form shows a Failed status and is not retrying.

Forms are retried automatically up to three times. After three failed attempts, the form is excluded from future automatic batch processing. To request conversion of a form that has reached the retry limit, contact Zenoti support and provide the form name and type. Support can reset the attempt count to allow the pipeline to retry the form.

The component count in the converted form is lower than expected.

Open the converted form in the form builder and compare it against the legacy form. Some legacy HTML form elements — particularly custom HTML blocks or non-standard field types — may not convert to discrete form builder components. Review each section of the form and add any missing fields manually using the form builder before adopting.

Adoption failed and I see an error message.

Adoption executes as a single transaction. If the association migration fails for any reason, the entire adoption rolls back and no changes are saved. Your legacy form and its associations remain intact. Check that:

  • The legacy form is not currently being filled in an active appointment.
  • You have the required permissions to manage form definitions.

If the error persists after retrying, contact Zenoti support with the form name and the error message you received.

I adopted a form but the new version does not appear on a service.

After adoption, navigate to Configuration > Forms > Form creation > Custom forms, open the adopted form, and verify the form association for the affected service on its SERVICES tab. If the association is missing, it is possible the original legacy association was already voided before adoption and was therefore not migrated. In this case, create the form association manually. For guidance, see Form–Service Association.

A legacy form I expected to see in the conversion list is not appearing.

Only forms of the eligible types (Service, Guest, Membership, Tag, and related HTML-based types) that have not yet been adopted appear in the conversion candidate list. If a form is missing, confirm:

  • The form has not already been adopted (check your active form builder forms).
  • The form is not voided.
  • The form type is eligible for conversion.

If the form meets all criteria and still does not appear, contact Zenoti support.

Was this article helpful?
Your feedback helps us improve our documentation.