Filings are a key offering for Verne registry applications and provide a record of changes applied to registry data over time via business service functions.
Filings need to be considered in two quite different contexts:
- generation – associating one or more filing codes to a service transaction
- view – viewing the content of a filing
Filing Generation
Service transaction filings is the standard mechanism for managing the filings associated to a service transaction.
Filings can be associated to a service transaction using Verne’s filing derivation process. In fact that is usually all that’s required to support any filing association functionality. It’s worth noting however that there’s nothing stopping filings being added and/or updated via custom rules, either in addition to the standard filing derivation (perhaps via one of the associated rule scopes) or just via one or more of Verne’s other standard rule scopes.
Filing Derivation
Out-of-the-box Verne derives/calculates filings when a service is first created, and then on activation. This allows filings to be displayed as soon as a service transaction is started (and viewed/edited for corrections), as well as having the filings updated (added or removed) based on the domain data relating to the service transaction (e.g. data entered in the form) if appropriate.
Filings are derived using the deriveFilings command or the deriveFilings convenience method on the service transaction.
Filing Instructions
Which filings are associated to a service transaction when derived are determined by processing an application’s configured filing instructions. Filings are associated to a service transaction for any filing instruction that "matches" the service transaction in its current state. A single filing instruction could relate to service transactions for a specific service, or relate to any service that meets the criteria defined within the instruction.
Filing instructions determine what filings (filing codes) get associated to a service transaction. The content of a filing relating to a filing code is outlined in the viewing filings section.
See filing instructions configuration for specific details relating to configuring filing instructions.
Additional Rule Scopes
The first-level filing instruction filing scope options for defining rules around when a filing should apply and the rule element for defining custom rules all relate to whether a service transaction filing relating to the filing instruction filing is added or not.
There are two additional rule scopes relating to filings that are run after the filings are derived using the filing instructions. For efficiency, these rule scopes are only called if there has been a change in the filings associated to the service transaction.
filings-changed scope
If the filings associated to the service transaction change, the filings-changed rule scope is called before the new filings are set on the service transaction. This allows decisions to be made or the filings altered before being updated. Rules of this scope can be from the application down to the service.
The following rule variables are available to use in this rule scope:
| Variable name | Type | Description |
|---|---|---|
appCtx | ApplicationContext | The application context when the rule is called. |
serviceTransaction | ServiceTransaction | The service transaction the filings are about to be updated on (note: the old filings are still associated with the service transaction at this point). |
hash | String | A unique fingerprint relating to the details of the new filings. |
newFilings | List | The new filings that are about to be set on the service transaction so they can be changed before they are set. |
changed | boolean | Whether the filings are changing (always true since this rule scope isn’t called if false). |
filings-changed-complete scope
If the filings associated to the service transaction change, the filings-changed-complete rule scope is called after the new filings have been set on the service transaction. This allows decisions to be made or the filings altered after being updated. Rules of this scope can be from the application down to the view tree nodes.
The following rule variables are available to use in this rule scope:
| Variable name | Description |
|---|---|
appCtx | The application context when the rule is called. |
serviceTransaction | The service transaction the filings have just been updated on (note: the new filings have already been set on the service transaction at this point). |
Filing examples
Given the following filing instruction configuration:
<filingInstructions>
<!-- Simple case: a filing for a single service -->
<filingInstruction name="newSolarSystemFiling" filingCode="newSolarSystemFiling" textKey="filing.newSolarSystemFiling">
<filingScope service="createSolarSystem"/>
</filingInstruction>
<!-- Filing if a new Planet is added -->
<filingInstruction name="newPlanetFiling" filingCode="newPlanetFiling" textKey="filing.newPlanetFiling">
<filingScope domain="Planet" domainAction="added"/>
</filingInstruction>
<!-- Filing for a new Planet added called 'Earth' -->
<filingInstruction name="newEarthFiling" filingCode="newEarthFiling" textKey="filing.newEarthFiling">
<filingScope domain="Planet" domainAction="added" attribute="Name" attributeValue="Earth"/>
</filingInstruction>
<!-- Filing if a Planet is changed other than its population -->
<filingInstruction name="changedPlanetFiling" filingCode="changedPlanetFiling" textKey="filing.changedPlanetFiling">
<filingScope domain="Planet" domainAction="modified">
<run type="groovy">return domainChange?.node?.isChanged({ e -> e.key != 'Population' })</run> <!-- Any attribute changed other than Population -->
</filingScope>
</filingInstruction>
<!-- Filing if a domain (i.e. solar system, planet, comet or asteroid) who's name attribute is changed (excludes new domains - modified only) -->
<filingInstruction name="objectRenameFiling" filingCode="objectRenameFiling" textKey="filing.objectRenameFiling">
<filingScope service="updateSolarSystem" domainAction="modified" attribute="Name" attributeAction="modified"/>
</filingInstruction>
<!-- Filing if a planet has it's population attribute removed/set to null -->
<filingInstruction name="extinctionEventFiling" filingCode="extinctionEventFiling" textKey="filing.extinctionEventFiling">
<filingScope domain="Planet" attribute="Population" attributeAction="removed"/>
</filingInstruction>
<!-- Filing if a planet is removed -->
<filingInstruction name="planetDestroyedFiling" filingCode="planetDestroyedFiling" textKey="filing.planetDestroyedFiling">
<filingScope domain="Planet" domainAction="removed"/>
</filingInstruction>
<!-- Filing if a new Asteroid or Comet domain is added -->
<filingInstruction name="newNonPlanetFiling" filingCode="newNonPlanetFiling" textKey="filing.newNonPlanetFiling">
<filingScope domain="Asteroid,Comet" domainAction="added"/>
</filingInstruction>
</filingInstructions>And the following services and form configuration:
<businessServices>
<businessService code="createSolarSystem" formItem="solarSystemDetails" mode="Create"/>
<businessService code="updateSolarSystem" formItem="solarSystemDetails" mode="Change"/>
</businessServices><serviceFormItems>
<record shortCode="solarSystemDetails" domain="SolarSystem">
<attribute attribute="Name"/>
<repeater shortCode="planets">
<record domain="Planet">
<attribute attribute="Name"/>
<attribute attribute="Diameter"/>
<attribute attribute="Population"/>
</record>
</repeater>
<repeater shortCode="asteroids">
<record domain="Asteroid">
<attribute attribute="Name"/>
<attribute attribute="Diameter"/>
<attribute attribute="Velocity"/>
<attribute attribute="Risk"/>
</record>
</repeater>
<repeater shortCode="comets">
<record domain="Comet">
<attribute attribute="Name"/>
<attribute attribute="Diameter"/>
<attribute attribute="Velocity"/>
</record>
</repeater>
</record>
</serviceFormItems>The following actions would attract the mentioned filings (note: this assumes that filings are derived on each update):
| Step | Action | Filing change(s) | Full list of current filing codes | Notes |
|---|---|---|---|---|
| 1 | Start createSolarSystem service | +newSolarSystemFiling | newSolarSystemFiling | |
| 2 | Add a planet | +newPlanetFiling | newSolarSystemFiling, newPlanetFiling | |
| 3 | Set the planet name to Gaia | newSolarSystemFiling, newPlanetFiling | ||
| 4 | Update the planet name to Earth | +newEarthFiling | newSolarSystemFiling, newPlanetFiling, newEarthFiling | |
| 5 | Set Earth’s population | newSolarSystemFiling, newPlanetFiling, newEarthFiling | ||
| 6 | Set the planet name to New Earth | -newEarthFiling | newSolarSystemFiling, newPlanetFiling | |
| 7 | Set the planet name to Earth again | +newEarthFiling | newSolarSystemFiling, newPlanetFiling, newEarthFiling | |
| 8 | Add a second planet | +newPlanetFiling | newSolarSystemFiling, newPlanetFiling, newEarthFiling, newPlanetFiling | |
| 9 | Set the 2nd planet name to Mars | newSolarSystemFiling, newPlanetFiling, newEarthFiling, newPlanetFiling | ||
| 10 | Add a comet | +nonPlanetFiling | newSolarSystemFiling, newPlanetFiling, newEarthFiling, newPlanetFiling, newNonPlanetFiling | |
| 11 | Set the comet details | newSolarSystemFiling, newPlanetFiling, newEarthFiling, newPlanetFiling, newNonPlanetFiling | ||
| 12 | Apply/activate the service | newSolarSystemFiling, newPlanetFiling, newEarthFiling, newPlanetFiling, newNonPlanetFiling | ||
| 13 | Start updateSolarSystem for the newly created solar system | |||
| 14 | Clear the Earth’s population attribute | +extinctionEventFiling | extinctionEventFiling | Population excluded from changedPlanetFiling |
| 15 | Set the Earth’s diameter attribute | +changedPlanetFiling | extinctionEventFiling, changedPlanetFiling | |
| 16 | Remove the Mars planet | +planetDestroyedFiling | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling | |
| 17 | Set the Earth planet name to New Earth | +objectRenameFiling | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling, objectRenameFiling | |
| 18 | Set the Halley’s Comet comet name to Comet Halley | +objectRenameFiling | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling, objectRenameFiling, objectRenameFiling | |
| 19 | Add another planet and set its name to Earth | +newEarthFiling | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling, objectRenameFiling, objectRenameFiling, newEarthFiling | |
| 20 | Add another planet and set its name to Earth | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling, objectRenameFiling, objectRenameFiling, newEarthFiling | Multiple newEarthFiling filings not allowed | Multiple newEarthFiling filings not allowed |
| 21 | Add another comet and set its name to Comet2 | +newNonPlanetFiling | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling, objectRenameFiling, objectRenameFiling, newEarthFiling, newNonPlanetFiling | |
| 22 | Add an asteroid and set its name to Asteroid1 | +newNonPlanetFiling | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling, objectRenameFiling, objectRenameFiling, newEarthFiling, newNonPlanetFiling, newNonPlanetFiling | |
| 23 | Add another comet and set its name to Comet3 | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling, objectRenameFiling, objectRenameFiling, newEarthFiling, newNonPlanetFiling, newNonPlanetFiling | Max of 2 newNonPlanetFiling filings | Max of 2 newNonPlanetFiling filings |
| 24 | Set the Solar System name to Outer Space | +objectRenameFiling | extinctionEventFiling, changedPlanetFiling, planetDestroyedFiling, objectRenameFiling, objectRenameFiling, newEarthFiling, newNonPlanetFiling, newNonPlanetFiling, objectRenameFiling |
