Guidelines for Loading US City Taxes Card Components
The City Taxes card component is used to capture information that impact city tax calculations for the employee. Not all states require a City Taxes card component.
If updating values in an existing component, the effective date must be the original start date of the component.
If you load a City and you haven't loaded the State and County component, then it won't be visible in the application. State and County Taxes card components aren't automatically generated when you upload City Taxes.
City Taxes Card Component Hierarchy Image
The City Taxes card component uses value definitions to capture override values. Value definitions are supplied using the Calculation Value Definition and Enterable Calculation Value record types.
The following sections describe how to provide valid file lines for these record types.
Card Component Attributes for City Taxes
| HCM Data Loader Attribute | Alternative User Key Attributes | Functional Description |
|---|---|---|
| SourceSystemId | CardSequence, ComponentSequence, AssignmentNumber, DirCardDefinitionName, LegislativeDataGroupName, DirCardCompDefName | A unique identifier for the City Taxes card component. For new card components supply the source key attributes. You can also identify card components with the user key attributes. |
| SourceSystemOwner | N/A | The name of the source system owner used to generate the source system ID. |
| LegislativeDataGroupName | N/A | The name of the legislative data group for the card component definition. |
| DirCardId(SourceSystemId) | CardSequence, AssignmentNumber, DirCardDefinitionName, LegislativeDataGroupName | The parent Tax Withholding calculation card should be identified by using the same key type used to identify the calculation card. When using source keys, supply this attribute with the value supplied for the calculation card’s SourceSystemId attribute. Otherwise, supply the user key attributes with the same values as the parent calculation card. |
| EffectiveStartDate | N/A |
The start date of the City Taxes card component, typically the employee’s start date. This must be the same as the EffectiveStartDate on the Tax Withholding calculation card. If updating an existing State Taxes card component, the effective start date must be original start date of the component. |
| EffectiveEndDate | N/A | The end date is optional for the card component |
| DirCardCompDefName | N/A | The component definition name. Specify ‘City Taxes’. |
| ComponentSequence | N/A | The number to uniquely identify this card component when multiple card components with the same DirCardCompDefName exist. Not required when source keys are used. |
| Context1 | N/A | The geocode number that identifies the US state. |
| Context2 | N/A | The geocode number that identifies the county. |
| Context3 | N/A | The geocode number that identifies the city. |
These attributes are supplied against the CardComponent file discriminator and must be supplied along with a CalculationCard record for the parent Tax Withholding card. An example is provided in the Example of Loading Tax Withholding City Taxes topic.
Refer to Cloud Customer Connect topic Template: BI Publisher Report: United States - State, County and City Geography Codes to identify the valid values for the context attributes.
City Taxes Value Definitions
| Value Definition Name | Functional Description |
|---|---|
| Filing Status | The marital status of the employee city taxes are filed for. Provide a lookup code from the lookup type HRX_US_LOCAL_FILING_STATUS |
| Exempt from City or Township Income Tax | Indicates whether the employee is exempt from city or township income tax. Specify Y or N |
| Exempt from Occupational or Head Tax | Indicates whether the employee is exempt from occupation or head tax. Specify Y or N. |
| Exempt from School District | Indicates whether the employee is exempt from school district tax. Specify Y or N. |
| Exempt from Wage Accumulation | Indicates whether the employee is exempt from wage accumulation. Specify Y or N. |
| Resident Wage Accumulation | Provide a lookup code from the lookup type HRX_US_CITY_WAGE_ACCUM. |
| School District | Provide the appropriate school district code for that city if applicable. When only entering city information specify a value of -999999999. (See separate example for loading school district information at the city level). |
Calculation Value Definition Attributes for City Taxes
The Calculation Value Definition record type specifies the value definition name for the override value.
| HCM Data Loader Attribute | Alternative User Key Attributes | Functional Description |
|---|---|---|
| SourceSystemId | CardSequence, ComponentSequence, AssignmentNumber, DirCardDefinitionName, LegislativeDataGroupName, DirCardCompDefName | A unique identifier for the calculation value definition record. For new records supply the source key attributes. You can also identify calculation value definition records with the user key attributes. |
| SourceSystemOwner | N/A | The name of the source system owner used to generate the source system ID. |
| LegislativeDataGroupName | N/A | The name of the legislative data group for the card component definition. |
| SourceId(SourceSystemId) | CardSequence, ComponentSequence, AssignmentNumber, DirCardDefinitionName, LegislativeDataGroupName, DirCardCompDefName | The parent City Taxes card component should be referenced by using the same key type used to identify the card component. When using source keys, supply this attribute with the value supplied for the card component’s SourceSystemId attribute. Otherwise, supply the user key attributes with the same values as the parent card component. |
| EffectiveStartDate | N/A | The start date of the parent City Taxes card component or the date the calculation value definition starts, if later. |
| DirCardCompDefName | N/A | The definition name of the parent City Taxes card component. Specify the same value as provided on the parent card component record. |
| ValueDefinitionName | N/A | The name of the value being overridden. The list of value definitions applicable to this card component are listed above. |
| Context1 | N/A | The geocode number that identifies the US state. Specify the same value as Context1 on the parent City Taxes card component. |
| Context2 | N/A | The geocode number that identifies the county. Specify the same value as Context2 on the parent City Taxes card component. |
| Context3 | N/A | The geocode number that identifies the city. Specify the same value as Context3 on the parent City Taxes card component. |
These attributes are supplied against the CalculationValueDefinition file discriminator and must be supplied along with a CardComponent record for the parent City Taxes card component and a CalculationCard record for the owning Tax Withholding card.
An example is provided in the Example of Loading Tax Withholding City Taxes topic.
Enterable Calculation Value Attributes for City Taxes
The Enterable Calculation Value provides the override value for the value definition. It references the Calculation Value Definition record which defines the Value Definition being overridden.
| HCM Data Loader Attribute | Alternative User Key Attributes | Functional Description |
|---|---|---|
| SourceSystemId | CardSequence, ComponentSequence, AssignmentNumber, DirCardDefinitionName, LegislativeDataGroupName, DirCardCompDefName | A unique identifier for the enterable calculation value record. For new records supply the source key attributes. You can also identify calculation value definition records with the user key attributes. |
| SourceSystemOwner | N/A | The name of the source system owner used to generate the source system ID. |
| LegislativeDataGroupName | N/A | The name of the legislative data group for the override value. |
| ValueDefnIdSourceSystemId | CardSequence, ComponentSequence, AssignmentNumber, DirCardDefinitionName, LegislativeDataGroupName, DirCardCompDefName, ValueDefinitionName |
Identify the parent Calculation Value Definition record using the same key type used to identify the calculation value definition. When using source keys, supply this attribute with the value supplied for the calculation value definition’s SourceSystemId attribute. Otherwise, supply the user key attributes with the same values as the parent record. |
| EffectiveStartDate | N/A | The effective start date of the parent calculation value definition record, or the update to the override value if supplying date-effective history. |
| EffectiveEndDate | N/A | The optional end date of the override value, or if you are providing date-effective history, the last day of the date-effective changes |
| Value1 | N/A | The value for the value definition identified by the parent
calculation value definition record. Unlike other calculation cards, if you supply a value definition but have no value for it supply ‘-999999999’ to indicate a null value. |
These attributes are supplied against the EnterableValueDefinition file discriminator. You must supply an EnterableValueDefinition record for each CalculationValueDefinition record supplied.
An example is provided in the Example of Loading US Tax Withholding City Taxes topic.