Canvas paragraph text here.
" } } ] } ] } ] } } ``` Key field semantics: `layout` values are `oneColumn`, `twoColumns`, `threeColumns`, or `oneThirdLeftColumn`/`oneThirdRightColumn`. The `width` field on a column is a number from 1–12 following a 12-column grid — full width is 12, a two-column layout uses 6+6 or 8+4. The `type` field on a webpart distinguishes `rte` (rich text), `image`, `spacer`, and embedded app parts. Every webpart requires a unique GUID for `id` — generate these programmatically; reused GUIDs cause page render failures. The `innerHtml` inside `rte` web parts accepts standard HTML (headings, paragraphs, lists, tables) but not arbitrary JavaScript or custom elements. For a checklist block from Slack, the migration choices are: (a) render as a static HTML unordered list with checkbox characters inside the `innerHtml`, (b) create a Microsoft To Do task list separately and embed the To Do web part by reference, or (c) create a Planner plan and embed the Planner web part. Options (b) and (c) require separate API calls to create the task data before the page can reference it. For archival canvases, static HTML is almost always sufficient. Converting to a document library file is computationally cheaper. Slack returns a canvas as HTML or markdown via the `canvases.getContent` endpoint, and Pandoc handles markdown-to-`.docx` conversion for most elements — but with known gaps covered in the Pandoc fidelity section below. ([docs.slack.dev](https://docs.slack.dev/reference/methods/canvases.getContent/)) Most teams push archival canvases into a document library as `.docx` files and reconstruct the 20–50 "living" canvases as site pages by hand or with semi-automated scripts. ## The Metadata Problem: Canvases Have No Fields **A Slack Canvas carries no structured metadata.** No tags, no categories, no custom fields, no content type. It has a title, a creator, a created timestamp, a last-modified timestamp, and that is it. SharePoint is a metadata-driven platform. **Content types** are reusable collections of metadata and behavior for a category of content — a "Project Brief" content type might include columns for Department, Project Code, Status, and Document Owner. **Site columns** are reusable field definitions shared across lists and libraries. **Managed metadata** columns link to hierarchical term sets in the Term Store, where each term has a stable GUID. These structures define how content is organized, filtered, and governed. This mismatch—which is equally challenging when [migrating from SharePoint back to Slack Canvas](https://clonepartner.com/blog/blog/sharepoint-to-slack-canvas-migration-metadata-permissions-guide)—means that every column value in your target SharePoint library must be **derived**, **defaulted**, or **entered by hand**. If you skip that design and start uploading first, required columns leave files checked in without publishing, invisible to end-users until an administrator fills in the missing required fields. ### Strategies for populating metadata | Strategy | Works when | Limitation | |---|---|---| | **Derive from channel** | Canvases are organized by Slack channel and channel names map to departments or projects | Assumes clean channel naming; many canvases live in DMs or are standalone | | **Derive from canvas title** | Titles follow a convention (e.g., "Q3 Sprint Retro — Platform Team") | Fragile; requires regex or NLP parsing | | **Default all values** | You assign every imported canvas the same content type and default column values | Fast but defeats the purpose of metadata | | **Manual entry** | A human reviews each canvas and fills in metadata post-migration | Accurate but does not scale past ~100 canvases | | **Hybrid** | Derive what you can, default the rest, queue exceptions for human review | Most realistic for migrations above 200 canvases | > [!WARNING] > **Term Store GUIDs are created fresh on import.** If you create new term sets during migration, every term gets a new GUID in the target tenant. Downstream systems that reference terms by GUID — Power Automate flows, custom SPFx web parts, search-driven pages — will break unless you update those references. Plan term creation as a separate, pre-migration step and maintain a crosswalk from source labels to target term IDs. If your SharePoint environment uses a strict taxonomy, your migration script must query the Microsoft Graph API to resolve term names to their specific GUIDs before executing the upload payload. Treat the SharePoint term GUIDs as new destination-side identifiers. ## How Do You Map Slack Canvas Permissions to SharePoint? Slack Canvas permissions are flat: a canvas has an **owner**, and other users or channels receive **read** or **write** access via the `canvases.access.set` method. Only users can be owners — channels can receive read or write but not owner. Channel-linked canvases inherit the channel's membership as their default audience. Standalone canvases shared via link may have workspace-wide visibility depending on sharing settings. SharePoint permissions are hierarchical: site-level, library-level, and item-level, governed by SharePoint groups, Azure AD (Entra ID) groups, and individual grants. ### The identity mapping problem **Identity mapping** is the programmatic process of matching a Slack user ID to a Microsoft Entra ID User Principal Name (UPN) or Object ID. Before you can set any SharePoint permission, you need this mapping built — and it is rarely one-to-one: - **Email mismatch:** Slack accounts may use personal emails, aliases, or vanity domains; Microsoft tenant accounts use the organization's UPN - **Guest accounts:** Slack guests and multi-channel guests may not have a corresponding Azure AD identity at all - **Service accounts and bots:** Slack bot users and integration accounts have no Microsoft equivalent - **Departed users:** Slack accounts for former employees may still own canvases, but the Azure AD account is disabled or deleted Build the identity map early. Export Slack users via `users.list`, export Azure AD users via Graph's `/users` endpoint, and match on primary email. Every unmatched Slack user is a permission you either drop, reassign to a fallback account, or flag for manual resolution. **Enterprise Grid note:** On Enterprise Grid workspaces, `users.list` requires organization-level token scopes and returns users across all workspaces in the org. Permissions and canvas ownership can span org boundaries in ways that standard workspace exports do not capture. Use the Discovery API or Audit Logs API for complete permission data in Enterprise Grid environments — the standard `files.list` and `canvases.access.set` endpoints do not expose org-level sharing state. ### Mapping access levels to SharePoint | Slack Access | SharePoint Equivalent | Notes | |---|---|---| | **owner** | Full Control on the library or site | SharePoint has no single "owner" on a document — ownership is approximated with Full Control | | **write** | Contribute or Edit permission level | Contribute allows add/edit/delete on items | | **read** | Read permission level | Straightforward | | **channel membership (implicit)** | SharePoint group or Azure AD security group membership | Requires mapping the Slack channel's member list to a group | Slack also supports a **comment-only** access level in its UI — users who can view and comment but not edit. SharePoint does not have a clean equivalent for migrated page or file content. A modern SharePoint page supports page-level comments, but that is not the same as Slack's section-anchored comment model. You need a policy decision for this edge case. ([slack.com](https://slack.com/help/articles/15678967614611-Manage-access-permissions-for-canvases-and-lists)) ### Channel-level vs. item-level permissions In Slack, a canvas shared in a channel inherits that channel's membership. In SharePoint, you have two approaches: 1. **Site-level inheritance:** Map the Slack channel to a Microsoft 365 Group (Team). Migrate the canvases to that Group's underlying SharePoint site. The canvases inherit the site's permissions. This is the recommended, scalable approach. 2. **Item-level permissions:** Break inheritance on the specific file and explicitly grant access to the individual users who were in the Slack channel. > [!CAUTION] > **Item-level permissions are expensive in SharePoint.** Microsoft recommends staying under 50,000 unique permission scopes per library. If every canvas gets its own permission set, you will hit governance and performance degradation fast. Group canvases by access profile into separate libraries or folders and apply permissions at the library or folder level. ## How to Extract Canvas Content from Slack ### Inventory: there is no canvases.list Slack does not expose a dedicated `canvases.list` endpoint. Whether you are moving to SharePoint or [migrating Slack Canvas to Confluence](https://clonepartner.com/blog/blog/slack-canvas-to-confluence-migration-apis-limits-mapping), the only programmatic inventory path is `files.list` filtered to `types=canvas`. This returns canvas metadata — ID, title, creator, timestamps — paginated in the standard Slack way. ([api.slack.com](https://api.slack.com/methods/files.list)) ```bash curl -s "https://slack.com/api/files.list?types=canvas&count=100" \ -H "Authorization: Bearer $SLACK_TOKEN" \ -H "Content-Type: application/json" ``` The `files.list` method is **Tier 3** rate-limited. Slack documents Tier 3 as "50+ per minute" — the floor is 50 requests per minute, but actual limits are workspace-dependent and not published as a fixed ceiling. For large workspaces with thousands of canvases, implement exponential backoff on HTTP 429 responses and respect the `Retry-After` header value. **Enterprise Grid:** On Enterprise Grid, canvas inventory requires Discovery API access (`discovery:read` scope), which is granted at the organization level, not the workspace level. Standard `files.list` with a workspace token will not enumerate canvases owned by users in other workspaces within the same org. ### Reading canvas content The `canvases.getContent` method returns the full body of a canvas as either markdown or HTML. The default format is markdown, matching the format accepted by `canvases.create` and `canvases.edit`. The method requires the `canvases:read` scope. It is also Tier 3 rate-limited — plan the same 50+ rpm constraint and 429 backoff logic as `files.list`. ([docs.slack.dev](https://docs.slack.dev/reference/methods/canvases.getContent/)) ```bash curl -s -X POST "https://slack.com/api/canvases.getContent" \ -H "Authorization: Bearer $SLACK_TOKEN" \ -H "Content-Type: application/json" \ -d '{"canvas_id": "F1234ABCD", "content_type": "markdown"}' ``` The response contains the entire canvas in a single `content` string with no pagination. Slack caps each `document_content` object at **1 MiB**. **Handling 429 responses from canvases.getContent:** ```python import time, requests def get_canvas_content(canvas_id, token, max_retries=5): url = "https://slack.com/api/canvases.getContent" headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} payload = {"canvas_id": canvas_id, "content_type": "markdown"} for attempt in range(max_retries): resp = requests.post(url, json=payload, headers=headers) if resp.status_code == 429: retry_after = int(resp.headers.get("Retry-After", 60)) time.sleep(retry_after) continue resp.raise_for_status() data = resp.json() if not data.get("ok"): raise ValueError(f"Slack API error: {data.get('error')}") return data["content"] raise RuntimeError(f"Max retries exceeded for canvas {canvas_id}") ``` ### What the markdown actually contains Canvas markdown is a **supported subset**, not full CommonMark or GFM. The elements available are: - **Headings: h1, h2, and h3 only** — no h4 through h6. Any nested logical structure relying on deeper heading levels will flatten during extraction. - Bold, italic, strikethrough - Bulleted and ordered lists - Checklists (task lists with checkboxes) - Code blocks, block quotes, and dividers - Links and @mentions - **Tables: capped at 300 cells**, with no formula support, no merged cells — plain-text grids only. Exceeding this cell count truncates the data. Images and file attachments embedded in a canvas are referenced by URL, not inlined as base64. Download those assets separately using the `url_private_download` field from `files.info`. ### Pandoc conversion fidelity Pandoc (`pandoc input.md -o output.docx`) handles most canvas markdown cleanly, but with documented gaps: | Canvas Element | Pandoc Conversion to `.docx` | Notes | |---|---|---| | Headings (h1–h3) | ✅ Clean | Maps to Word Heading 1–3 styles | | Bold, italic, strikethrough | ✅ Clean | Standard character formatting | | Bulleted and ordered lists | ✅ Clean | Nested lists preserved | | Checklists (task lists) | ⚠️ Degraded | Pandoc renders `- [ ]` as a plain hyphen + brackets in some `.docx` backends; test your Pandoc version. Use `--reference-doc` with a custom Word template to improve output | | Code blocks | ✅ Clean | Renders as `Code Text` paragraph style | | Block quotes | ✅ Clean | Renders as block quote paragraph style | | Tables | ⚠️ Conditional | Tables with merged cells or complex alignment may lose formatting; Slack tables have no merges, so standard Slack tables convert cleanly. Verify row/column counts post-conversion | | Links | ✅ Clean | Hyperlinks preserved | | @mentions | ❌ Lost | Pandoc passes through Slack-format mentions (`<@U12345>`) as literal text; pre-process to resolve to names before conversion | | Images (by URL) | ❌ Not inlined | Pandoc does not download remote images; pre-download and reference local paths in the markdown before conversion | | Dividers (`---`) | ✅ Clean | Renders as horizontal rule | To produce the cleanest `.docx` output, pre-process the markdown to: (1) replace `<@UXXXXXXX>` mentions with resolved display names, (2) download images to a local directory and rewrite image URLs to local paths, (3) strip any Slack-specific syntax not in the subset above. Then run Pandoc with `--from=markdown+task_lists --to=docx`. ### Canvas comments do not migrate cleanly Canvas comments are anchored to sections in the UI — you click the six-dot icon on a block and add a comment, and the resulting thread appears visually attached to that section. But in the API, these comments are stored as **channel messages** (thread replies on a file conversation), not as inline annotations on the markdown body. There is no stable inline anchor ID in the markdown content that maps to a specific comment thread. You can export the comments, and you can export the canvas body, but you cannot programmatically reconstruct which comment was attached to which paragraph. That positional anchoring is visual-only in Slack's UI and does not survive extraction. ([slack.com](https://slack.com/help/articles/15708101445011-How-data-management-features-apply-to-canvases-and-lists)) On the SharePoint side, modern site pages support page-level comments but not inline section-level comments. Document library files support no inline commenting natively. Either way, the comment-to-section relationship is lost. During migration, comments must be handled as one of: - A static text log appended to the bottom of the SharePoint page or document - Separate JSON or HTML evidence files stored alongside the migrated canvas - Messages in a dedicated Microsoft Teams channel ### Version history `canvases.getContent` returns the current state only. Canvas version history is not exposed via the standard API for bulk programmatic extraction. If version history is a compliance requirement, it must be sourced from Slack's full workspace export (available to workspace admins) or the Discovery API on Enterprise Grid, which includes prior document states in the export package. ## Uploading to SharePoint Through Microsoft Graph ### File uploads: the 250 MB boundary Microsoft Graph's simple upload endpoint (`PUT /drive/items/{id}/content`) supports files up to **250 MB** in a single request. For anything larger, use a **resumable upload session** via `createUploadSession`, which supports files up to 250 GB. Chunk size must be a **multiple of 320 KiB** (327,680 bytes) — misaligned chunk sizes cause commit errors at the final merge step. For canvas-derived `.docx` or `.md` files, the 250 MB single-request limit is almost never the bottleneck. Canvases with heavily embedded video assets or large images could exceed it, but that is uncommon. ```bash # Simple upload for files under 250 MB PUT https://graph.microsoft.com/v1.0/sites/{site-id}/drives/{drive-id}/root:/{filename}:/content Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document Authorization: Bearer {token} {binary file content} ``` **Common failure modes on upload:** - `HTTP 401 Unauthorized`: The token lacks `Files.ReadWrite.All` or `Sites.ReadWrite.All` scope, or the token has expired mid-batch. - `HTTP 403 Forbidden`: The target library requires a content type the uploaded item does not satisfy, or the uploading account lacks Contribute permission on the library. - `HTTP 409 Conflict`: A file with the same name already exists and the request did not specify a conflict behavior. Add `@microsoft.graph.conflictBehavior=rename` or `replace` to the upload URL query string. - `HTTP 423 Locked`: The file is checked out by another user. Use `_api/web/lists/.../items/.../uncheckout` via SharePoint REST before retrying. ### Preserving created and modified timestamps When you upload a file through Graph, the service stamps `createdDateTime` and `lastModifiedDateTime` with the current time. To preserve the original Slack timestamps, write the `fileSystemInfo` facet on the `driveItem`: ```json { "fileSystemInfo": { "createdDateTime": "2024-03-15T10:30:00Z", "lastModifiedDateTime": "2025-06-20T14:22:00Z" } } ``` The `fileSystemInfo` properties are read/write — you can set them on upload or update them afterward via `PATCH`. The values on the `driveItem` resource itself (`createdDateTime`, `lastModifiedDateTime`) are service-controlled and read-only. The `fileSystemInfo` values are what surface in document library views when configured. ([learn.microsoft.com](https://learn.microsoft.com/en-us/graph/api/resources/baseitem?view=graph-rest-1.0)) ### Author and modifier identity: a harder problem The `createdBy` and `lastModifiedBy` fields on a `driveItem` are **read-only** in the Graph API. There is no direct Graph endpoint to set the original author or last modifier of an uploaded file. The file will show the service principal or the user account that performed the upload as the creator. The workaround uses the **SharePoint REST API** — specifically `ValidateUpdateListItem` — to write the `Author` and `Editor` fields on the underlying list item: ```json POST https://{tenant}.sharepoint.com/sites/{site}/_api/web/Lists/GetbyTitle('Documents')/items({id})/ValidateUpdateListItem() { "formValues": [ { "FieldName": "Author", "FieldValue": "[{'Key':'i:0#.f|membership|user@tenant.onmicrosoft.com'}]" }, { "FieldName": "Editor", "FieldValue": "[{'Key':'i:0#.f|membership|user@tenant.onmicrosoft.com'}]" }, { "FieldName": "Created", "FieldValue": "2024-03-15T10:30:00Z" }, { "FieldName": "Modified", "FieldValue": "2025-06-20T14:22:00Z" } ] } ``` This requires the uploading account to have site collection administrator rights or Full Control on the list. If the uploading account has only Contribute, the `Author` and `Editor` fields will silently ignore the override — no error is returned, but the values do not change. Confirm the permission level before running Author/Editor updates in bulk. The target user identity must already exist in the tenant — another reason the identity map must be built before migration begins. **Common failure modes for ValidateUpdateListItem:** - `HTTP 403`: Insufficient permissions on the list. Requires site collection admin or Full Control, not just Contribute. - `"fieldName":"Author","hasException":true` in the response body (HTTP 200 with partial failure): The identity key format is wrong. The `i:0#.f|membership|` prefix is required for standard member accounts. Guest accounts use `i:0#.f|membership|` only if they are B2B guests with a UPN in the tenant. External users without a tenant identity cannot be set as Author. - Silent no-op on `Created`/`Modified`: Some SharePoint configurations protect system timestamp fields. Verify by reading the item back immediately after the PATCH. If you skip this step, every migrated canvas appears as if it was created by the service principal on the day of the cutover, destroying your audit trail and breaking search relevance. ### PnP PowerShell alternative path For SharePoint practitioners who work primarily in PowerShell, PnP PowerShell covers most of the upload and metadata-setting workflow without requiring raw REST calls: ```powershell # Connect to the target site Connect-PnPOnline -Url "https://tenant.sharepoint.com/sites/target" -Interactive # Upload file Add-PnPFile -Path ".\canvas-export.docx" -Folder "Shared Documents/MigratedCanvases" # Set metadata including Author and timestamps Set-PnPListItem -List "Documents" -Identity 42 -Values @{ "Author" = "user@tenant.onmicrosoft.com" "Editor" = "user@tenant.onmicrosoft.com" "Created" = "2024-03-15T10:30:00Z" "Modified" = "2025-06-20T14:22:00Z" "ContentType" = "Project Brief" } ``` PnP PowerShell's `Set-PnPListItem` calls `ValidateUpdateListItem` internally. The same permission requirements apply — site collection admin or Full Control. PnP also provides `Set-PnPPage` for site page creation, which wraps the Graph Pages API and simplifies some of the `CanvasContent1` construction for common layouts. ### Creating site pages via Graph The SharePoint Pages API in Graph v1.0 supports creating modern site pages programmatically. You define the page layout, title area, and canvas layout with horizontal sections and web parts. The body content goes into `TextWebPart` objects within the canvas layout. Specific mapping examples from Slack markdown to SharePoint page structure: - A heading + paragraph block becomes a `TextWebPart` with the corresponding HTML inside a `horizontalSection` with `layout: oneColumn` and column `width: 12` - A checklist becomes a static HTML unordered list inside a `TextWebPart` (archival use), or a Planner web part (interactive use, requires a separate Planner plan created via the Planner API first) - A canvas table becomes an HTML `