Stonly to SharePoint Migration: A Technical Guide

Stonly to SharePoint Migration: A Technical Guide

There is no native migration path from Stonly to SharePoint. No import wizard, no connector, no "Move to SharePoint" button. Stonly stores content as interactive step-by-step guides with branching logic, decision trees, and structured knowledge base articles — a content model with no direct equivalent in SharePoint's page and document library architecture.

Do not confuse Stonly's SharePoint integration with a reverse migration feature. Stonly's integrations page describes SharePoint as a source that feeds knowledge into Stonly AI — not the other way around. (stonly.com) On the SharePoint side, SPMT targets on-prem SharePoint sources (a limitation common to other wiki migrations, like Confluence to SharePoint), and ShareGate's documented import sources are file shares, Google Drive, and Box. (help.sharegate.com) Stonly is not a supported source in either tool. Most Stonly-to-SharePoint projects end up as custom scripts or managed migrations.

This guide covers the real extraction methods, the architectural mismatches between the two platforms, the content types that break or lose fidelity during migration, a decision framework for flattening strategies, and a complete technical workflow for getting it done.

The Structural Mismatch: Why This Migration Is Harder Than It Looks

The fundamental problem is structural, not cosmetic. Stonly is a knowledge management and customer self-service platform that organizes content as interactive guides with steps, choices, and conditional branching. SharePoint is a document management and collaboration platform built around document libraries, lists, and modern .aspx pages rendered with CanvasContent1 JSON.

Stonly's content model is tree-shaped: a single guide can contain dozens of steps linked by decision points, where each path through the tree represents a different user journey. SharePoint has no native concept of branching content. A SharePoint modern page is a flat sequence of web parts — text blocks, images, embeds — laid out top to bottom.

Stonly has three content types that matter here:

• Guides: Step-by-step, branching content with interactive elements like inputs, contact forms, automations, and AI chat. (stonly.com)
• Articles: Single-page content without guide interactivity — these use a simplified editor with no inputs, no next-step blocks, and only inline images and videos. This is the closest match to SharePoint pages. (stonly.com)
• Tours: Step-based content displayed on top of a website or app UI. No SharePoint page equivalent exists.

Here's how specific content types map — and where they break:

Getting Data Out of Stonly

You have three realistic extraction paths. Each has different trade-offs around automation, fidelity, and scale.

Method 1: Stonly Public API (Recommended for Scale)

Stonly's REST API provides endpoints for listing and exporting guides and folders. The API base URL is https://public.stonly.com/api/. You'll need an API key generated from your Stonly team settings under Settings > API. API keys are passed as Bearer tokens in the Authorization header. Stonly uses API key authentication, not OAuth; there is no OAuth flow to configure for server-to-server access.

What the API gives you:

• Guide metadata (title, folder, language, status)
• Step content and structure (rich text, typically HTML)
• Guide hierarchy and folder organization
• Routing logic (which choice leads to which step)

What it does not give you:

• Embedded media files — images, GIFs, and videos are hosted on Stonly's CDN (media.stonly.com) and must be downloaded separately by URL
• Analytics or session data
• Widget configuration or targeting rules

import requests
import time
 
API_BASE = "https://public.stonly.com/api"
API_KEY = "your-stonly-api-key"
 
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}
 
def get_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 5))
            time.sleep(retry_after)
        else:
            response.raise_for_status()
    raise Exception(f"Failed after {max_retries} retries: {url}")
 
# List all guides
guides = get_with_retry(f"{API_BASE}/guides", headers)
 
for guide in guides:
    guide_id = guide["id"]
    detail = get_with_retry(f"{API_BASE}/guides/{guide_id}", headers)
    # Store raw response as JSON for source-of-truth archive
    print(detail)

Two details are easy to miss during extraction. Stonly distinguishes published and draft guides — define upfront whether you're migrating only live content or internal drafts too. (stonly.com) Stonly also supports both a restricted Guide URL and an unrestricted Unique sharing link. Capture both during extraction, because legacy links often live in ticket macros, chatbots, and internal runbooks.

Note on KB widget vs. standalone guides: Stonly guides embedded as knowledge base widgets have a different access model than standalone guides. Widget-embedded guides may be scoped to specific domains or authenticated sessions. These may have different API endpoint behaviors — verify your plan's API access covers both types before building your extraction pipeline.

Method 2: Per-Guide Export (Small Scale Only)

For fewer than ~50 guides, you can export each guide individually from the Stonly editor. Navigate to Settings > Import/Export > Export within each guide. Stonly supports CSV and JSON export formats containing the guide's text content and step structure. PDF exports are available on Business and Enterprise plans. (stonly.com)

Stonly also offers bulk exports in CSV and Parquet formats on request, which can be scheduled to external systems like S3, Azure, GCP, or SFTP.

Limitations:

• Individual export is one guide at a time — no bulk option from the UI
• Embedded media is not included; only text and structural data
• Decision tree branching is represented in the file structure, but converting it to a flat document is manual work

Method 3: Web Scraping (Last Resort)

If your Stonly knowledge base is publicly accessible, you can scrape the rendered HTML. This captures the final presentation but loses all interactive structure — branching, conditional logic, and step-by-step flow are baked into JavaScript and won't appear in a static scrape.

When to use this: Only as a fallback when API access is unavailable and you just need the visible text content.

Transforming Stonly Content for SharePoint

This is where the real engineering work happens. Stonly's interactive model does not map cleanly to SharePoint's flat page model. You need a transformation layer between extraction and loading.

Standard Knowledge Base Articles

Stonly articles that are flat text with images are the simplest to migrate. Extract the rich text content, download embedded images, and create corresponding SharePoint modern pages. This is a straightforward content transfer with minor formatting adjustments.

Flattening Interactive Guides and Decision Trees

This is the hardest part. The correct strategy depends on guide complexity. Use this decision matrix:

Strategy A: Single-page flattening. Convert the Stonly guide into a single SharePoint Modern Page. Each step becomes a Heading 2 (<h2>), and the step's content follows as standard text. Choices (e.g., "If you are on Mac, click here") become HTML anchor links pointing to the respective headings further down the page. This is the preferred strategy for long-term maintainability.

Strategy B: Multi-page web (for complex decision trees). Convert the guide into a SharePoint folder. Each step becomes an individual SharePoint page. Choices become standard hyperlinks pointing to other pages. A guide with 5 binary decision points produces up to 32 unique paths — that's up to 32 pages from a single guide. Without a clear naming convention and navigation structure, users can't find the right page. This creates clutter in your Site Pages library and makes content updates painful. Enforce a strict naming pattern (e.g., {GuideSlug}-step-{N}-{context}.aspx) before migration.

Strategy C: PDF/Word archive (for reference or compliance). Render the guide as a document and upload it to a SharePoint document library. Loses all interactivity but preserves a readable reference copy.

Rough effort estimates by guide type:

• Flat article (no branching): ~15–30 minutes including QA
• Simple guide (≤8 steps, Strategy A): ~45–90 minutes including content decisions and QA
• Complex guide (9–30 steps, Strategy B): ~2–4 hours including naming, linking, and QA
• Decision tree rebuilt in Power Automate: ~4–8 hours depending on action complexity

These are floor estimates for experienced practitioners. If you have 200 complex guides, budget 400–800 hours of content transformation work before writing a single line of migration script.

Handling Embedded Media

Stonly hosts images, GIFs, and videos on its own CDN. These assets are not included in API or CSV exports. Your extraction script must:

1. Parse guide content for media URLs (look for <img>, <video>, and <iframe> tags)
2. Download each asset to a local staging environment
3. Generate a hash (e.g., MD5) per file to prevent duplicate uploads
4. Store a mapping of Old_Stonly_CDN_URL → Local_File_Path

Do not leave image src URLs pointing to Stonly's CDN. Those links will break when your Stonly contract expires, and every image in your SharePoint pages will disappear. This is the single most common post-migration failure.

For a detailed walkthrough, see How to Migrate Images, Attachments & Embeds Without Broken Links.

Handling Multi-Language Content

Stonly supports multiple language versions per guide. SharePoint Online has a multilingual pages feature that creates translation pages linked to a source page. During migration:

• Extract each language variant as a separate content payload
• Create the primary-language page first in SharePoint
• Use the SharePoint multilingual API to create linked translation pages
• Map Stonly's language codes to SharePoint's supported language identifiers

Migrating Permissions

Stonly guides can be restricted to specific users or teams via access controls. SharePoint has two mechanisms for controlling access to migrated content:

Item-level permissions: Break permissions inheritance on individual Site Pages library items and assign unique permissions. This is viable for small numbers of restricted guides (under ~100 items). Beyond that, it creates administrative overhead and approaches SharePoint's 100,000-item limit for breaking/reinheriting permissions on a single list.

SharePoint audience targeting: Available on modern pages via site columns. Audience targeting shows or hides content based on AAD group membership but does not prevent direct URL access — it affects surface visibility only, not security.

Migration mapping approach:

1. During Stonly extraction, capture each guide's access restriction settings (user list or team)
2. Map Stonly user identifiers to Microsoft 365 AAD groups or user UPNs
3. After page creation, apply item-level permissions programmatically via Graph API for genuinely restricted content
4. Use audience targeting for content that should be surfaced differently by role but doesn't require hard access control

There is no automated tool to perform this mapping. It requires a permission manifest built during the content audit phase.

Rewriting Internal Links (Two-Pass Migration)

Stonly guides frequently link to other Stonly guides. During extraction, these links point to https://stonly.com/guide/.... Because SharePoint assigns new URLs based on the site page name, you must execute a two-pass migration:

1. Pass one: Create all pages in SharePoint and capture their new URLs (https://tenant.sharepoint.com/sites/IT/SitePages/Guide.aspx)
2. Pass two: Update the page content, replacing old Stonly URLs with the new SharePoint URLs using your mapping table

If you skip this step, users will click internal links in SharePoint and hit dead Stonly pages.

Loading Content into SharePoint via Microsoft Graph API

Once your data is transformed and media is downloaded, you push it into SharePoint using the Microsoft Graph API.

Uploading Media to Site Assets

Before creating pages, all images must exist in SharePoint. Use the Graph API DriveItem endpoint to upload files to the Site Assets library:

PUT https://graph.microsoft.com/v1.0/sites/{site-id}/drive/items/root:/SiteAssets/StonlyMigration/{filename}:/content

For files under 4 MB, use a single PUT request. Larger files require an upload session with chunked transfer, supporting up to 250 GB per file. (learn.microsoft.com)

Capture the new SharePoint URLs from each upload response. Run a find-and-replace on your transformed HTML to swap Stonly CDN URLs with the new SharePoint Site Asset URLs.

Creating Modern Pages

SharePoint Modern Pages are not simple HTML files. They use a proprietary JSON structure called CanvasContent1 that defines the grid layout and web parts (text blocks, image blocks, etc.). The SitePage resource and CanvasContent1 schema are documented at learn.microsoft.com/en-us/graph/api/resources/sitepage.

import requests
import time
from msal import ConfidentialClientApplication
 
# Authenticate with Microsoft Graph
app = ConfidentialClientApplication(
    client_id="your-app-id",
    client_credential="your-client-secret",
    authority="https://login.microsoftonline.com/your-tenant-id"
)
token = app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])
 
if "access_token" not in token:
    raise Exception(f"Authentication failed: {token.get('error_description')}")
 
headers = {
    "Authorization": f"Bearer {token['access_token']}",
    "Content-Type": "application/json"
}
 
def graph_post_with_retry(url, headers, payload, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)
        if response.status_code in (200, 201):
            return response.json()
        elif response.status_code == 429 or response.status_code == 503:
            retry_after = int(response.headers.get("Retry-After", 10))
            time.sleep(retry_after * (2 ** attempt))  # Exponential backoff
        else:
            response.raise_for_status()
    raise Exception(f"Failed after {max_retries} retries: {url}")
 
page_payload = {
    "name": "how-to-reset-password.aspx",
    "title": "How to Reset Password",
    "pageLayout": "article",
    "promotionKind": "page",
    "canvasLayout": {
        "horizontalSections": [{
            "layout": "fullWidth",
            "columns": [{
                "width": 12,
                "webparts": [{
                    "type": "textBlock",
                    "data": {
                        "innerHTML": "<p>Your migrated content here</p>"
                    }
                }]
            }]
        }]
    }
}
 
result = graph_post_with_retry(
    f"https://graph.microsoft.com/v1.0/sites/{{site-id}}/pages",
    headers,
    page_payload
)

Once the page is created, publish it using the /publish endpoint. If the Site Pages library has content approval enabled, a publish call does not make the page visible until the approval flow completes — account for this in your migration script. (learn.microsoft.com)

SharePoint Throttling and Rate Limits

SharePoint Online throttles API requests using a resource-unit model. The actual rate depends on your tenant size. When throttled, SharePoint returns HTTP 429 (or 503) with a Retry-After header. Your ingestion script must:

• Respect the Retry-After header exactly
• Implement exponential backoff with jitter
• Register the app properly and decorate requests with AppID, AppTitle, and a clear User-Agent string for better service behavior (learn.microsoft.com)

Failing to handle throttling properly will result in temporary tenant-wide bans. Start with conservative request rates (5–10 requests/second) and increase gradually while monitoring for 429 responses.

SharePoint Limits That Bite This Migration

The hard platform limits most relevant to a Stonly migration:

(learn.microsoft.com)

Normalize filenames and shorten deep paths early. A lot of late-stage migration failures come from path lengths and special characters, not API logic.

For more on SharePoint import methods, see How to Import Data into SharePoint: Methods, Limits & Tools.

Configuring SharePoint Search Post-Migration

Migrating content without configuring findability is incomplete migration. SharePoint Search is the primary discovery mechanism for KB content, and migrated pages won't surface optimally without post-migration configuration.

Managed properties and crawled properties: When pages are created via Graph API, standard crawled properties like Title, Author, and LastModifiedTime are indexed automatically. Custom metadata columns (e.g., ProductArea, LegacyGuideId, Audience) need to be mapped to managed properties before they appear in KQL queries or search refiners. Do this in the SharePoint admin center under Search > Manage Search Schema. Allow a full crawl cycle (typically 4–24 hours for SharePoint Online) before testing search results.

Result sources: If your migrated KB content lives in a specific site collection, create a dedicated result source scoped to that site. This lets you build search center experiences or SharePoint search web parts that surface only KB content, not all tenant content.

KQL-backed filtered views: For support agents or users who need to filter by guide type, product area, or audience, build KQL-backed search pages or modern list views against your metadata columns. This replaces Stonly's category navigation. Example KQL: ContentType:"KBArticle" AND ProductArea:"IT" AND Audience:"Agent".

Search schema changes require a crawl: After adding new managed properties and mapping them to crawled properties, the search index must crawl the new content. Plan for a 24-hour delay between publishing migrated pages and those pages surfacing in KQL queries with full metadata.

Step-by-Step Migration Workflow

Here's the technical workflow for a Stonly-to-SharePoint migration at scale:

Step 1: Audit and inventory Stonly content. Catalog total guides, articles, and tours. Note published vs. draft status, steps per guide, decision point count, languages, embedded media count, active data transmission rules, access restrictions per guide, and folder structure. This inventory directly determines which flattening strategy applies to each guide.

Step 2: Design the SharePoint information architecture. Map Stonly folders to SharePoint site sections or document library folders. Map KB categories to SharePoint metadata columns or content types. Decide how interactive guides will be represented using the decision matrix above. Instead of recreating deep Stonly folder hierarchies, consider using site columns (ProductArea, Audience, Language, LegacyGuideId) and driving discovery with KQL-backed search pages or filtered views. Get this mapping right before you migrate a single piece of content. For guidance, see Mastering SharePoint Information Architecture 2026.

Step 3: Build the permission manifest. Map Stonly access restrictions to Microsoft 365 AAD groups or user UPNs. Document which guides require item-level permissions vs. audience targeting. This cannot be automated and must be completed before content is loaded.

Step 4: Extract content via Stonly API. Pull all guide content, metadata, and structural data. Store raw API responses as JSON files — this becomes your source-of-truth archive. Export guide analytics CSVs from Stonly before decommissioning; this data does not migrate.

Step 5: Download embedded media. Parse extracted content for image and video URLs. Download all assets locally with a mapping file connecting each asset to its source guide and step.

Step 6: Transform content for SharePoint. Apply the appropriate flattening strategy per guide using the decision matrix. Convert Stonly rich text to SharePoint-compatible HTML. Generate page payloads with correct CanvasContent1 web part structures. Create metadata mappings for categories, tags, and language variants.

Step 7: Build the SharePoint skeleton. Create the destination site, Site Pages structure, asset libraries, metadata columns, Microsoft 365 groups, and the legacy-map list before bulk loading content. Configure managed properties in the search schema now so they're ready when pages are indexed.

Step 8: Upload to SharePoint via Graph API. Upload media first, then create modern pages with transformed content referencing the new media URLs. Apply metadata, set item-level permissions for restricted content, and publish pages.

Step 9: Rewrite internal links. Execute a second pass to update all internal Stonly URLs to their new SharePoint page equivalents using your legacy-map table.

Step 10: Configure search and navigation. Set up result sources, KQL-backed filtered views, and hub site navigation to replace Stonly's category browsing. Allow 4–24 hours for full crawl before validating search results.

Step 11: Validate and QA. Compare source and target content counts. Spot-check 10–15% of migrated pages for content accuracy. Verify embedded media loads correctly. Test internal links. Confirm multi-language pages are properly linked. Check that pages are published and not stuck in approval. Verify search findability and filtered views return correct results. Test permission boundaries — confirm restricted pages are inaccessible to users outside the target AAD group.

Step 12: Cut over. Freeze editing in Stonly if possible. If you cannot, schedule one last export/load pass for changed items, then switch links. Monitor 404s and permission failures closely in the first few days.

What You Cannot Migrate

Some Stonly features have no SharePoint equivalent and cannot be migrated:

• Interactive branching logic: Must be rebuilt in Power Automate or Power Apps, or accepted as lost
• Data transmission rules: Stonly's ability to push data to Zendesk, Salesforce, etc. on step completion has no SharePoint page equivalent. Rebuild with Power Automate if needed
• Automations and widget event listeners: SharePoint pages do not carry that runtime behavior. (stonly.com)
• Iframe and custom HTML/JS blocks: SharePoint's Graph page API only supports a defined set of web parts. Arbitrary embedded behavior must be redesigned
• Tours and widget triggers: Overlay content meant to run on top of a website — not a SharePoint page feature
• Guide analytics: Session data, step completion rates, and performance metrics stay in Stonly. Export CSVs for archival before decommissioning. (stonly.com)
• AI Answers configuration: Stonly's AI chatbot training won't transfer. Configure Microsoft Copilot or SharePoint search separately
• Widget targeting rules: Stonly's contextual content delivery based on user data doesn't exist in SharePoint. SharePoint audience targeting is a partial substitute
• Permission structures: Stonly access restrictions require manual remapping to AAD groups; there is no automated transfer

Treat content migration, analytics retention, and permission remapping as separate workstreams.

Common Failure Modes

Broken media links. The most common post-migration issue. If you skip the media download-and-reupload step and leave references pointing to media.stonly.com, everything works until your Stonly subscription ends — then every image disappears.

Content sprawl from flattened decision trees. A single complex Stonly guide can generate dozens of SharePoint pages. Without a clear naming convention and navigation structure, users can't find the right page. Enforce naming conventions before migration begins, not after.

Silent broken internal links. If you don't build a URL mapping table (old Stonly guide ID → new SharePoint page URL), internal links break silently. Users won't report them — they'll just stop using the knowledge base.

Throttling during large uploads. Migrating thousands of pages and media files in a single batch will trigger SharePoint throttling. Start at 5–10 requests/second, respect Retry-After headers, and implement exponential backoff. Budget time for retries — a 1,000-guide migration can take 2–3x longer than the content volume alone would suggest.

Pages stuck in approval. If the Site Pages library has content approval enabled, published pages may not be visible to users until approved. This can make a migration look incomplete when the content is actually there. Check approval settings before bulk loading.

Path and filename failures. SharePoint's 400-character decoded path limit and restrictions on special characters cause failures that only surface at scale. Sanitize early.

Search not configured post-migration. Migrated pages exist in SharePoint but surface poorly in search because managed properties aren't mapped, result sources aren't configured, and crawls haven't completed. Users conclude the KB is broken. Schedule search configuration and a full crawl cycle as explicit migration steps.

Permission sprawl. Applying item-level permissions to hundreds of individual pages without a manifest creates an unauditable permission model. Establish AAD groups before migration and apply permissions at the group level.

When a Hybrid Model Makes More Sense

If your real problem is discoverability rather than interactivity, a hybrid approach is often the fastest safe path. Move policies, reference docs, and static KB articles into SharePoint. Keep interactive troubleshooting flows, onboarding guides, or complex decision trees in Stonly for now.

Stonly supports embedding guides on external websites, and its integrations page positions SharePoint as a source for Stonly AI rather than a destination for Stonly content. (stonly.com) That makes a phased model technically sound: centralize static knowledge in SharePoint first, then decide later whether the interactive layer should be rebuilt in Power Apps, Power Automate, or another tool.

A useful heuristic: if more than 30% of your Stonly guides have more than 8 decision points, the interactive content volume is significant enough that a full migration to SharePoint alone will leave meaningful capability gaps. Consider whether Power Apps, Power Automate, or a different interactive documentation platform is a better long-term target for that portion of the estate.

The Practical Path

A Stonly-to-SharePoint migration is fundamentally a content architecture project, not just a data transfer. The technical extraction and upload are solvable problems. The hard part is deciding how to represent interactive, branching content in a flat-page system — and getting that decision right before you move a single guide.

Do the content audit first. Map your information architecture second. Build the permission manifest third. Write the migration scripts fourth. Budget real QA time and a full search crawl cycle at the end — the edge cases in content transformation and search configuration are where migrations quietly fail.

If your scope is small — under 100 simple articles with no complex decision trees — an internal team can handle this with disciplined exports, Graph API loaders, and QA. Beyond that threshold, the content transformation work scales faster than most teams expect. A migration of 500 guides with mixed complexity, multi-language content, deep media dependencies, and access control requirements realistically requires 600–1,200 hours of combined engineering and content work — before factoring in QA, stakeholder review, and cutover coordination.