BooleX.ai DOCS Book a demo
Documentation

Get started

Set up

Get answers

Quick reference

Manual

IT documentation

Guides

Reference

Docs / Guides

Connect a document share

Import manuals, drawings and work orders, or read them in place from a read-only share, SharePoint, OneDrive or Google Drive.

Collect the documents

O&M manuals, the functional specification, drawings (PDF, DXF, DWG, Visio, DEXPI), ECAD report exports, spreadsheets (C&E, I/O lists), procedures (safety, lock-out), the CMMS work-order export and the spare-parts list. Scanned PDFs are read by OCR on the edge PC.

Write the manifest

List each file with its ID, revision, title, type and assets, and each work-order and parts export with its column mapping: see Documents and work orders.

Import

shell
python -m documents.load docs/manifest.yaml

Or read the share in place

Instead of importing, mount the site share read-only on the edge PC and start the watch profile:

shell
BOOLE_WATCH_DIR=/mnt/plant-docs make up PROFILES=,watch

Every 5 minutes the share is listed. New and changed documents are indexed where they are, never copied; a changed document becomes a new revision, and earlier answers still open the revision they cited. PLC and DCS exports on the share are imported into the code model. With a model configured, each document gets a cited summary. BooleX never writes to the share. See Documents and work orders.

To show the share's label and reachability in the catalogue and the source viewer, list it under document_sources in site.yaml, and turn on page_cache if the viewer should still show cited pages while the share is down.

Check it

Open Documents in the top bar: every document is listed by source and folder, with its revision, assets, index state (indexed, indexed by OCR, no text found, failed to index) and summary. Open one and ask it a question. Ask a question the manual answers on the Diagnostics screen and open the doc:// citation: it opens on the cited page. See Document catalogue.

Or read SharePoint, OneDrive or Google Drive in place

BooleX reads these libraries where they are, through their own APIs, and only the libraries and folders you list. It uses an account that can only read. SharePoint Server works in every deployment profile. SharePoint Online, OneDrive and Google Drive work only in the hybrid and client-cloud profiles, on endpoints in approved_endpoints. The production and offline-import profiles refuse them; an air-gapped site syncs those libraries to an on-site share instead (above).

For each source:

  1. Grant the read-only access described below.
  2. Put the credentials in a JSON file under deploy/secrets/documents/. Make it readable by its owner only (chmod 600). The watch and assistant services see this folder as /run/secrets/documents (or set BOOLE_DOCS_SECRETS).
  3. Add the source to document_sources in site.yaml.
  4. Start the watch profile: make up PROFILES=…,watch.

Every 5 minutes the watch service picks up new, changed and removed documents. BooleX never logs a credential or shows one in an error.

SharePoint Online (Microsoft Graph, Sites.Selected)

A Microsoft Entra administrator and a SharePoint administrator of the client's tenant do this.

  1. In the Microsoft Entra admin center, open App registrations › New registration. Name it BooleX documents (<site>), choose this organisational directory only, and leave the redirect URI empty. Note the Application (client) ID and the Directory (tenant) ID.
  2. Open API permissions › Add a permission › Microsoft Graph › Application permissions. Select Sites.Selected only, then Grant admin consent. Remove any other application permission: a token that carries more than Sites.Selected is refused.
  3. Add a credential under Certificates & secrets. A certificate is preferred: make it on the edge PC (command below), upload boolex-docs.crt under Certificates, and write {"private_key": "<boolex-docs.key>", "certificate": "<boolex-docs.crt>"} (the files' PEM text) to deploy/secrets/documents/sp-plant.json. Or choose New client secret, copy its Value and write {"client_secret": "<value>"} to that file; renew it before it expires.
  4. Give the app read access to each site it may read; Sites.Selected grants nothing until then. A SharePoint administrator runs the PnP PowerShell command below for each site, or the same grant through Graph: POST /v1.0/sites/{site-id}/permissions with {"roles": ["read"], "grantedToIdentities": [{"application": {"id": "<client-id>", "displayName": "BooleX documents"}}]}. Never grant write, manage or fullcontrol.
  5. Allow outbound HTTPS (443/TCP) from the edge PC to graph.microsoft.com, login.microsoftonline.com and the tenant's SharePoint host (for example contoso.sharepoint.com, where Graph sends each download), and list all three in approved_endpoints.
  6. Add the source to site.yaml (below).
shell
openssl req -x509 -newkey rsa:2048 -nodes -days 730 -subj "/CN=boolex-docs" -keyout boolex-docs.key -out boolex-docs.crt
PnP PowerShell, as a SharePoint administrator
Grant-PnPAzureADAppSitePermission -AppId <client-id> -DisplayName "BooleX documents" -Site https://contoso.sharepoint.com/sites/Plant -Permissions Read
site.yaml
approved_endpoints: ["https://graph.microsoft.com", "https://login.microsoftonline.com", "https://contoso.sharepoint.com"]
document_sources:
  - id: sp-plant
    kind: sharepoint
    label: "Plant SharePoint"
    url: https://graph.microsoft.com/v1.0
    tenant: <tenant ID or contoso.onmicrosoft.com>
    client_id: <application (client) ID>
    site: contoso.sharepoint.com:/sites/Plant
    folders: ["Documents/Drawings", "Documents/Manuals"]   # a library, or a folder in it
    secret_file: /run/secrets/documents/sp-plant.json

folders names a library (Documents, or its address name Shared Documents), optionally followed by a folder in it. Subfolders are included. Graph's change feed covers a whole library, so BooleX reads the feed of each listed library and catalogues only the listed folders.

OneDrive

OneDrive for work or school is the owner's personal SharePoint site, so it uses the same app registration and the same Sites.Selected permission.

  1. Do steps 1 to 3 above, or reuse the same app.
  2. Grant read access on the owner's OneDrive site, for example https://contoso-my.sharepoint.com/personal/jane_contoso_com, as in step 4.
  3. Find the drive ID with Graph Explorer, as an administrator: GET https://graph.microsoft.com/v1.0/users/jane@contoso.com/drive?$select=id.
  4. Approve https://contoso-my.sharepoint.com as well as the hosts above. Then add:
site.yaml
  - id: od-eng
    kind: onedrive
    label: "Engineering OneDrive"
    url: https://graph.microsoft.com/v1.0
    tenant: <tenant ID>
    client_id: <application (client) ID>
    drive: <drive ID, b!…>
    folders: ["Plant docs"]                 # folders in the drive; "/" for all of it
    secret_file: /run/secrets/documents/od-eng.json

SharePoint Server (2016, 2019, Subscription Edition)

  1. Create a domain service account, for example svc-boolex-docs.
  2. Give it the Read permission level on each listed library only: Library settings › Permissions for this document library › Grant permissions › Read.
  3. Turn on Basic authentication over HTTPS for the web application zone the edge PC uses: Central Administration › Manage web applications › Authentication providers. A zone extended for the edge PC keeps the other zones unchanged. If the site issues OAuth bearer tokens to SharePoint instead, use auth: bearer.
  4. Write {"username": "DOMAIN\\svc-boolex-docs", "password": "…"}, or {"token": "…"} for bearer, to deploy/secrets/documents/sps-eng.json.
  5. If the server's certificate is issued by the site's own CA, put the CA certificate (PEM) beside the secrets and name it in ca_file.
site.yaml
  - id: sps-eng
    kind: sharepoint_server
    label: "Engineering SharePoint"
    url: https://sp.plant.local/sites/engineering
    auth: basic
    folders: ["Shared Documents/Drawings"]   # relative to the site
    secret_file: /run/secrets/documents/sps-eng.json
    ca_file: /run/secrets/documents/site-ca.pem

NTLM and Kerberos (Windows integrated authentication) are not supported. A zone that offers only these refuses the edge PC. The REST change log query is a POST, which BooleX never sends. So instead of reading the change log, BooleX lists the listed folders every 5 minutes and compares each file's ETag.

Google Drive (drive.readonly, service account)

A Google Cloud project owner and the owner of the Drive folders do this.

  1. In the Google Cloud console, choose or create a project. Under APIs & Services › Library, enable the Google Drive API.
  2. Under IAM & Admin › Service accounts, choose Create service account. Name it boolex-docs. Give it no project roles.
  3. On the service account, open Keys and choose Add key › Create new key › JSON. Save the downloaded file as deploy/secrets/documents/gd-eng.json. If the organisation policy iam.disableServiceAccountKeyCreation blocks this, an organisation administrator must allow it for this project.
  4. In Google Drive, share each listed folder with the service account's e-mail address (boolex-docs@<project>.iam.gserviceaccount.com) as Viewer. For a shared drive, add the service account as a Viewer member of the drive. Share nothing else with it. Domain-wide delegation is not used.
  5. Note each folder's ID: the last part of its address, https://drive.google.com/drive/folders/<folder ID>.
  6. Allow outbound HTTPS (443/TCP) to www.googleapis.com and oauth2.googleapis.com, and add:
site.yaml
approved_endpoints: ["https://www.googleapis.com/drive/v3", "https://oauth2.googleapis.com/token"]
document_sources:
  - id: gd-eng
    kind: google_drive
    label: "Engineering Drive"
    url: https://www.googleapis.com/drive/v3
    folders: ["<folder ID>"]               # folder IDs; subfolders are included
    drive: <shared drive ID>                # only for a shared drive
    secret_file: /run/secrets/documents/gd-eng.json

The token asks for the drive.readonly scope only. Documents are listed under their folder's name. Google Docs and Slides are read as PDF, and Sheets as XLSX.