File arrival
Start a workflow or a process-flow instance when a document lands in a SharePoint document library or in OneDrive.
Two trigger blocks fire when a file appears in a watched location:
| Block | Watches |
|---|---|
| SharePoint: New File | a document library on a SharePoint site |
| OneDrive: New File | a folder in the connected account's OneDrive |
Both are polling triggers. Scrydon holds the watch and asks Microsoft Graph what changed since the last check, so you do not build or maintain a loop of your own, and the trigger has no inbound URL for anyone to call.
Configuration
| Field | Required | Notes |
|---|---|---|
| Site ID | yes | A site id, or hostname:/sites/<name>. |
| Document Library | no | A drive id. Leave blank for the site's default library. |
| Folder Path | no | /Shared Documents/Contracts. Leave blank to watch the whole library. |
| Field | Required | Notes |
|---|---|---|
| Folder Path | no | /Documents/Invoices. Leave blank to watch the root. |
| MIME Type Filter | no | A prefix — application/pdf, or image/ for any image. |
| Include Subfolders | no | On by default. Turn it off to watch only the named folder. |
There is no account field on the trigger, and that is deliberate. A polling trigger always reads through the connection's designated execution account for the environment it runs in, so an account chosen on the block would be ignored. Connect or change the account on the Microsoft connection instead.
Folder paths are matched case-insensitively and a trailing slash makes no
difference. A sibling folder that merely starts with the same text does not
match: watching /Contracts does not pick up files in
/ContractsArchive.
What the trigger emits
| Field | Example |
|---|---|
fileId | 01ABCDEF... |
name | signed-contract.pdf |
path | /Contracts/signed-contract.pdf |
parentFolder | /Contracts |
size | 184320 |
mimeType | application/pdf |
webUrl | link that opens the file in SharePoint or OneDrive |
createdBy | display name of whoever uploaded it |
createdDateTime · lastModifiedDateTime | ISO-8601 timestamps |
driveId | the parent drive |
dedupeKey | stable key for this file — see below |
siteId | SharePoint only |
The trigger does not hand over the file's bytes, or a link to them.
Microsoft's pre-authenticated download URL is deliberately not emitted: it
grants the file to anyone holding it, and a trigger payload is recorded in the
run log. Use fileId and driveId with a SharePoint or OneDrive action to
fetch the content, so the read carries its own authorization.
Starting a process-flow instance
Connect the trigger to a Create Process Instance block:
| Create Process Instance field | Value |
|---|---|
| Instance name | Onboarding — <start.name> |
| Seed context (JSON) | { "documentPath": "<start.path>", "documentUrl": "<start.webUrl>" } |
| Dedupe key | leave blank, or <start.dedupeKey> |
<start.…> is the trigger's output; the trigger block's own name works too,
for example <sharepointfilearrival1.dedupeKey>. Write references in angle
brackets. {{…}} is the environment-variable syntax, and a block reference
written inside it is passed on as literal text.
The dedupe key is what guarantees one instance per document, and a blank
Dedupe key already uses the trigger's dedupeKey. The key is derived from
the drive and the file, so it does not change when the file is renamed or
re-uploaded, and a second arrival of the same document returns the existing
live instance instead of starting a parallel one. A Create Process Instance
block inside a Loop is the exception: there a blank key is not filled in, so
each iteration starts its own instance.
Type your own Dedupe key only when you want a different grouping, and keep
it different per file. Fixed text such as contracts, or a reference written
as {{…}}, is the same for every file, so every arrival after the first
returns the first file's instance. If one trigger starts two different
templates, give each its own key, for example contracts:<start.dedupeKey>:
one key cannot belong to two templates, and the second start fails.
Scrydon also treats a repeated delivery of the same file as a duplicate, on every server, but only for 24 hours after the first — the dedupe key is the durable guarantee.
Timing and first run
- Microsoft notifies Scrydon when something changes in the watched drive, so a file is usually picked up within seconds.
- A poll runs every five minutes alongside the notifications and catches anything a notification missed. Microsoft does not guarantee delivery, so the poll is what makes the trigger reliable — notifications only make it fast. You do not configure either one.
- A new watch does not replay the files already in the folder. The first check records the current position and emits nothing; only files arriving afterwards start a run. Add existing documents by hand if you need them.
- Only newly created files fire the trigger. Folders, deletions, renames, and edits to a file that was already there are ignored — and so is a file moved into the watched folder, because it keeps its original creation time.
- If Microsoft invalidates the trigger's change-tracking token (it does this after a long gap), the trigger re-arms from that moment. Files created while the token was invalid are not replayed.
- A large bulk upload is delivered over several polls rather than all at once.
Polling triggers only run in a promoted environment. In Development the trigger saves, validates, and shows as active, but never ticks — the poll deliberately skips writable environments so an in-progress workflow does not act on real documents. Promote the workflow to Staging or Production to see it fire, and use Test on the trigger to exercise the downstream blocks while you are building.
Permissions
The connected Microsoft account needs read access to the watched location —
Sites.Read.All and Files.Read.All for SharePoint, Files.Read /
Files.Read.All for OneDrive. These are part of the scopes requested when the
account is connected; an account connected before this trigger existed may need
reconnecting.
Scrydon also registers a change subscription with Microsoft for the watched drive and renews it automatically. If your tenant blocks change notifications, or the Scrydon instance is not reachable from Microsoft's network, the subscription simply never gets created and the trigger falls back to the recurring poll — slower, and otherwise identical. Nothing to configure either way.
Troubleshooting
| Symptom | Cause |
|---|---|
| Nothing fires, no errors | The workflow is in Development. Promote it. |
| Nothing fires in Production | Check the folder path spelling, and whether Include Subfolders is off. |
registration_unsupported in Monitor | The trigger's extension declares no way to fire it. Nothing will dispatch this trigger. |
| Reauthorization messages | The Microsoft connection expired or needs Entra admin consent. |
| The same document started two instances | Dedupe key holds something that differs per arrival, or the block runs inside a Loop. Leave it blank, or set it to <start.dedupeKey>. |
Every new file returned the same instance (deduped: true) | Dedupe key is the same for every file: fixed text, or a reference written as {{…}}. Leave it blank, or set it to <start.dedupeKey>. |
| Arrivals are noticed within five minutes rather than seconds | The change subscription is missing or expired. Harmless — the five-minute poll is still covering the trigger, and the subscription is renewed every few hours. |
| A file moved into the folder never fired | Expected. Only newly created files fire; a moved file keeps its original creation time. |
Invalid webhook signature on the trigger URL | Something other than Microsoft posted to it. The trigger URL is not a generic webhook; it accepts only Microsoft's own change notifications. |