Skip to content
KiweelyKiweelyKiweely

Remap Workday Benefit Codes When a Carrier Companion Guide Changes

A mid-year companion-guide change is an integration-map change, not a new connector. Workday’s ANSI X12 834 V2 template already has the loops. You remap the codes, limit the test to the affected workers, and send only after that file matches the guide.

  • Checked against Workday on
  • Applies to Workday Extend
  • 6 min read
  • Published
  • By Kiweely
On this page

A carrier that changes plan or coverage codes mid-year is asking you to change the values in an existing Cloud Connect for Benefits file. The ANSI X12 834 layout stays. The companion guide’s codes move. The work is the integration maps for those codes, a launch limited to the workers who use them, and a file you can read against the new guide before the nightly job sends it.

Workday’s benefits-connector course is explicit about the gap this creates. Providers share the 834 format and still use different values. Companion guides explain the provider’s values. They do not name Workday integration attributes, maps, or field overrides. You make that connection, then test it. See Design Benefits Connectors.

What you are remapping

For the ANSI X12 834 V2 template, Create Benefits Connectors lists these integration maps:

Map What the carrier is usually changing
MapLoop2300_HD03 — Insurance Line Code for Standard Loop What the carrier is usually changingThe plan or product code in the HD segment (medical, dental, vision, and the carrier’s own line codes).
MapLoop2300_HD05 — Coverage Level Code What the carrier is usually changingThe coverage tier: employee only, employee plus spouse, family, and whatever codes the new guide now requires.
MapLoop2000_INS02 — Individual Relationship Code What the carrier is usually changingHow the carrier wants employee, spouse, and child coded.
MapLoop2100A_DMG03 — Gender Code What the carrier is usually changingThe carrier’s gender values, which often change when a guide is rewritten.
MapLoop2100A_DMG04 — Marital Status Code What the carrier is usually changingThe carrier’s marital-status values.

Providers may require maps beyond that list. The same chapter says the practical way to see which maps the template treats as essential is to run the integration after you create it and read the integration event messages.

Two other facts keep a mid-year code change from turning into a rebuild:

  • Use the ANSI X12 834 V2 template for 834 output. Workday says not to use named vendor templates that produce 834 files, because Workday does not enhance them and will deprecate them.
  • Enable one file-transmission service at a time. Changes Only, Actives Only, and the three Full File variants are separate services. Turning on a second one produces a warning, and the file contents follow whichever service is enabled.

The admin guide’s merger notes say the same thing in operational language: you can change integration maps so Workday values match the external endpoint, and a new plan or a new location often needs a new map entry. The example there is a medical provider that requires a proprietary code per state. See Setup Considerations: Benefits for Mergers and Acquisitions.

Do this before you touch the map

  1. Read the new companion guide for the segments you already send. Loop information is not written on the file. Workday and the carrier both use loop names to point at segments. Loop 2300 is where HD03 and HD05 land.
  2. Leave the benefit plan’s name alone if the plan itself did not change. The merger guide says not to rename an existing benefit plan or provider, because that hits current integrations and enrollment history. A code change in the guide is a map change. A real plan replacement is a new plan, linked to the existing integration when the provider stays the same, and unlinked when the plan is discontinued.
  3. If the carrier added a value Workday does not store, a map cannot invent it. Field overrides exist for a format or a value that is not directly available. Overrides accept one field. Conditional results belong in an Evaluate Expression or another calculated field, then that one field goes on the override. Enhance Benefits Connectors says complex calculated fields slow the event down, so keep the expression small.
  4. Confirm the integration system user can see the benefits data you expect. Workday recommends one integration system security group per product area and one integration system user per integration system. Compare the output with View Current Benefit Elections. Missing rows are either absent in Workday or invisible to that user.

Prove the new codes on a small file

The 834 V2 template includes CCB - Debug Service, which lets a launch include or exclude specific workers and dependents. Use it. A full population file is how a one-code change becomes an all-night compare.

For that test launch, set the dates the way the carrier will consume the real file. Enhance Benefits Connectors defines the parameters:

Launch parameter Role
Launch parameterEffective Date RoleStart of the range where enrollments are first valid.
Launch parameterFrom Effective Date RoleEnd of that range. Defaults to the current date.
Launch parameterLast Update RoleStart of the range for data entered in Workday. Often the current moment.
Launch parameterFrom Last Update Date RoleEnd of the entered range. Often one hour before the current moment.

Cloud Connect reports eligibility and enrollment for the benefit plan year of the Effective Date. A code remap that must include coverage ending at year-end needs an Effective Date on or before the last day of that plan year.

Then read the file, not the integration status. A completed event means Workday built a file. The carrier rejects it later, row by row, when HD03 or HD05 still carries the old code. Segment structure is stable: the segment id, an asterisk between elements, a tilde at the end. HD is the segment. Count elements after the segment id. That is the check against the guide.

Document retention on this template defaults to 30 days. Keep the test output long enough to compare with the carrier’s rejection, then let the retention policy drop it.

What a nightly changes-only job will and will not resend

CCB ANSI X12 834 V2 Changes Only reports new coverage, changes, and terminations in the current benefit plan year, and it depends on the Transaction Log Service. Workday preconfigures that log for this template and says not to modify it. A map correction does not rewrite history the carrier already accepted. If the carrier must replace codes on people who were not otherwise changed, the transmission service and the launch dates have to ask for those people. The full-file choices are in the open-enrollment file guide.

Where Roots fits

Kiweely Roots (coming next) sits outside the tenant and reaches Workday through standard APIs. For benefits it sends 834 files and carrier APIs, checked against each carrier’s own rules. A benefits fix is proven on Sandbox with the rows that failed, then waits for approval. Each integration has its own API client, scoped to what it reads, and the run keeps times, counts, and outcomes rather than the records. Register interest on the Roots page. Roots does not replace the companion guide or the Cloud Connect license Workday requires for the connector catalog.

Questions people ask on the night the guide changes

Do we build a new integration system?

Build a new system when the provider is new and the catalog template is the right starting point. For a new code set on a carrier you already send to, change the maps on the integration that already links that plan. The merger guide says to link a new plan from the same provider to the existing integration.

The event completed and the carrier still rejected rows. Which message matters?

The integration event’s messages name maps the template still needs. The carrier’s rejection names values the guide no longer accepts. Both can be true on the same night. Read HD03 and HD05 in the file against the new guide.

Can we rename the plan so the name matches the new code?

Leave the plan name. Renaming a plan or provider changes enrollment history and the integrations that already point at it. Put the carrier’s code in the map.

Sources checked

Related guides

All guides

Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.

We’ll email you once to confirm. Unsubscribe in one click from any issue.