A GL code mapping tells Everee which general ledger code a line of the payroll journal should carry. Once your company has mapped its GL codes, every journal line comes with the code it belongs to, and the Payroll Journal report in Everee shows the same codes. You can create and maintain your mappings with this API, or in Everee's admin portal. Both work on the same mappings.
Some companies need a different GL code for the same kind of line depending on which approval group or work location it's for. You can map GL codes that way too. See Scoping mappings by approval group or work location.
How does a mapping work?
A mapping has three levels of detail, matching the fields of a journal line:
| Field | What it narrows to | If you leave it out |
|---|---|---|
category | The kind of line: GrossPay, EmployerTaxes, and so on. See What are the line categories? | Required |
transactionType | One type within the category, like the REGULAR_HOURLY earning type or the Social Security (ER) tax | The mapping covers every type in the category |
transactionDetail | One detail of that type, like a particular pay code label or tax jurisdiction | The mapping covers every detail of the type. Needs a transactionType |
Each mapping also has a glCode, and an optional description for your own notes.
A journal line takes the most specific mapping that matches it: category, type, and detail; otherwise category and type; otherwise the category alone; otherwise it has no GL code, and its glCode is null. There's at most one mapping at each level, so a line never has two equally specific candidates.
For example, these three mappings code every wage line 6000, field hours 6010, and one particular pay code 6015:
[
{ "category": "GrossPay", "glCode": "6000" },
{ "category": "GrossPay", "transactionType": "FIELD_HOURS", "glCode": "6010" },
{ "category": "GrossPay", "transactionType": "FIELD_HOURS", "transactionDetail": "Night Field Hours", "glCode": "6015" }
]What values can I use for the type and detail?
A mapping matches the transactionType and transactionDetail of a journal line exactly, so use the values the journal reports. The easiest way to find them is to retrieve a journal and look at its lines. You can also list suggested transaction types for a category: the earning types and pay codes you've set up, the employer taxes by name, the benefit types, and so on.
Suggestions are only suggestions. A mapping accepts any text, so you can map a type that doesn't exist yet, and it takes effect once a line has it.
How do I create and change mappings?
Send your mappings to Create or update GL mappings. Each one is matched to an existing mapping by its category, type, detail, and scope (see below). If there's a match, its GL code and description are updated. If not, a new mapping is created. So you can send your whole set of mappings every time you sync, without creating duplicates.
- You can send up to 500 mappings in one request.
- They're all validated before any are saved. If one is invalid, none of them are.
- A GL code can be up to 100 characters. Types, details, and descriptions can be up to 255.
- Blank types, details, and descriptions are treated as if you left them out.
List your mappings to see what you have, and delete a mapping you no longer want. Lines that used a deleted mapping fall back to a less specific one, or have no GL code.
GL codes are worked out when you retrieve a journal, not when the funding is made. So a change to a mapping applies to every journal you retrieve afterward, including journals of fundings in the past.
Scoping mappings by approval group or work location
By default, a company has only master mappings: one set of GL codes for every line. If your company needs different GL codes for different approval groups, or different work locations, it can scope its mappings. A scoped mapping applies only to the lines of one approval group or one work location. You choose one dimension for your company, approval group or work location, not both.
Turning scoping on
- Set the scope of your company to
APPROVAL_GROUPorWORK_LOCATION. You can retrieve the setting at any time. A company that hasn't chosen has the scopeNONE. - Create mappings with an
approvalGroupId, or with aworkLocationId, depending on the dimension you chose. The group or location must belong to your company.
[
{ "category": "GrossPay", "glCode": "6000" },
{ "category": "GrossPay", "approvalGroupId": 5, "glCode": "6100" }
]A scoped mapping has the same levels as a master mapping: a category, optionally narrowed to a type, and a detail. A master mapping and a scoped mapping, or the mappings of two different groups, are separate mappings, even when their category, type, and detail are the same.
You can only create mappings scoped by your company's dimension. If your scope is WORK_LOCATION, a mapping with an approvalGroupId is rejected, and so is a mapping with both an approvalGroupId and a workLocationId.
To list the mappings of one group or location, pass approvalGroupId or workLocationId to List GL mappings. Pass master=true for the master mappings.
How do lines get their GL code?
A journal line is looked up in two steps:
- The mappings of the line's own approval group or work location. The most specific one that matches the line wins, as described above.
- If its group or location has no mapping that matches, the master mappings, again the most specific one that matches.
The first step always wins, even when the master mapping is more specific. Let's say you've mapped these:
| Scope | Category | Type | GL code |
|---|---|---|---|
| Master | GrossPay | 6000 | |
| Master | GrossPay | REGULAR_HOURLY | 6001 |
| Approval group "Field Crew" | GrossPay | 6100 |
A regular hourly wage line of the Field Crew group gets 6100, because Field Crew has a mapping for the GrossPay category and that's checked before the master mappings. If you want the 6001 code for regular hourly wages of Field Crew, give Field Crew its own REGULAR_HOURLY mapping. Regular hourly wages of every other group still get 6001, and a FIELD_HOURS line of any group but Field Crew gets 6000.
In short: a group or location's mappings are a complete set of overrides, and any line they don't cover uses the master mappings.
A broad scoped mapping covers more than you may expectA scoped mapping for a whole category overrides every master mapping within that category for the group or location, including the more specific ones. If you only want to change one type, map just that type.
A few kinds of lines don't belong to any approval group or work location: Liabilities and PayrollFunding lines. They always use the master mappings.
Wages are coded to the approval group or work location on the earning. Everything else on a payment, like employer taxes and benefit costs, is split across the wages of the payment, so it follows the wages. A payment with wages for two groups has its employer costs split between them, in proportion to the wages, and each part gets its own group's GL code. This is the same split the journal uses for cost centers. See How are lines split?
This happens even if you don't split the journal by approval group or work location with group-by. The journal still has the lines it would have without scoping, with one difference: lines that get different GL codes are kept as separate lines, rather than combined into one. The amounts of the journal and its totals don't change.
Changing the dimension
You can't change your company's dimension while scoped mappings exist. The request to set the scope is rejected, and tells you how many scoped mappings there are. Mappings of a deleted approval group don't count, as explained below. Delete them first, and then choose the new dimension. Setting the dimension you already have does nothing, and so does setting it to NONE when you've only master mappings.
Master mappings aren't affected by a change. They're used by every line, whatever your scope is.
When an approval group or work location goes away
- An archived work location keeps its mappings, and they keep applying to journals of its past fundings.
- A deleted approval group keeps its mappings too, and they keep applying to journals of past fundings as long as your company scopes by approval group. They show up when you list your mappings, and you can still delete them. They don't stop you from changing your company's dimension, but once you do, they no longer apply to any journal. Delete them if you don't need them.
- A work location that's permanently deleted takes its mappings with it.