Why Document IDs Should Survive Folder Moves

A supplier changes its name. Procurement reorganises the contract folder, and an ERP link to the signed agreement stops working. The agreement has not changed, but the integration used its old location to identify it. Store a stable document ID with its site context so ordinary folder changes do not require rebuilding business-system references.

A path answers “where is this document organised now?” An identifier answers “which managed document is this?” Keep both, with different jobs: use the identifier to retrieve the document and the current path to help people recognise and browse it.

Store the reference your integration actually needs

An ERP vendor number identifies the supplier. A FormKiQ document ID identifies an agreement managed in the repository. The folder path describes its current organisation. Treat these as separate fields in the integration mapping rather than deriving one from another.

Keep the deployment or connection context too when an application talks to more than one FormKiQ environment. A reference is useful only if the application knows where to send it. A stable ID also does not grant access: requests still need the appropriate authentication and authorisation.

What FormKiQ's folder-move release provides

FormKiQ v1.19.1 introduced asynchronous folder moves and fixed document MOVE collisions that could remove documents from folder search results. It also corrected folder listings and access checks to respect folder read permissions consistently. These are useful release details when planning an upgrade or testing a reorganisation.

The folder-move API accepts the source folder's indexKey, the site context, and a target path. Its documented 201 response confirms that a move request was created. Because processing is asynchronous, that response alone is not confirmation that every child document has reached its destination.

Keep the application's “move requested” state separate from its “move verified” state. Confirm the resulting document locations and folder contents before reporting completion to users or dependent systems. Use the behaviour documented for the deployed release when handling conflicts and retries.

1. Before

   Capture the references

   Record the affected document IDs, site, source location, and expected destination.

2. During

   Track the request

   Show that the move is processing and retain the references needed to reconcile its outcome.

3. After

   Verify the result

   Check IDs, destination listings, and access before refreshing display paths and confirming completion.

Worked example: a supplier rename without broken contract links

Suppose vendor V-1042 changes its trading name from Acme to Northstar. The ERP's agreement record already stores a FormKiQ document ID and the procurement site. Its display path is vendors/acme/master.pdf. The records team moves the folder to vendors/northstar/.

The application's document-details request uses documentId with the appropriate siteId, rather than searching for the old supplier name. If the original approval must remain tied to a particular signed revision, retain that version reference separately. “The same document” and “the exact revision approved” answer different questions.

Separate a move from a policy change

A new location can affect access wherever folder permissions are part of the deployment's policy. Test the destination with both permitted and denied users, including direct API access as well as folder browsing. A familiar path is not evidence that access is correct, and knowing a document ID is not permission to read it.

Use explicit business attributes for durable meaning, such as vendor ID, record class, matter ID, and confidentiality. If a reorganisation also changes retention, ownership, or review responsibility, make that an explicit, authorised policy decision. Do not infer that a folder rename should silently reclassify the record.

Plan recovery around the observed result. If a client times out, inspect the affected records before resubmitting the move; a lost response does not establish that processing failed. Keep an integration log of the requested source and destination, affected IDs, time, and reconciliation outcome. Include these fields in the integration's own records so support staff can reconcile a reported failure.

A practical folder-move acceptance checklist

• Confirm the deployed release supports the intended folder operation and record its documented conflict behaviour.
• Open the same document from the ERP, CRM, or case record before and after the move using its stored ID and site.
• Reconcile nested folder contents by document ID, rather than relying on a matching total count alone.
• Exercise destination collisions and an interrupted client request; check the outcome before retrying.
• Verify permitted and denied access, plus the relevant versions, attributes, relationships, and governed records.
• Refresh displayed paths only after verification and retain enough integration history to explain the change.

Let folder structure evolve around stable references

People should be able to reorganise documents as suppliers, teams, and cases change. Durable identifiers let integrations keep their connection to the managed record while paths remain useful for navigation. Combine those identifiers with site context, explicit policy decisions, and a verified move outcome.

Technical guidance reviewed: November 12, 2026, against the FormKiQ document model, folder-move API reference, document retrieval API, and v1.19.1 release notes linked above.