​

StackOne File Picker

The StackOne File Picker provides a unified interface for browsing and selecting documents from third-party platforms. It abstracts provider-specific differences behind a consistent user experience and developer interface, whether the source is a file storage system (like SharePoint, OneDrive, Google Drive) or a knowledge base (like Confluence or Notion).

​

How It Works

The File Picker allows users to:

• Navigate a hierarchical file tree (folders, pages, blocks)
• Select one or more files or documents
• Return a list of StackOne file objects, which can be used with unified operations such as GET /files/{id} or POST /files/download

​

Picker Types

​

Output Format

When a user completes selection, the picker returns:

{ 
  "files": [
    {
      "id": "c28xIQaWQ6ODA5MzcyMg",
      "name": "QA text 1",
      "path": "https://exploreconfluence.atlassian.net/wiki/spaces/QS/pages/8093722/QA+text+1",
      "driveId": "7733268"
    }
  ]
}

Each fileId corresponds to a StackOne-normalized file object that can be accessed via API:

• GET /files/{id} – fetch file metadata
• POST /files/{id}/download – retrieve file contents (if supported)

​

File Object Structure (for Fetch)

When queried individually, a file returns the following structure:

{
  "id": "file_123",
  "name": "Report Q1.pdf",
  "path": "/Marketing/Reports/Q1",
  "mimeType": "application/pdf",
  "size": 204800,
  "lastModified": "2024-12-01T10:00:00Z",
  "provider": "sharepoint",
  "downloadUrl": "https://..."
}

• For knowledge bases like Confluence and Notion:

  • Files may represent pages or blocks
  • Additional metadata like hasContent, hasChildren is provided

​

Provider Feature Table

​

Developer Integration

1. Trigger the Picker Use the StackOne SDK, embed directly via the UI component or trigger via the StackOne Dashboard.

2. Receive Selection The picker will return:

   { 
     "files": [
       {
         "id": "c28xIQaWQ6ODA5MzcyMg",
         "name": "QA text 1",
         "path": "https://exploreconfluence.atlassian.net/wiki/spaces/QS/pages/8093722/QA+text+1",
         "driveId": "7733268"
       }
     ]
   }

3. Perform Unified Actions

   • Fetch metadata: GET /files/{id}
   • Download file: POST /files/{id}/download

​

Auth & Permissions

• Each provider uses OAuth2 authentication via StackOne’s integration flow

• File access scopes are handled per provider during auth

  • SharePoint: Files.Read.All, Sites.Read.All
  • Google: https://www.googleapis.com/auth/drive.readonly
  • Confluence/Notion: Read access to spaces/pages/blocks

​

StackOne File Picker SDK Documentation

The StackOne File Picker SDK enables you to integrate file selection from connected accounts into your application.

Below are the installation steps, usage examples, and API details.

​

Installation

Install the SDK using one of the following package managers:

# Using NPM
npm install --save @stackone/file-picker

# Using Yarn
yarn add @stackone/file-picker

​

Connect Session Token

The File Picker requires creating a separate connect session token with the Account ID and Provider Key of a connected account.

​

Usage

Below you can find the basic usage of the StackOne File Picker SDK using React:

import React, { useState, useEffect, useCallback } from 'react';
import { FilePicker } from '@stackone/file-picker';
import { StackOne } from "@stackone/stackone-client-ts";

const _stackOne = new StackOne({
  security: {
    password: "",
    username: "",
  },
});

export const FilePickerButton = () => {
  const [filePicker, setFilePicker] = useState(null);

  useEffect(() => {
    const initializePicker = async () => {
      const { sessionToken } = await _stackOne.connectSessions.createConnectSession({
        categories: [ConnectSessionCreateCategories.Documents],
        accountId: '{{Connected Account ID}}',
        provider: '{{Provider Key}}',
        ...
      });
      setFilePicker(new FilePicker({ sessionToken }));
    };

    initializePicker();
  }, []);

  const handleClick = useCallback(() => {
    filePicker?.open();
  }, [filePicker]);

  return (
    <button onClick={handleClick} disabled={!filePicker}>
      Open File Picker
    </button>
  );
};

​

API Reference

​

FilePicker Class

​

Constructor: FilePicker(options)

The options object can include the following parameters:

​

Methods

​

Coming Soon: Notion Support

StackOne will soon launch a custom picker for Notion, modeled similarly to Confluence:

• Block/page navigation
• Unified selection of document-style pages
• Multi-select and metadata retrieval