Premium change notice for New York -- Setting it up

Setting it up

Five steps, repeated for each policy type in scope.

Work out the scope first

A renewal lands on the newest lines effective date at or before its term start. So every renewal from now on goes to the newest copy of its policy type, and older copies can never receive one.

Configure only the newest effective date of each policy type in scope. A line published over many years may have dozens of policy type rows and only a handful that can ever take a renewal. This is usually a much smaller job than it first appears.

Step 1 — Add the calculation item

Go to Lines → the policy type → the lines effective date and add an item. Name it something stable; this article calls it Premium Change Notice Flag.

• Type Calculation — not coverage, not adjustment
• Category Policy, so there is one per policy
• Requirement type Mandatory
• Sort order higher than every other item on the policy type

Sort order matters because items rate in that order and this one sums the others, so it must rate last. Take the highest existing sort order and go well above it. Check that no item on the type has a blank or higher sort order — anything rating after the flag is left out of its sum.

Keep it at policy category. As a risk item, a multi-property policy would evaluate the trigger once per property and produce duplicate notices.

Step 2 — Add three rate chain evaluations

On that item, in this order:

current_total   NEW VARIABLE

                sum of every non-fee, non-calculation item premium on the

                revision (the properties' items plus the policy-wide items)

prior_total     NEW VARIABLE

                the same two sums, but over

                i.previous_revision_value('annual_premium', d('0'))

Premium         PREMIUM

                (this.current_total - this.prior_total)

                if (this.is_renewal_revision

                    and this.prior_total > d('0')

                    and (this.current_total - this.prior_total) / this.prior_total > d('0.10'))

                else d('0')

Change 0.10 to your filed percentage. Three parts of that expression are load-bearing:

• is_renewal_revision stops a mid-term endorsement re-rating the flag and sending a renewal notice out with an endorsement packet.
• annual_premium, not written premium — written premium on an endorsement is that revision's pro-rated change, which is the wrong basis for comparison.
• Summing the other items' prior values, rather than the flag's own, avoids a gap in the first cycle. A brand-new item has no value in last year's term, so it would return the default and print nothing for a full renewal cycle.

Step 3 — Item settings

Most of these are on the item's Setup tab, in the Options section. One is on the Rating tab — noted below.

Tick "Only Available For:" and choose Renewals from the dropdown. This is the setting that decides whether renewals pick the item up at all, and it is the most common reason a notice never appears.

The checkbox matters as much as the dropdown. The dropdown has no effect until the checkbox beside it is ticked. Choosing Renewals without ticking it leaves the item unrestricted, which is the same as not setting it.

A renewal copies the prior revision's items forward, so an item added to a line after a policy was written is simply absent from that policy's renewal. The only items added automatically are mandatory ones restricted to renewals. Leave this unticked — which is the default — and the flag reaches almost nothing, with no error reported anywhere.

Then, on the Setup tab:

Also on Setup, tick Show in Builder: and choose BriteCore only from its dropdown.

And confirm the item is set to Line item is Mandatory for this policy type.

On the Rating tab, set the rounding dropdown to Round to Nearest Dollar.

Do not add a system tag. An item with no system tags is already eligible to be used by a rule. Adding an unrelated tag removes that eligibility.

If the item was created through the API rather than the UI, open it in the UI and save it once. Several of these settings default differently through the API.

Step 4 — Create the rule

Advanced trigger:

flag_premium = 0

for item in list(policy_items.values()):

    if (item.name or '').strip() == 'Premium Change Notice Flag':

        flag_premium = float(item.annual_premium or 0)

return_value = flag_premium > 0

The rule's category must match the trigger item's. A policy-category rule needs a policy-category trigger item.

Anchor the trigger to the calculation item itself. A rule is never retrieved for a policy that does not carry its anchor item, and triggers on different items combine with AND rather than OR. Anchoring to an item that only some policies carry silently limits the rule to those policies.

Step 5 — The document and its figures

Create a Carbone custom document holding the notice wording, with print on initial dec, print on renewal dec, print on non-autopay and overwrite stock all off, so it cannot print by itself.

That is deliberate. It means a mistake in the rule results in no notice printing, never a wrong notice reaching a policyholder.

Give it a distinct name. The name must be unique among your Carbone documents and must not match the name of a standard BriteCore report type. The system resolves the document by name when the rule fires, so a duplicate or colliding name can generate the wrong document. When you save the registration it will warn you that the name is not a known report type — for this document, that warning is what you want to see. Renaming it later is safe.

Add two calculated fields for the dollar increase and the percentage, reading the annual premium and the prior term's annual premium. These are worked out when the page is rendered, from the committed revision — this is what the policyholder actually reads.

Place a tag on the template for every figure the notice states. A calculated field that exists and computes is not the same as one that appears on the page. A sentence carrying both reads:

Your premium has increased by ${d.calculated.annual_premium_increase_cf:formatN(2)},

which is {d.calculated.annual_premium_increase_pct_cf:formatN(2)}%

Do not attach the notice as a form on the item unless your declaration is itself a Carbone document. A .docx attached to an item does render through Carbone, but it inherits the declaration's context. Where the declaration is a legacy document, that context has none of the fields this notice needs and the template renders blank.

Where your declaration is a Carbone document, an item form is the better design — its print only when this item's premium is greater than $0 condition is the same gate, it prints with the renewal packet, and the rule becomes unnecessary. Check which kind of declaration you have before choosing.