Knowledge

File

View as Markdown

Use the File connector to upload approved documents, spreadsheets, PDFs, or exported files directly into AIvis knowledge. It has no source-system ACL to synchronize, so access is controlled entirely by the connector’s Public or Private group configuration.

Use cases

ScenarioRecommendation
Controlled document packetPut files with the same audience into one connector and bind it to the matching Private group.
Temporary project materialRemove files or delete the connector after the project ends to avoid retaining stale material.
Spreadsheet analysisConfirm the spreadsheet is indexed and validate code-interpreter staging when needed.
Mixed-permission filesSplit connectors by audience; do not upload files with different visibility into one batch.

What it indexes

The File connector uploads one or more files into AIvis-managed storage and indexes each recognized file as a document. It is a load-state connector with no scheduled refresh or source system to poll.

ContentIndexing behavior
Text and document filesSupported extensions are .txt, .md, .mdx, .conf, .log, .json, .csv, .tsv, .xml, .yml, .yaml, .sql, .pdf, .docx, .pptx, .eml, .epub, .html, .xlsx, and .xlsm. Unrecognized extensions can be stored by the upload handler but are skipped during connector processing.
Tabular files.csv, .tsv, .xlsx, and .xlsm become tabular sections and retain the stored file ID for code-interpreter staging. If raw-file staging is unavailable, tabular files are skipped.
Images and embedded images.png, .jpg, .jpeg, and .webp become image sections. DOCX and PPTX actively extract embedded images. PDF embedded images are extracted only when the deployment’s image-extraction-and-analysis setting is enabled. The current EML, EPUB, HTML, XLSX, and XLSM paths do not emit embedded images.
ZIP uploadOne ZIP may be expanded by an upload request. Directories and path components beginning with . are skipped. A second ZIP is rejected. Files extracted from the archive still pass the extension checks above during indexing.

The normal Admin flow accepts multiple files and does not apply a file-extension filter in the browser. Uploading bytes successfully therefore does not guarantee that the connector will emit an indexed document.

Prerequisites

  • Prepare files with one of the supported extensions and validate that their contents match the extension.
  • For encrypted PDFs, note that the normal Admin File flow creates an empty internal credential and exposes no PDF-password field. Use an unencrypted copy unless your deployment has a separate supported ingestion path.
  • Ensure the file-store and indexing workers can hold and process the upload. The File upload handler does not enforce a connector-specific byte limit. The current MAX_FILE_SIZE_BYTES indexing check only logs when a constructed document exceeds the configured value; it does not reject the upload or skip that document.
  • Apply deployment ingress, storage, memory, and worker limits appropriate to your environment, then test representative large PDFs, spreadsheets, images, and archives before broad use.

Credentials

MethodAIvis behavior
Admin File uploadNo external credential is required. After storing the files and creating a load-state connector, the UI creates an empty internal credential so the connector-credential pair has an owner and can use AIvis access controls.
PDF passwordThe backend connector can read a pdf_password value from a credential, but the normal Admin File form does not expose or populate it. Do not assume encrypted PDFs are supported by this UI flow.

Do not upload access tokens, private keys, or source-system credentials as ordinary content. A File connector indexes content; it does not use a file as an authentication credential.

Configure in AIvis

  1. In the Admin panel, open Connectors, select File, and enter a descriptive connector name.
  2. Select one or more files. A ZIP is expanded by default; include at most one ZIP in the upload.
  3. Review the selected file names and remove unsupported formats before creating the connector. Upload storage can accept a file that the indexing worker later skips.
  4. Select AIvis Private groups for restricted files. Choose Public only when every AIvis account may search every file in the connector.
  5. Create the connector. The UI uploads the files, creates the connector and internal empty credential, links them with the selected access, and starts one indexing run.
  6. To revise an existing File connector, add or remove files in its management view. At least one file must remain; additions trigger update indexing and removals trigger pruning.

Permissions

File contents and descriptive owner metadata do not create source ACLs. File is not an Auto Sync Permissions source in the current Admin access selector.

Search access is controlled only by the connector’s AIvis Private groups or Public mode. Every user with connector access can search every emitted document in that File connector. Split files into separate connectors when audiences differ.

File-management authorization is separate from search access. All three File management endpoints first require a curator or admin session. Upload proceeds after that role gate. Listing then checks connector access; updating then checks editable access. A global curator has a special update allowance for a Public File connector, but not for an unrelated Private connector. An ordinary connector user cannot list or update files through these Admin endpoints merely because the user can search the connector. These management rules do not create per-document search permissions.

Verify

  1. After creation, confirm the upload returns stored file names and the indexing attempt completes.
  2. Search a distinctive title and sentence from each supported file type in the batch.
  3. Confirm an unsupported-extension test file is absent even if upload storage accepted it.
  4. For CSV, TSV, XLSX, or XLSM, inspect the extracted table and test raw-file analysis if code-interpreter staging is part of your deployment.
  5. For a ZIP, compare extracted file names with the archive. Confirm hidden path entries are not indexed as documents.
  6. Test every assigned AIvis group and a user outside those groups.
  7. Add one file and remove one file from an existing connector, then verify the new document appears and the removed document is pruned.

Troubleshooting

SymptomWhat to check
Upload succeeds but no document appearsConfirm the filename has a supported extension, the file record exists, and extraction produced text, a table, or an image section. Upload storage itself does not enforce the indexing extension allowlist.
A second ZIP is rejectedThis is expected. Use one archive for the connector upload, combine the archives before uploading, or use a separately supported ingestion API.
A large upload exhausts resourcesThe connector upload handler has no connector-specific byte rejection, and MAX_FILE_SIZE_BYTES currently warns rather than blocks. Enforce deployment-level request and storage limits, reduce the batch, and test extraction memory separately.
A tabular file is skippedConfirm raw-file staging is configured. CSV, TSV, XLSX, and XLSM require the staging callback before tabular sections are emitted.
Users can search files outside their source responsibilityFile has no source ACL sync, and metadata owners are not authorization. Restrict the connector with AIvis Private groups or split files by audience.