Maintenance Work Permits
Version 20.0.1.0.0. English customer manual.
Purpose and scope
Maintenance Work Permits coordinates authorization for a defined maintenance job. It links an optional native maintenance request and equipment record to a work area, separate issuer and performer, precautions, a validity interval and a retained handback history.
This is operational coordination software. It does not certify safety, establish legal compliance, replace competent assessment or implement electronic signatures. Example precautions are starting prompts for your site's own procedures, not complete safety instructions. The addon does not operate equipment, schedule maintenance, modify stock or create accounting documents.
Requirements and installation
Use Odoo 20. The declared dependencies are the standard maintenance and mail addons. Tested on Odoo 20 Enterprise for installation with and without demo data, focused workflow and access checks, and native HTML report rendering. Community qualification has not been established. No paid external service or hardware connection is required.
- Place the corvus_maintenance_permits folder on the configured addons path.
- Restart Odoo, update the Apps list and install Maintenance Work Permits.
- Assign permit roles to internal users and verify their allowed companies.
- Review the supplied permit types before preparing a live job.
- Open Work Permits > Permits. Optional demo data is not needed for normal operation.
The app supplies a numbered sequence, three editable permit types, precaution templates and an hourly expiry activity job. A fresh database needs an assigned issuer and performer before its first permit can be saved.
Roles and visibility
Performer: read accessible company permits; prepare and edit an assigned draft; confirm precautions; activate an assigned approved permit; suspend assigned work; and hand work back.
Issuer: includes Performer access. The assigned issuer can issue, approve, suspend, extend, cancel and close a permit. The issuer cannot act as performer on another person's assigned work. Issuer and performer must be different active internal users with the appropriate roles and company access.
Manager: includes Issuer access and manages permit types/templates. A manager may edit another person's draft and act as issuer on another permit, but cannot approve a permit on which that manager is the performer. Managers can archive closed or cancelled permits.
The role selector is Maintenance Work Permits in the user's access rights. A system administrator assigns it. Permit records are restricted by allowed company. A linked maintenance request also retains its native read restrictions; associated precautions and history inherit permit visibility. Ensure the issuer and performer can access the request through normal maintenance assignment or following. Permit roles do not grant Maintenance administration rights. Permits without a linked request are readable by permit users in the allowed company.
Workflow checks also apply to imports and API calls. Hiding a button is not the access control. Lifecycle, history and confirmation identity fields cannot be overwritten through ordinary writes.
Configure permit types
Open Work Permits > Configuration > Permit Types as a Manager. The initial types are General Maintenance (24 hours), Hot Work (12 hours) and Restricted Access (12 hours). These elapsed-hour limits are sample operational settings, not safety limits prescribed by the product.
For each type, set its name, optional company, maximum total duration, preparation guidance and ordered precaution template. Leave company empty for a shared reference type. A required precaution must be confirmed before approval and activation. Optional precautions remain visible but do not block those actions.
New drafts copy the current template, guidance and duration limit. Existing permits retain their own copies when configuration changes. Choose the type before saving; use a new draft to change the type later. Customize the copied precautions while the permit is still Draft. A permit must have at least one precaution before issue.
Do not delete a type that is referenced by permits. Archive unused types instead. Normal reference records use upgrade-preserving data for editable names, guidance, duration limits, templates, sequence and scheduled-action settings.
Prepare and issue a permit
Create a permit under Work Permits > Permits. Enter a concise subject, permit type, physical work area, job-specific work scope, issuer, performer, Valid From and Valid Until. Link equipment and a maintenance request when appropriate. If the request specifies equipment, choose that same equipment on the permit.
The interval must end after it starts and must not exceed the copied duration limit. Odoo stores datetimes in UTC and displays them in each user's timezone. The end instant is exclusive: activation at the expiry instant is refused. Maximum duration is elapsed time, including time before activation and all extensions.
Save to obtain the numbered reference and copied precautions. The assigned issuer reviews the scope and presses Issue. Issue requires a future expiry and at least one precaution. Issued details are frozen, including responsibility, work area, native links and original start time. If the job changes materially, cancel and prepare a new permit.
Only drafts can be deleted. Issued and later records are retained; use cancellation or handback rather than deletion.
Confirm precautions, approve and activate
The assigned performer opens the Precautions tab and confirms each required item. Save newly added precaution rows before selecting Confirmed; creation and confirmation are separate actions. Add a concise job-specific confirmation note where useful. Each confirmation records the acting user and time. Confirmation may be prepared in Draft or updated while Issued, Approved or Suspended.
The issuer presses Approve after all required precautions are confirmed. Approval is available from Issued or Suspended and rejects an expired interval. Approval alone does not mark work Active.
The assigned performer presses Activate during the interval. The server checks the role, current state, time and required confirmations again. Repeated activation is refused. Confirmation evidence cannot be changed while Active: suspend work first.
The interval badge describes time only. Work is recorded as authorized only when the state is Active and the interval has not expired. Refresh an open view to update time-dependent badges.
Suspend, extend and resume
The assigned performer or an authorized issuer can choose Suspend from Approved or Active. Record why work stopped and any changed conditions. Suspended permits appear in Needs Attention. A suspended permit cannot be activated directly.
An authorized issuer can choose Extend from Approved, Active or Suspended. Enter the revised expiry and a meaningful review reason. The new end must be later than both the previous expiry and the current time, and the whole interval must remain within the copied maximum duration. Extensions can therefore recover an expired permit only when that original duration limit still allows it.
Each extension preserves its actor, timestamp, reason, previous expiry and revised expiry in History. It always leaves the permit Suspended, including when it was previously Active. The original start and first activation time are retained. Review the existing precautions, update confirmations if conditions changed, obtain issuer approval again, then let the performer activate.
A duration limit cannot be changed on an existing permit. If the revised job or interval no longer fits, cancel the suspended permit and prepare a new permit with a suitable reviewed scope.
Handback, closure and cancellation
The assigned performer chooses Hand Back from Active or Suspended. Enter the condition of the work area, completion status and any remaining restrictions. Handback is allowed after expiry so the team can record that work has stopped. The state becomes Handed Back; no further activation is available.
The issuer reviews the performer statement and presses Close. The report preserves the handback and closure times. Repeated closure is refused. There is no automatic closure of the linked maintenance request; continue that native workflow separately.
The issuer can Cancel a Draft, Issued, Approved or Suspended permit with a reason. Suspend Active work before cancellation. Closed or cancelled permits cannot be reopened. Create a new permit for new work, retaining the previous record as history. A Manager may archive closed or cancelled permits, which remain available through the Archived filter.
Expired permits and activities
The permit register marks unfinished permits whose end instant has passed as Expired. Needs Attention includes expired permits, Suspended permits and Handed Back permits awaiting closure. Search filters also include My Work, My Approvals, Awaiting Approval, Awaiting Closure, Overdue Activities and Archived.
An hourly scheduled action processes up to 100 expired issued/approved/active/suspended permits per run and assigns one review activity to the issuer for each expired interval. Its deadline is the expiry date. For already-expired permits that date may be overdue. Additional records are handled on later runs. Extensions reset the interval reminder marker, so a later expiry can generate a new activity. Already-existing activities remain for the issuer to review and complete; they are not silently removed.
Activities support follow-up; the scheduled job does not stop physical work or change the permit state. Refresh the register and inspect the interval even when the scheduler is delayed. Teams can schedule additional native activities and use the Activity view. Keep responsible users active, and assign a replacement through a new permit if an issued assignment is no longer usable.
Maintenance links, register and report
Use the Maintenance Request and Equipment smart buttons to open the linked native records. This addon does not change their scheduling, assignment or completion state. Native access rights still apply.
The list shows reference, subject, type, area, performer, expiry, time status, lifecycle state, required-precaution progress and activities. Optional columns include issuer, start time, equipment and company. Search by the reference, subject, work area, maintenance request, equipment or people. Group by State, Permit Type, Performer or Work Area. No quantities or safety scores are inferred.
Open a permit and use Print > Work Permit and Handback. The report includes scope, people, validity, native links, precautions and confirmation evidence, handback text and the complete authorization/extension history. Native HTML report rendering has been verified. PDF generation requires a working Odoo server PDF engine; server PDF output has not been qualified on the tested target. A report can also document unfinished work and identifies when handback is absent. A printout is a time-bound snapshot; verify current Odoo state and expiry before using it for coordination.
Worked example
In the optional fictional demo, Maya Brooks is the issuer and Leon Park is the performer. Open Extraction fan drive inspection completed. It links to Fictional Workshop Extraction Fan EF-3 and the matching native inspection request.
For a new equivalent job, the issuer creates a General Maintenance draft, defines the workshop boundary and saves. The copied three required precautions appear on the Precautions tab. Maya issues the permit; Leon confirms all three items; Maya approves; Leon activates within the validity interval.
If an adjacent area is not ready, Leon suspends the work and records the restriction. Maya may extend the interval within the copied limit, explaining the review. The state stays Suspended until Maya reapproves and Leon reactivates. The two expiry times remain in History.
Once work has stopped and the area is ready for handback, Leon records the completion statement. Maya reviews it and closes the permit. Print the Work Permit and Handback report. The demo also includes a Draft job, a partially confirmed Issued access review, an Active workshop repair and a Suspended conveyor review with extension history and an overdue follow-up. Demo dates are relative to installation; an Active demo can legitimately become Expired later.
Corrections and troubleshooting
Approval blocked: check required precautions, expiry and the assigned issuer's role. Only the assigned performer can set confirmations. Being a Manager does not make a user the assigned performer.
Activation blocked: confirm the state is Approved and the current time lies at or after Valid From and before Valid Until. A Suspended or extended permit requires approval again. Refresh after another user changes the record.
Invalid people: issuer and performer must differ, remain active, have the appropriate permit groups and have access to the permit company. An issued permit cannot be reassigned; retain it and prepare a replacement.
Missing linked request: verify ordinary Maintenance visibility. Add the relevant people to the maintenance request using its native assignment/following workflow. The permit role intentionally does not broaden access to unrelated maintenance records.
Extension rejected: the new end must be later than both current expiry and current time, and must fit the original copied duration limit. Editing the permit type does not retroactively change that limit.
Precaution editing refused: definitions are frozen after issue and confirmations are frozen while Active or after handback. Suspend active work before changing confirmations. Cancel and replace a permit whose actual scope or precaution definition changed.
No expiry activity: the permit may not yet have expired, may be Draft or finished, may already have an interval reminder, or the hourly job may not have run. The scheduled action processes a bounded batch; inspect its status with an administrator. The Expired filter does not depend on the job.
Another user is updating this permit: refresh and retry the intended action. Transition locks prevent overlapping updates from producing duplicate approvals or contradictory changes.
A report lacks handback: this is expected for work that has not reached Handed Back. Complete the performer handback and issuer closure when appropriate; do not overwrite history to make a report appear complete.
Upgrade, backup and support
Back up the database and filestore before an Odoo module upgrade. Upgrade through the normal Apps workflow. Stable configuration records use upgrade-preserving data settings, and issued permit snapshots and history remain separate from the current templates. Verify your configuration and retained history after the upgrade. No other Odoo major version is claimed.
History is an application audit trail rather than a cryptographic or legal signature service. Database administrators can administer their database outside these application controls. Do not use permit notes as a store for secrets or unnecessary personal data.
Support: support@corvusnexus.com. Publisher: Corvus Nexus Technologies LTD. Website: https://corvusnexus.com. Include the addon version, Odoo version, action attempted and a fictionalized reproduction when requesting support.
Availability
This guide covers the Odoo 20 package. Older-version packages are not part of this release.