Subcontractor requests and awards
A principal offers a defined scope to subcontractors, called UE in the Swedish interface. Each executor company answers independently. A positive answer creates or links an application. Principal staff then choose the executor through an award, which creates a commitment for the work. One request has one awarded executor; separate scopes require separate requests.
The project and work order identify where the work belongs. The commercial authority model distinguishes this supplier commitment from the customer’s accepted quote. An executor’s answer, principal award, approved delivery evidence and supplier settlement are separate facts.
Records and ownership
Section titled “Records and ownership”| Record | Owner and state | Relationship |
|---|---|---|
Request, marketplace_listings |
Principal company; draft, open, awarded or another terminal listing state | One live project, optionally one work order; the award pointer names one application. |
| Offer version | Captured at publication; immutable scope, dates, compensation and currency | Request’s current version; not the principal’s customer price or margin. |
| Invitation | Principal selects executor company and one active contact | One company/request pair; bound to the published offer and notification recipient. |
| Targeted response | Executor company through an active person; yes or no, optional note |
One retained response per invitation/version; a yes links an application. |
| Application | Executor’s interest; submitted, shortlisted, accepted, rejected or withdrawn | One company/request pair; records the offer version. Acceptance here records the principal’s award. |
| Commitment | Principal-owned, executor-linked; draft, in_progress, pending_close or closed | Award links the application; project, agreed value and dates are copied from the offer. |
| Submission, time and review | Executor submits; principal reviews | Delivery evidence for the commitment; review does not award or settle it. |
Worker and subcontractor access owns the detailed identity and resource predicates. Capabilities and resource access explains why a capability alone cannot authorize another company’s request. Publication and files retain their own audience rules.
Prepare scope and compensation
Section titled “Prepare scope and compensation”Staff use UE-förfrågningar or the project’s connected request flow. The API
requires listings:write and verifies the principal’s live project. An optional
work order must belong to that project and company. The request has no independent
phase selection; a work order can carry its own project phase. Award cannot redirect
an application to a different project. A legacy request without project scope is
refused by the award API.
The draft contains work description, location, requested dates and reply deadline. Compensation is either a positive fixed amount with its inclusions, or a positive hourly rate with estimated hours and inclusions. Customer quote values and internal margins are not offered terms. Draft save, photo upload, invitation selection and publication are separate requests. Saving a draft does not publish it. After a photo failure, the office UI retains the created request ID so it can retry the photo step. A lost create response has no general request-key guarantee; reload before creating another request.
The invitation API requires listings:invite, a managed UE partner and an active,
live contact in that executor company. The contact must have a valid email and a
staff or worker flag. The selected contact is a delivery recipient; it is not an
exclusive right for that person to answer on behalf of the executor company.
Partner qualification checks explicit blocks, tax-clearance problems, expired insurance and expired documents. Missing information can produce a warning rather than a block. Invitation requires the managed roster; award and older manual assignments retain compatibility with executors outside that roster. Qualification is checked before the award RPC, not frozen inside its transaction.
Publish and deliver invitations
Section titled “Publish and deliver invitations”A request can use invite_only or public discovery. Invited-only publication
requires at least one invitation. Public discovery means the authenticated UE
portal can find the open request; it does not publish an anonymous web page. The
API model also accepts private, which the executor visibility helper does not
admit as a public or invited-only request. Do not use that value as a third
executor-discovery workflow.
The publication API requires active principal staff. Its service-only database function locks the request and changes draft/open to open. A trigger captures the current offer version, binds invitations and queues their durable notification work. Repeated publication retains the same offer. Published description, scope, dates, compensation, currency and visibility are locked; offer rows cannot be edited or deleted through the service API. Changed terms require a new request. Photos belong to the draft and cannot silently amend a published offer. This is versioned evidence, not an office workflow for issuing successive editable versions of the same published request.
Publication and notification queueing commit together. Provider delivery happens later. The office list exposes queue status, error and delivery generation for each recipient. A queued notification is not a delivered email or an executor response. The delivery worker validates the selected contact and uses a provider idempotency key based on the outbox record and delivery generation.
Changing the contact after a send or uncertain outcome is refused. Explicit retry requires a dead notification and a recognized failure before sending, such as a disabled outbound gate or missing sender configuration. It increments the delivery generation. An uncertain provider outcome requires investigation first. Repeatedly publishing or choosing a new recipient is not a safe substitute for that review. Registration/account invitation is also distinct from answering a work request.
Record the executor’s answer
Section titled “Record the executor’s answer”Executor routes require a subcontractor company. Mutations require
applications:write; a targeted response also resolves an active person in that
company. Portal discovery combines public openings with the company’s own current
and historical invitations. It uses the offer snapshot and the company’s own
response/application, not another executor’s bid. Historical cards can show a
withdrawn response or an award to another executor; discovery is not permission
to submit a new answer.
For a targeted invitation, Ja records a positive response and creates or links a submitted application. Nej tack records a negative response without creating an application. An optional note accompanies the saved response; the portal’s current yes/no buttons send only the choice. The database locks the request and invitation and verifies the current invitation/offer pair. A response is tied to that offer, not to a later view of mutable draft fields.
The first response requires an open, live request and an unexpired offer. The
calendar deadline includes its final day in Europe/Stockholm. A database trigger
enforces this for targeted response inserts. A repeat of the same saved choice
returns replayed: true, even after expiry or award, provided the current offer
and invitation still resolve. It does not replace the first note or undo a later
application withdrawal. An opposite choice returns a conflict. There is no
caller-generated response key: invitation plus offer version identifies the
retained answer.
For public discovery, the application endpoint accepts a cover message and optional proposed price/start date. It binds the application to the current offer and now checks that offer’s inclusive Swedish deadline before creating or reactivating an application. The executor portal submits interest without a proposed price; even if another caller supplies one, award value comes from the published compensation. This application path uses separate reads and writes, not the targeted-response transaction. An already active application returns a conflict rather than a replay receipt. Reload applications after a lost response. Application insertion is not protected by the targeted response’s deadline trigger against all other callers.
Withdrawal changes the company’s own application to withdrawn. An accepted award cannot be withdrawn here; contact the principal about the commitment. A targeted positive response remains in history after withdrawal and cannot be resubmitted on the same request. A normal public application can be reactivated from withdrawn or rejected while the request remains eligible. A repeat withdrawal is an error, not an idempotent receipt. There is no dedicated invitation-revocation endpoint in these routes: listing closure/deletion and an executor’s negative response are different facts. A removed invitation cannot authorize a fresh response.
Award one executor
Section titled “Award one executor”Principal staff use Tilldela UE for an eligible application. The API requires
applications:moderate, company-owned request and matching application, the fixed
project, partner qualification and an active principal staff person. It then calls
award_ue_job_application. Only the service role can execute that function; the
browser cannot call it directly.
The current function supersedes the earlier claim-only implementation. It locks
the listing, then the application. It requires matching current offer versions,
complete compensation, an open unclaimed request, max_accepted = 1 and a submitted
or shortlisted application. The transaction accepts the application, records the
listing’s winner, resolves supplier identity/relationship, creates the commitment,
writes the audit event and inserts deduplicated in-app assignment notifications
for active executor staff. Failure rolls these writes back together. The office
API does not send a separate best-effort assignment email on this award path.
The older manual assignment path has separate commitment creation and best-effort
in-app notification; it is not the same offer/award protocol.
A fixed offer copies its amount to original_value and approved_value. An hourly
offer copies rate multiplied by estimated hours. This is agreed cost basis, not
measured hours or a supplier-invoice amount. The commitment copies title, description,
project, currency and dates, links the application and starts in_progress.
The request retains the optional work-order scope through that link; award does
not create a new work order or worker booking.
The listing lock serializes competing awards. A different application loses with
a conflict. A partial unique index permits one non-deleted commitment per linked
marketplace application. Repeating the same winner returns the same live commitment
with already_awarded: true; it can recover an older missing commitment and avoids
duplicating the award notification/audit event. The API still repeats current
project/person/qualification checks before reaching this replay. It is not an
unconditional bypass of current authorization. The reply deadline restricts new
responses; the award function does not impose the same deadline on an existing
eligible application.
An award leaves other applications independently stored; it does not automatically reject them. Principal refusal now rejects an already accepted application with HTTP 409. Its conditional update also refuses a status changed by a concurrent award. This API protection preserves the winner and commitment; it is not a new universal database transition policy for arbitrary direct writes.
sequenceDiagram participant P as Principal staff participant API as Scoped API participant DB as Database participant N as Delivery worker participant UE as Executor company P->>API: Save draft and selected invitation P->>API: Publish request API->>DB: Lock, capture offer, open, queue invitation DB-->>API: Published and queued counts N->>DB: Claim invitation delivery N-->>UE: Deliver selected offer link UE->>API: Yes to invitation API->>DB: Record choice and linked application atomically P->>API: Award selected application API->>DB: Lock, claim winner, create commitment and notifications DB-->>API: Commitment and replay flag UE->>API: Open assigned work room
The transaction reference compares the current atomic award with narrower conditional updates and provider boundaries.
Work, review and close the commitment
Section titled “Work, review and close the commitment”The resulting work room uses the executor company and commitment identity. An explicit request work order can define the assigned scope; other project orders need the applicable UE visibility. Published UE calendar passes are a separate planning projection. Selecting individual workers for time requires active workers in the executor company. Award does not assign every employee to every order. The planning, execution and review workflow owns bookings, submissions, time review and readiness.
Messages use a commitment conversation. Principal staff and the assigned executor have their own admission checks; closing the conversation does not remove its history, and a subsequent message can reopen it. Request photos, work-order visibility, project files and message attachments are separate audiences. The existing project-file loader is project-wide without a content-validity/audience filter. Commitment scope must not be read as proof that all loaded files are correctly restricted.
An approved completion submission advances in_progress to pending_close.
Principal staff with projects:write close it separately. Close requires
pending_close, normally reached through approved completion, and refuses pending submissions, pending linked
time or potentially related unlinked legacy time. It does not wait for a supplier
invoice or financial matching. A conditional status update catches a competing
status change; blocker reads and that update do not form a transaction-wide barrier
against newly arriving evidence.
A closed commitment returns a close acknowledgement. Reopen changes closed to
in_progress and records a reason; the request model rejects an empty string but
does not reject whitespace before trimming. Reopen is not a fresh award or a
reversal of supplier settlement. Closing records reason/status history and the
database refuses new submissions against the closed commitment. It does not revoke
all reads, messages or every time action. Review of evidence already matched to a
supplier service sheet is refused. Billing and cost follow-up
retains its own evidence and processing rules.
Example and recovery
Section titled “Example and recovery”A principal offers Interior painting, east wing for a synthetic fixed amount
of 24,000 SEK, including paint. Two invited companies answer yes. The first company’s
answer does not reserve the work. Staff award it, producing one 24,000 SEK commitment;
a competing award to the second company conflicts. Staff can reject the second
application separately. Approved completion later produces pending_close.
Closing after the remaining reviews does not establish that a 24,000 SEK supplier
invoice has arrived or been paid.
| Situation | Persisted fact and recovery |
|---|---|
| Terms changed after publication | Old offer remains locked. Create a separately scoped request; do not silently move an awarded request or reinterpret its answer. |
| Expired or closed request, or missing invitation | New targeted response is refused. Same-choice replay can acknowledge an existing answer while its invitation/offer resolves. Public applications have their own deadline check. |
| Saved yes later withdrawn | The answer remains positive history; the application says withdrawn. Same-choice replay does not reactivate it. Use a new request. |
| Some invitation deliveries fail | Publication remains saved. Inspect each recipient’s queue and generation; only known pre-send failures support explicit retry. |
| Response outcome lost | Reload own response/application. Retry the same targeted choice; inspect a public application’s existing state before trying again. |
| Award outcome lost | Reload request and commitment or repeat the same winner through current authorization. Do not choose a second executor as a recovery attempt. |
| Another executor wins concurrently | The losing award conflicts; no second commitment is created by that transaction. Review the recorded winner. |
| Completion approved but close fails | Inspect pending submissions/time and the current commitment status. Approval is not automatic closure. |
| Supplier-matched evidence needs correction | Review refuses mutation of matched evidence. Resolve its financial relationship through the owning cost workflow. |
The delivery PR distinguishes executed local SQL, substituted backend tests and shared application checks. A browser check does not establish provider delivery, an arbitrary direct-database caller’s transition safety or an atomic commitment close against concurrent new evidence. Historic fixtures and legacy manual assignments do not establish the current versioned-offer contract.