This is the advanced guide to packages: how stage lists, statuses and synchronization actually behave, flow by flow. For what packages are and how to create one, start with the introduction: Create Package of Cards.
Terms used on this page
When a package is created, DocBoss duplicates the doc code and makes the duplicate a compilation containing the original code. The original code's name has (Each) appended to it, so it is clear on the code list which cards receive the individual files and which code carries the package itself.
Package card - the card on the duplicated (compilation) code. It carries the combined package document, has its own stage list and status, and is what you submit.
Each cards - the individual document cards under the code marked (Each). DocBoss keeps tracking every one of them separately.
z_ stage list - the stage list DocBoss creates for a package by copying the code's stage list. Where several codes share an identical stage list, their packages share one z_ list rather than each creating a numbered copy.
When Each cards sync with the package - the rules
This is the section to read when a card did (or didn't) move and you want to know why. There are exactly three events that update Each cards from the package, a defined set of cards a sync can reach, and a defined list of cards each event skips.
Which cards a sync can reach
A sync only considers the Each cards that were in the package the last time it was generated. DocBoss saves that list at every generation and uses it for every sync, whether the package card's current file was generated or assigned (for example, a returned file you did not unpack).
- Cards added to the package since the last generation are not updated - the customer has not seen them. Regenerate to include them.
- Cards removed from the package since the last generation are still updated - they were part of what the customer reviewed.
- A package that has never been generated has no saved list, so nothing syncs.
- Regenerating replaces the saved list, whether or not the new file has been sent yet.
Rule 1 - the package moves to a later stage
When the package card moves forward to a later stage - from an assignment, an edit, a stage list change, a bulk or CSV change, a submittal with no return expected, or on completing an outstanding action - the Each cards sitting in the stage the package moved from move with it and take its status. Stages are matched by their abbreviation.
The stage is always synced first. The status is copied only when the stage move succeeds. A card that cannot take the package's status (for example, a card at NULL awaiting a new document) still moves to the new stage and keeps its own status.
A card in the stage the package moved from moves whatever its current status is, including a customer status such as a rejection. Cards left behind in the package's stage travel with the package when it advances.
Synchronization runs in the background; a banner shows while it is in progress. With a typical package it completes in moments.
Rule 2 - the package completes at its final stage
When the package card receives a complete status at the last stage of its list (so there is no next stage to move to), Each cards in that same stage take the package's status. This is what closes out a package at the end of its life, including single-stage packages and packages whose final stage completes on a submittal with no return expected.
Rule 3 - the package moves back to an earlier stage
When the package card moves back to an earlier stage - from an edit, a bulk or CSV change, voiding a submittal, rolling back an assignment, or reverting the package card's history - the Each cards sitting in the stage the package moved from move back with it. This lets a mistake, such as a package set complete by accident, be undone without fixing every card.
When Each cards move back:
- each card keeps its current file, including any file uploaded at the later stage before the package was moved back;
- cards take the package's status;
- cards at NULL are set to X and their last active file is restored, so the package can be regenerated without fixing each card;
- cards with routing are skipped and keep their stage and routing.
When you move the package back by hand, you can choose to revert only the package and leave the Each cards as they are.
What is deliberately skipped
An Each card is not updated when:
- it is not in the stage the package moved from - a card sitting in an earlier or later stage stays where it is;
- it was not in the package at the last generation, or the package has never been generated;
- its stage list has no stage matching the package's stage - the card is skipped silently;
- it has an active routing - a review in progress is never overwritten or cancelled;
- the package was assigned with unpack = Yes - you set each card's status yourself during unpacking, so nothing is synced from that assignment. This applies to that assignment only; later stage changes on the package sync as normal.
Skipped cards are left alone on purpose. If a card should match the package, update it from its own edit form.
What never triggers a sync
- A status change on the package (other than complete at the final stage). Correcting or changing a package's status mid-list does not touch the Each cards.
- Generating or regenerating the package file. Generation changes the document and refreshes the saved list of included cards, never the cards themselves.
When a package comes back from the customer
Assigning a returned package to the package card asks two things: is it complete, and should it be unpacked? The four combinations are below.
The Complete on Upload option is not offered for Each cards in a package; they always keep their original settings.
Complete + unpack
The normal path for a clean return. The returned pages are assigned to the Each cards during unpacking and you set each card's status there (any status - cards do not have to be set complete). No sync runs from this assignment; the statuses you set are the statuses the cards keep.
Complete + do not unpack
For returns where the files carry no changes or markup - typical for certificates. A confirmation explains the consequences before it applies: the Each cards will not receive a copy of the returned documents, they take the package's status, and they advance with it. You can then resubmit the package as-is (new cover page) or regenerate.
Because the returned file is assigned rather than generated, the cards updated are the ones saved at the last generation; a notice on the form states that only cards linked to the last generation will be updated. Resubmitting as-is sends exactly what the customer reviewed. If cards have been added since, regenerate first to include them. Where regenerate on submittal is switched on, the package is rebuilt at submittal with the current cards.
Not complete + unpack
The normal path for a rejection. Unpack, set each card's status individually, and route only the problem cards. Cards you complete advance on their own; the rejected cards and the package stay in the current stage for resubmittal.
When the package later advances, the cards still in its stage (the rejected ones, and any you left) move with it. Cards you advanced during unpacking are already in a later stage and are not touched again.
Not complete + do not unpack
Possible, but unpacking is the recommended path, and the form says so. The Each cards keep their current status (usually X) and only the package can be routed. You must add yourself as a reviewer before saving - it is the only way you are notified of what the team uploads to the package card.
Submitting and resubmitting
- Reaching the outgoing list: a package becomes available for submittal once every Each card has a file assigned, with no routing and no suffix.
- Stage check before generating: the package cannot be generated while any Each card is in an earlier stage than the package. Generation is blocked and a warning lists those cards. It offers to move them forward to the package's stage and status for you, or you can cancel and fix them yourself (for example, by moving those cards forward from their own edit forms). Cards DocBoss cannot move (no matching stage in their stage list) must be fixed by you before generating.
- Routing on the package card: regeneration is blocked while the package card has routing. The icon is greyed with a mouseover; complete or remove the routing first.
- Routing on Each cards: manual generation shows an error listing the routed cards that will be left out. When the package is regenerated on submittal, the same error is shown and the routing must be resolved before the submittal goes out.
- Resubmitting after a partial rejection: complete the action on the rejected card(s), then regenerate and submit from the package's current stage. Cards approved on the earlier pass will have advanced, and they are still included - see "Which file goes into the package" below.
- Changing the package's stage by hand, forward or back, shows a warning first, since the Each cards in its stage will have stage and status reset to match. The warning states how many of those cards have routing; those cards are not moved. The same warning appears when a status saved on the package card's edit form moves its stage (for example, setting it complete). Moving the package back by hand also offers to revert the package only, without syncing the Each cards.
- Changes without the prompt: bulk and CSV changes, voided submittals, rolled-back assignments and history reverts apply the same sync rules in the background, without a warning.
Which file goes into the package
Packages differ from ordinary compilations in one deliberate way, and it is the thing most likely to look wrong when it is working correctly.
- An Each card with an active file contributes that file, as always.
- An Each card that has advanced past the package's stage and sits at NULL (awaiting its next document) still contributes: DocBoss takes the card's last active file from its history. This applies when the card's stage list contains the package's stage before the card's current stage. This is why a card can show NULL on the card list while its document appears in the generated package. It is deliberate: when a package is re-issued at an earlier stage - a resubmittal after a partial rejection is the usual case - the customer must receive the complete package, and the last active file is the document that card last carried.
- An Each card at the package's own stage with NULL contributes nothing, the same as an ordinary compilation - there is no document for the current pass yet.
In an ordinary compilation a NULL card is never included. The package exception applies only to cards ahead of the package's stage.
Finding the package from an Each card
Every Each card links to the package PDF - in card info and on the outstanding action popup - so a reviewer holding one rejected card can open the package it was sent in.
Why didn't it...?
(quick answers for common situations)
I changed the package's status and the Each cards didn't change. Correct. Status changes don't sync, except complete at the final stage. Move the stage, or edit the cards directly.
I moved the package back a stage and the Each cards moved back too. Correct. Each cards in the stage the package moved from follow it back, so a mistaken stage change can be undone in one step. A manual change back offers to revert the package only.
An Each card didn't move with the package. It wasn't in the stage the package moved from, it wasn't in the package at the last generation, its stage list has no matching stage, it had routing, or the package was assigned with unpack = Yes. It stays put by design; update it from its edit form if it should match.
An Each card moved stage but kept its NULL status. Correct. The stage always syncs; a card that cannot take the package's status keeps its own.
A rejected Each card moved forward with the package. Correct. Any card in the stage the package moved from travels with it, whatever its status, unless it has routing.
I added a card to the package and it didn't update when the package moved. Correct. Syncs use the cards saved at the last generation. Regenerate the package to include the new card.
The package isn't showing in Outgoing Submittals. At least one Each card is missing a file, carries a suffix, or has routing. The restriction icon's mouseover names the condition.
I can't regenerate the package. Three possible causes: the package card has active routing (complete or remove it), an Each card has routing (resolve it), or an Each card is in an earlier stage than the package - you would have seen the warning for this. No Each card can be behind the package when it is generated.
An Each card shows NULL but its document is in the package. Deliberate - the card advanced past the package's stage, and its last active file is included so the package goes out complete. See "Which file goes into the package" above.
If you have questions about packages, please reach out to our Support team and we'll be happy to assist.