Configure the SharePoint import

Use offgen.json files to control how SharePoint folders are imported into your offgen library.

The automated SharePoint import mirrors a folder tree into your offgen library. A small file named offgen.json controls how each folder is imported. You create and edit it directly in SharePoint. offgen only reads it.

This page assumes your site is connected and an automated import is set up for your organization.

Where to put the file

Place offgen.json in the root folder of the import, in any subfolder, or both.

A file applies to its folder and everything below it.
A subfolder file only needs the settings that differ. Everything else is inherited from the folders above.
Folders without a file simply inherit. {} is a valid file.

Settings

All settings are optional.

Setting	Values	Default	What it does
`flat`	`true`, `false`	`false`	How a PowerPoint file with several slides is imported. `false` keeps the slides together as one stack. `true` makes every slide a separate template. A file with one slide is always one template.
`kind`	`"icon"`, `"image"`	`"image"`	Whether `.png`, `.jpg`, and `.webp` files are imported as icons or as images. `.svg` files are always icons.
`labels`	list of texts, up to 60 characters each	none	Labels added to everything imported from this folder. Labels add up down the folder tree. A sync never removes labels.
`locks`	see Lock shapes	not set	Which shapes keep their original content when offgen generates slides.
`analysisPrompt`	text, up to 2000 characters	not set	Extra instructions for the AI that names and describes each slide. Any language.

Settings in a subfolder replace the inherited value. labels is the exception: they are combined.

References/offgen.json

{
  "$schema": "https://www.offgen.ai/schemas/offgen.schema.json",
  "flat": true,
  "labels": ["Reference"],
  "analysisPrompt": "Use the slide title as the template name."
}

References/Quality/offgen.json

{ "labels": ["Quality"] }

Slides in References/Quality are imported one template per slide, named after their title, with the labels Reference and Quality.

The $schema line is optional. With it, editors such as VS Code suggest settings and flag mistakes while you type. The import ignores it.

Lock shapes

A locked shape keeps its content exactly as authored, for example a logo, a legal footer, or a fixed chart. Set a default for all shapes, then list the exceptions in except. Exceptions get the opposite of the default.

{
  "locks": {
    "default": "locked",
    "except": ["placeholder:footer"]
  }
}

This locks everything except the footer. With "default": "unlocked", only the listed shapes are locked.

You can select shapes in two ways:

placeholder:<type> selects a PowerPoint placeholder: title, subtitle, body, footer, header, slideNumber, date, picture, chart, table, object, or media.
name:<shape name> selects a shape by its name in PowerPoint's selection pane. Upper and lower case do not matter, and * is a wildcard: name:Rectangle*.

If a selector matches no shape on a slide, the import continues and lists it in the run summary. A locks block in a subfolder replaces the inherited block completely.

Recipes

References: one template per slide, named after the slide title

{
  "flat": true,
  "labels": ["Reference"],
  "analysisPrompt": "These slides are client references. Use the slide title as the template name."
}

Frameworks: keep multi-slide files together

{
  "labels": ["Framework"],
  "analysisPrompt": "These slides are reusable frameworks. Describe the slide structure, not the specific project."
}

Icons saved as PNG files

{ "kind": "icon" }

Protect everything except title and body text

{
  "locks": {
    "default": "locked",
    "except": ["placeholder:title", "placeholder:body"]
  }
}

Check before you run

Open Settings → SharePoint in app.offgen.ai and select Check setup on the import. offgen reads every offgen.json, shows the effective configuration for each folder, and lists any problems. Nothing is imported during the check.

When the setup looks good, select Run now or wait for the next scheduled run.

If a file has an error

A folder with an invalid offgen.json is skipped together with all its subfolders, and the reason is reported. offgen never falls back to default settings, because a large import with the wrong settings is hard to undo. Other folders are imported as usual.

Common causes:

A misspelled setting such as lables. Unknown settings are rejected.
Comments or a trailing comma. The file must be plain JSON.
Curly quotes (“ ”) pasted from Word or Outlook. Use straight quotes (").
A wrong value type, such as "flat": "true" instead of "flat": true.
A label longer than 60 characters, a prompt longer than 2000 characters, or a file larger than 64 KB.

Fix the file in SharePoint and select Check setup again.

Good to know

Supported files are .pptx, .pptm, .svg, .png, .jpg, .jpeg, and .webp. Other files are skipped and listed in the run summary.
Unchanged files are skipped on later runs. An edited slide updates its existing template.
Renaming or moving a file in SharePoint does not create duplicates.
When a file is deleted in SharePoint, its library entries are archived after the next complete run. Existing workflows keep working.
A slide that already exists in the library with the same layout and text is skipped and reported.
A changed analysisPrompt or flat applies to new and edited files only. Changed labels apply on the next run.
Limits: 1 GB per PowerPoint file, 20 MB per icon or image, 12 folder levels.