# SharePoint import settings

Put offgen.json files in SharePoint folders to choose which slides, icons and images are imported into your Library and how.

Source: https://www.offgen.ai/docs/sharepoint/import

The automated SharePoint import copies a folder tree into your offgen [Library](/docs/library) and keeps it in sync. A small file named `offgen.json` decides which folders are imported and how. You create and edit it directly in SharePoint. offgen only reads it.

**Where:** your SharePoint folders, plus [Settings → SharePoint → Automated imports](https://app.offgen.ai/settings/sharepoint) at app.offgen.ai · **Who:** admin task (Owner or Admin role in offgen, and edit rights on the SharePoint folders)

**Before you start:** your library is [connected](/docs/sharepoint), and offgen has set up an automated import for your organization. If **Automated imports** is empty, [ask support to set one up](mailto:support@offgen.ai?subject=SharePoint%20import).

## Quick start

1. In SharePoint, create a file named `offgen.json` in the top folder you want to import. Its content can be just `{}`.
2. In [Settings → SharePoint](https://app.offgen.ai/settings/sharepoint), select **Check setup** on the import.
3. If it says **Setup looks good**, select **Run now**.

## Where to put the file

Only folders that contain an `offgen.json`, or sit below a folder that does, are imported. Folders with no `offgen.json` in themselves or any parent folder are ignored, and the run summary lists them under **Ignored**. To import a whole tree, put `{}` in its top folder.

* 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.
* A subfolder without its own file inherits the settings of the nearest file above it.

## Settings

Every setting is optional. The file itself is what opts a folder in.

| 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](#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.

```json title="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."
}
```

```json title="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.

```json
{
  "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**

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

**Frameworks: keep multi-slide files together**

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

**Icons saved as PNG files**

```json
{ "kind": "icon" }
```

**Protect everything except title and body text**

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

## Check before you run

Open **Settings → SharePoint** in [app.offgen.ai](https://app.offgen.ai/settings/sharepoint) 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 items are removed after the next complete run. Existing workflows keep working.
* Imported templates are managed in SharePoint. To change one, edit the file in SharePoint; the next run updates the template in offgen.
* 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.

## Related

* [Connect SharePoint](/docs/sharepoint): connect the site and pick the document library
* [Template library](/docs/library): where the imported slides, icons and images appear
* [Lockable elements](/en/product/lockable-elements) on offgen.ai