Upgrading#

Moving an org from an installed Welisa DocGen version to a newer one. An upgrade is an in-place package install: templates, versions, jobs, signature data and settings are kept, the post-install script re-runs, and nothing needs re-configuring. It is also an irreversible change to a client's production org — there is no rollback — so it follows a short, deliberate playbook. Plan 45–90 minutes of a consultant's attention per production org, never squeezed between two meetings.

Welisa consultants perform upgrades for clients. Client administrators are welcome to read this page to know what to expect.

0. Decide, don't drift into it#

Is there a newer released version? See Release notes, or sf package installed list -o <org> versus the current release.
Read what changed. Security and bug fixes: upgrade soon. Features: agree a moment with the client; production upgrades happen in a quiet, announced window.
Sandbox first when the client has one and the change is more than a hotfix.
One consultant with admin rights in the target org, uninterrupted, with this page open.

1. Preflight (read-only, ~10 minutes)#

sf org list                                   # the alias is the RIGHT org — check the org Id, sandbox vs production
sf package installed list -o <org>            # current Welisa DocGen version (namespace welisa)
sf org display -o <org>                       # org Id, instance, the user you act as

Note the installed version and the target version's package Id.
The Welisa Licence tab reads Licensed? Fix that first (it is on Welisa's side) — you do not want to debug two things at once.
Client customisations that bind to the package can break on upgrade. Retrieve and list everything that references welisa__ or welisa.:
```
sf project retrieve start -o <org> -d /tmp/<org>-pre -m ApexClass -m ApexTrigger -m Flow -m LightningComponentBundle -m PermissionSet -m CustomMetadata -m Layout -m FlexiPage
grep -rl "welisa__\|welisa\." /tmp/<org>-pre | sort
```
Compare that list with the release notes: a renamed or removed global method, a new required field, changed Flow inputs? Plan the client-side change first.
Running work: no bulk job in progress, no signature request you would interrupt (they survive, but do not upgrade while someone is signing).
Permission-set licences: Welisa User and Welisa Admin carry View All; an assignment to a user on a licence that does not permit it fails the upgrade. Check before, not after — see Installation.

2. Backup (~10 minutes)#

Because uninstall/reinstall deletes package data and there is no rollback, export the client's records to CSV and keep them with the project files, date-stamped: templates, template versions, brands, assets, e-mail templates, saved queries, jobs, signature requests, signers, audits, placements, settings, button metadata — and the template files themselves (the Word/HTML/PDF bodies are files linked to the template versions). Keep the retrieved client metadata from step 1 with it. Welisa's consultants have a scripted version of this step.

3. Install the new version (~5–15 minutes)#

sf package install -p <04t…> -o <org> -w 30 --no-prompt

or the install link on the right login host (login.salesforce.com for production and Developer Edition, test.salesforce.com for sandboxes), Install for Admins Only, accept the AppExchange notice. While it runs: nothing else in that org.

4. Verify (~15 minutes, tick all)#

sf package installed list shows the new version, and the installed-package Id is unchanged (an in-place upgrade, not a reinstall).
The post-install script ran: the Welisa Licence Check scheduled job exists, a fresh check completed, the Welisa Licence tab reads Licensed.
Record counts equal the backup for every object.
Open the client's most-used template and generate a sample; one Word and one HTML if both exist; one signature request if they sign.
The client's own Flows and Apex that call the package still work (run one, or run their Apex tests).
Permission sets still assigned (an upgrade never removes assignments — check one user anyway).
No new rows in the Welisa Error Logs since the install time.
Type picklists on Welisa Template and Welisa Template Version carry every value — a value introduced after the org's first install does not arrive with an upgrade; add it by hand (Troubleshooting).
Deprecated components: Setup → Installed Packages → Welisa DocGen → View Components; anything deprecated that the client references → plan a follow-up.

5. Record and tell the client#

Record the org (name, org Id, date, who) with Welisa so the installed-orgs ledger stays current, and tell the client what changed (the release notes section) and that the upgrade is done.

If it fails#

Install error → the org is unchanged; Salesforce rolls the whole upgrade back. Read the error (often a client customisation referencing something removed), fix, retry.
Install succeeded, something is broken → there is no downgrade. In order: fix the client-side customisation; a hotfix release from Welisa; as a last resort uninstall and reinstall the previous version restoring the backup from step 2 — hours of work, announce it.
Licence tab red after upgrade → press Check now; the upgrade itself never changes licence state. If it stays red, contact Welisa.

What an upgrade never does#

Pushes itself. Welisa does not push upgrades into client orgs; every upgrade is performed knowingly, in an agreed window, with the steps above. Beta builds are never installed in client orgs.