File handlers

When files are dropped inside the monitor directory the file is picked up by a specific handler based on the filename and extension. For excel both xls and xlsx are supported.

When the file is handled by the service, the file is renamed to: active.<filename>. When the handler is finished the file is moved to the completed or error directory.

Pages (excel)

Use this format to create/update site pages. The filename should contain PageSet and format is xls(x)/csv.

The following columns are required:

• Url or MatterCode (/ClientCode)
• PageSet or PageSets or both.
• Additional columns are converted to properties (can be used as variables in the pageset)

The page that is defined in pageset is created/updated in the site via the url or via the client/mattercode and will be the homepage.

The pages that are defined in pagesets are created/updated in the site via the url or via the client/mattercode.

QuickLaunchNavigation (excel)

Use this format to create/update the QuickLaunchNavigation in a site. The filename should contain QuickLaunchNavigation and format is xls(x)/csv.

The following columns are required:

• Url or MatterCode (/ClientCode)
• SiteSet
• Additional columns are converted to properties (can be used as variables in the siteset)

The QuickLaunchNavigation that is defined in the siteset is created/update in the site via the url or via the client/mattercode. Only items that are marked as Remove are removed.

TopNavigation (excel)

Use this format to create/update the TopNavigation in a site. The filename should contain TopNavigation and format is xls(x)/csv.

The following columns are required:

• Url or MatterCode (/ClientCode)
• SiteSet
• Additional columns are converted to properties (can be used as variables in the siteset)

The TopNavigation that is defined in the siteset is created/update in the site via the url or via the client/mattercode. Only items that are marked as Remove are removed.

CopySearchSchema (excel)

Use this format to copy a search schema from one site collection to another. The filename should contain CopySearchSchema with format xls(x)/csv.

The following columns are available:

• Origin (required)
• Target (required)
• Force
• CreateCrawledProperties
• Debug

Origin is the site collection URL from which the search schema is copied. Example: https://tenant.sharepoint.com/sites/siteCollection1

Target is the site collection URL where the search schema will be applied. Example: https://tenant.sharepoint.com/sites/siteCollection2

Admin sites (URLs containing -admin) are blocked as targets to prevent accidental tenant-level schema changes.

Force is a boolean used when the target site collection already has a search schema and it needs to be overwritten. When Force is False (default), the handler aborts if the target already has any aliases, managed properties, or overrides. When Force is True, the existing schema is overwritten. Aliases from the old target schema that are not present in the origin schema are reported as orphaned and must be removed manually. Example: True

CreateCrawledProperties is a boolean that controls whether crawled properties referenced in the origin schema should be auto-created on the target site. When set to True, non-implicit crawled properties have their SchemaId reset to 0 so SharePoint creates them during import. This is useful when the target site does not yet have the crawled properties that the managed properties in the schema are mapped to. Example: True

Debug is a boolean that outputs the raw XML of the origin search schema to the console for troubleshooting purposes. Example: True

Workflow

1. Export search schema from the Origin site
2. Export search schema from the Target site
3. If Force is False, verify the target has no existing schema; otherwise detect orphaned aliases
4. Apply the origin schema to the target (with optional crawled property creation)
5. Re-export the schema from the target and verify the import was faithful (aliases and crawled properties)
6. Report success with any orphaned aliases, or report specific missing items on verification failure

Retry behavior

The schema import automatically retries up to 3 times with exponential backoff when SharePoint returns a "Service unavailable" error. Each retry uses a fresh client context to avoid dirty state from a failed request. This handles transient failures that can occur during search schema operations on SharePoint Online.

Verification

After applying the schema, the handler re-exports the search schema from the target site and compares it against the origin. It checks that all expected aliases (by name and PID) and crawled properties are present. If any are missing, the operation is reported as failed with the specific missing items listed.