Documents and work orders

Importing manuals, drawings, spreadsheets, work orders and spare parts, and reading documents in place from a file share.

File types

A document is cited by its ID, revision, page and section: doc://<site>/OM-CIP-01@B/p14#4.2. Re-importing the same ID and revision replaces it; a new revision is kept beside the old one, so earlier answers still open what they cited.

The manifest

A manifest lists each file with its document ID, revision, title, type and the assets it covers. Asset tags mentioned in the text are linked from the site's tag list.

site: plant-a
documents:
  - file: om/OM-CIP-01.pdf
    doc_id: OM-CIP-01
    revision: B
    title: Operation and maintenance manual, CIP skid CIP-100
    type: O&M
    assets: [CIP-100, P-101, P-104]
work_orders:
  - file: ../workorders/cmms_export.csv
    mapping: ../workorders/mapping.yaml
parts:
  - file: ../parts/parts.csv
    mapping: ../parts/parts_mapping.yaml
drawings:
  - file: ../electrical/E-CIP-100.pdf
    doc_id: E-CIP-100
    revision: C
    title: CIP skid electrical schematics
    assets: [CIP-100]
    reports:
      - {file: ../electrical/terminals.csv, mapping: ../electrical/terminals.mapping.yaml, doc_id: E-CIP-100-TRM}

Import it with the administrator connection:

python -m documents.load docs/manifest.yaml

Work-order column mapping

Each work-order field names the column of the CMMS export it comes from. Columns that are not mapped are kept in the technician notes and reported.

site: plant-a
format: csv              # or xlsx
date_format: "%Y-%m-%d %H:%M"
columns:
  number: WO No
  opened: Raised
  closed: Completed
  asset: Equipment
  symptom: Problem
  cause: Cause
  action: Remedy
  notes: Tech comments
  technician: Tech

Work orders are cited as wo://<site>/<number>. The same mapping is used for the work-order draft BooleX exports after a confirmed diagnosis.

Documents read in place

A site's documents can be read where it keeps them, instead of imported: BooleX lists the source, indexes each supported document and cites it, and keeps only a catalogue entry and the search index, never a copy of the file (REQ-CONN-080…086, REQ-DATA-040…045). Every document appears in the Document catalogue.

File share

Mount the site share read-only on the edge PC as BOOLE_WATCH_DIR and start the watch profile (make up PROFILES=…,watch). Every 5 minutes by default the share is listed, so a change is found well within 15 minutes:

• a PLC export (L5X, PLCopen XML including Sysmac Studio's, PAC Machine Edition's and CODESYS V3.5's, a TIA Portal SimaticML export, a Control Expert XEF) or a DCS export (DeltaV FHX, PCS 7, 800xA) is imported into the code model as a new revision, with the site lists applied;
• any other supported document is indexed in place. A changed document is indexed as a new revision (W and the first 8 hex digits of its SHA-256); earlier answers still name the revision they cited. A removed document is marked removed in the catalogue.

When a model is configured (/config/llm.json), each new or changed document gets a short summary whose every statement cites its pages. The share is only listed and read; what the last scan found is kept in a state file outside it (/data/watch-state.json). Each scan that indexed something is audited.

python -m edge.watch_folder /watch --once      # one scan now, then exit

Sources in site.yaml

document_sources in site.yaml lists the document sources. Each has an id, a kind, a label, and either a path (a share) or a url (a server or cloud source). The Assistant checks each source's reachability and shows it in the catalogue and the source viewer. The watch service indexes the SharePoint, OneDrive and Google Drive sources in the same pass as the watched share. Every key is listed in Site configuration. Connect a document share gives the steps to grant access.

document_sources:
  - {id: plant-share, kind: share, path: /mnt/docs, label: "Plant documents share"}
  - {id: sp-plant, kind: sharepoint, url: "https://graph.microsoft.com/v1.0", tenant: contoso.onmicrosoft.com,
     client_id: <app ID>, site: "contoso.sharepoint.com:/sites/Plant", folders: ["Documents/Drawings"],
     secret_file: /run/secrets/documents/sp-plant.json}
page_cache: {enabled: true, path: /data/page-cache, cap_mb: 50, expiry_days: 30}

A cloud kind in the production or offline-import profile is refused when the Assistant starts. In the hybrid and client-cloud profiles, both the service URL and its identity endpoint must be in approved_endpoints. An approved address also approves the addresses under it, so https://graph.microsoft.com approves https://graph.microsoft.com/v1.0/…. A request to any other host is refused before it is sent. That includes the tenant's SharePoint download host, unless it is approved too.

Each adapter sends only GET requests. The one exception is the token request, a POST to the identity endpoint. Each adapter catalogues only the sites, libraries and folders it lists. It refuses a Graph token that carries any application role other than Sites.Selected. Credentials are read from the secret_file (mounted read-only at /run/secrets/documents). They never appear in a log, an error or the catalogue. Logged request addresses lose their query string, because a download address carries a short-lived access token.

A source that cannot be reached is marked unreachable, and its documents stay searchable from the index (REQ-ASST-150). This covers a network failure, an identity endpoint that refuses the credentials, and an HTTP 5xx answer. An expired Graph delta feed or Drive page token makes the adapter list the folders again.

SharePoint Server is read with basic or bearer authentication only. NTLM and Kerberos (Windows integrated authentication) are not supported: give the edge PC a zone with basic authentication over HTTPS. A server certificate issued by the site's CA is trusted through ca_file.

page_cache (off by default) keeps the image of each cited page for at most expiry_days, within cap_mb. The source viewer can then still show the page when its source cannot be reached. Pages from SharePoint and Drive are rendered from a temporary file that is deleted at once.