Defining Forms Processing Options
Forms processing is a core function for a tax authority.
Registration forms are used for taxpayer registration and / or taxpayer demographic information updates. These forms are processed in the context of a taxpayer. When a registration form is processed, it usually results in the creation of new taxpayers / accounts / tax roles / obligations or updates to existing taxpayer information - e.g. name / address change.
Tax forms are the most common types of forms. These forms are processed in the context of a filing period. When a tax form is filed, it satisfies an obligation to file and its processing results in an assessment.
Most forms have a common structure. The form consists of one or more sections, with each section containing one or more lines or groups of lines. Processing rules can be associated with any of these components.
As form changes are introduced from year to year, the changes usually entail adding or removing specific sections and / or lines, as well as adding / removing the processing rules associated with them.
Forms can come from one or more sources. They can be interfaced in batch from an external system or created internally.
Contents
The Big Picture of Registration
The Big Picture of Form Definition
The Big Picture of Form Versions
The Big Picture of Forms Upload
Setting Up Form Processing Options
Registration forms are used for maintaining taxpayer demographic information. Examples of these forms are a business registration form and a change of address form.
A taxpayer is registered in any of the following ways:
· The taxpayer files a paper registration form
· The taxpayer submits a registration form online.
· A tax authority user registers the taxpayer using an online registration form
· For some tax types, the system can automatically register the taxpayer when the first tax form is processed.
Contents
Registration Forms Are Linked to Taxpayers
Registration Forms Have A Common Lifecycle
Registration Forms Are Linked to Taxpayers
Registration forms create / update taxpayer information. When a registration form posts, it may include actions like adding / updating accounts, tax roles and obligations.
Unlike tax forms, registration forms typically don't result in assessments. Thus, these forms usually do not have a financial effect.
Registration Forms Have A Common Lifecycle
Most registration forms go through a similar lifecycle:
The registration form is created in an initial state where processing rules are not yet executed. This allows the form to be saved as work-in-progress.
Contents
Registration Form - Validation
Registration Form - Waiting for Information
Registration Form - Validation
A validation step verifies the information on the registration form. Any issues detected at this step usually causes form processing to stop.
Registration Form - Suspense
A registration form goes into this state when the validation step detects errors on the form that a user may be able to investigate and resolve. Exceptions are stored in the system so that a user can resolve the issues accordingly. The form needs to be re-validated after the issues are resolved.
Registration Form - Waiting for Information
A registration form goes into this state when the validation step detects missing information, thus preventing the system from further proceeding with form processing. Exceptions are stored in the system so that a user can track the issues accordingly. In addition, this state usually triggers correspondence to the taxpayer, requesting for the missing information. The form is usually re-validated after the missing information is received.
Registration Form - Posting
When a tax form passes validation, it is posted in the system. Actions can include creating the taxpayer / account / tax role / obligation, confirming registrations, etc.
A tax form fulfills an obligation to file a tax return for a specific filing period. When a tax form is processed, it results in an assessment, which determines either a tax amount due or an overpayment.
Contents
Tax Forms Are Linked to Obligations
Tax Forms Have A Common Lifecycle
Other Changes After a Tax Form Posts
Tax Forms Are Linked to Obligations
When a tax form is posted, it is associated with an obligation for a specific filing period. Any financial transactions relating to the filing period will be created under this obligation. The obligation can be created in advance in anticipation of filing, such as in the case of business taxes or created at the time the form is posted, such as in the case of individual income tax.
The form type references one or more obligation types, and this information is used when determining what type of obligation to create for a specific tax form. Typically a form type would only reference one obligation type. For example, taxes such as sales and use, individual income, and corporate income would typically have one obligation type defined per form type. The base business object C1-StandardTaxFormType supports the definition of one obligation type on a form type.
There are situations where a form type would be associated with more than one obligation type. These include business activity statements, estimated payments, audit forms. A different business object can be used to support these situations. Alternatively, the validation on the base business object can be disabled to allow more than one obligation type for a form type.
The obligation types defined for a form type are used to restrict the form type list for a specific tax type, when a user adds a tax form.
Tax Forms Have A Common Lifecycle
Most tax forms go through a similar lifecycle.
The tax form is created in an initial state where processing rules are not yet executed. This allows the form to be saved as work-in-progress.
Contents
Tax Form - Waiting for Information
Tax Form - Validation
A validation step verifies the information on the tax form. Any issues detected at this step usually causes form processing to stop.
Tax Form - Suspense
A tax form goes into this state when the validation step detects errors on the form that a user may be able to investigate and resolve. Exceptions are stored in the system so that a user can resolve the issues accordingly. The form needs to be re-validated after the issues are resolved.
Tax Form - Waiting for Information
A tax form goes into this state when the validation step detects missing information, thus preventing the system from further proceeding with form processing. Exceptions are stored in the system so that a user can track the issues accordingly. In addition, this state usually triggers correspondence to the taxpayer, requesting for the missing information. The form is usually re-validated after the missing information is received
Tax Form - Posting
When a tax form passes validation, it is posted in the system. Actions can include creating the taxpayer / account / tax role / obligation, creating financial transactions, etc.
Tax Form - Adjust
A posted tax form can be adjusted for any of the following common reasons:
· Correcting data capture errors or data entry errors
· Line item adjustments initiated by the taxpayer
· Adjustments initiated from an audit
When a tax form is adjusted, the financial effect of the existing tax form is canceled and new financial transactions are created for the updated line items.
Tax Form - Transfer
A tax form can be transferred to a different taxpayer/obligation if it previously posted to the incorrect taxpayer/obligation.
When a tax form is transferred, the financial effect of the existing tax form is removed from the current obligation and new financial transactions are created for the 'transfer to' obligation.
Tax Form - Reversal
Some exceptional cases may require that the financial effect of a tax form be canceled, without necessarily creating new financial transactions. A tax form reversal is a way of voiding a tax form that has already posted.
Tax Form Lifecycle Example
The base package provides a sample tax form C1-ParentTaxForm that has a common lifecycle.
Refer to the Business Object metadata for more information.
Categorizing States
The business objects provided in the base product include a status option for the states in the lifecycle called Status Category. The values provided in base identify the states in which the form is considered In Effect and the states in which it is considered Not In Effect. This setting may be used in code to allow or prevent certain actions from occurring based on the state of the form. For example, a user may not cancel an Obligation if there are any tax forms for the obligation whose state is In Effect.
In addition, the POSTED status defines an additional status category value for Posted, allowing for validation or processing based on whether a form is posted or not.
This option allows multiple values to exist for a given state.
Other Changes After a Tax Form Posts
The following sections describe other possible changes after a tax form posts.
Contents
Standalone Amendment Forms
A posted tax form can also be adjusted by processing a standalone amendment form. In this case, the amendment form is processed independently of the original form. New financial transactions are created for the difference between the financial effect of the original form and the financial effect of the amendment form.
Standalone Audit Forms
A standalone audit form can also adjust a previously posted tax form. In this case, the audit form is processed independently of the original form. New financial transactions are created for the difference between the financial effect of the original form and the financial effect of the audit form.
Payments Related to Tax Forms
Some tax types require taxpayers to make estimated payments based on specific conditions - e.g. estimated revenue, estimated tax liability, etc. The system allows for payments to be made in advance. These payments are usually reconciled when the associated tax forms are processed.
The system also caters for payments sent together with tax forms. The payments are usually created when the form posts, suspends or cancels (depending on the situation).
Contents
Payments in Advance / Estimated Payments
Directing a Payment to a Form or Filing Period
Payments in Advance / Estimated Payments
Some tax types require taxpayers to make estimated payments based on specific conditions -e.g. estimated revenue, estimated tax liability, etc.
When the payment is processed, the obligation may or may not exist yet.
· If the obligation exists, the payment is applied to that obligation
· If an obligation does not exist but the taxpayer has an existing account, the payment is applied to an excess credit obligation under that account.
· If the taxpayer does not have any accounts, the payment is applied to a company suspense account.
In the cases where the payment got applied to an excess credit obligation or company suspense, the payment needs to be transferred when the tax form is processed and the obligation is determined. To do this, a form rule needs to be configured to do this transfer at the point where the form's obligation is identified.
Refer to Defining Form Rules for details on how to configure rules.
It's important for the payment to capture details that will facilitate the transfer of the payment to the correct obligation when the tax form gets processed. The payment should capture details like the taxpayer's identifier and the tax type / filing period being paid.
Payments with a Tax Form
When payments are sent with a tax form, the payment is usually linked to the form by a unique identifier, such as a document locator.
The payment is processed in two possible ways, which are described in the following sections
Contents
Payment Is Processed Separately From The Tax Form
Payment Is Processed With The Tax Form
Payment Is Processed Separately From The Tax Form
This is applicable for implementations that have separate processes for payments and forms.
In this case, the payment is applied depending on which of the payment and the tax from gets processed first:
· If the tax form is processed before the payment, the payment is applied to the obligation on the form.
· If the payment is processed before the tax form and:
· The taxpayer has an existing account, the payment is applied to an excess credit obligation under that account
· The taxpayer does not have any accounts; the payment is applied to a company suspense account.
In the cases where the payment got applied to an excess credit obligation or company suspense, the payment needs to be transferred when the tax form is processed and the obligation is determined. To do this, a form rule needs to be configured to do this transfer at the point where the form's obligation is identified.
Refer to Defining Form Rules for details on how to configure rules.
It's important for the payment to capture details that will facilitate the transfer of the payment to the correct obligation when the tax form gets processed. The payment should capture details like the taxpayer's identifier and the tax type / filing period being paid.
Payment Is Processed With The Tax Form
This usually occurs when payments are uploaded with tax forms.
In this case, the payment is not created until the form is processed. In order to process payments within tax form processing, a form rule needs to be configured.
Refer to Defining Form Rules for details on how to configure rules.
Directing a Payment to a Form or Filing Period
The base package provides a Pay A Form / Filing Period Distribution Rule - Create Payment algorithm type C1-PAYFRM. This algorithm type assumes that the payment event distribution details can be specified as any of the following
· Document locator only. The algorithm will post the payment to the tax form's obligation. If the tax form is not found, the payment is applied to either an excess credit obligation or company suspense account.
· Document locator with taxpayer identifier number, tax type and filing period. The algorithm will post the payment to the tax form's obligation. If the tax form is not found, the payment is applied to either an excess credit obligation or company suspense account.
· Taxpayer identifier number, tax type and filing period (i.e. advanced / estimated payments). The algorithm will post the payment to either an excess credit obligation or to company suspense account.
To enable this algorithm type:
· Configure an algorithm for C1-PAYFRM with the appropriate parameters. Use base characteristic types for DLN, Taxpayer Identifier, Tax Type and Filing Period.
· Create distribution rules for each of the distribution details. Use base characteristic types for DLN, Taxpayer Identifier, Tax Type and Filing Period.
· Plug in your Pay A Form / Filing Period algorithm in one of the distribution rules you created.
The distribution detail with the 'create payment' algorithm is last. When creating the payment event using the above distribution rules, the detail that has the 'create payment' algorithm must be specified as the last. This ensures that all details are available by the time the algorithm executes.
Contents
Form Type Controls Form Processing
Designing The Form's Processing Rules
Form Type Controls Form Processing
Each tax form or registration form must reference a form type. The form type may reference business objects that define:
· The structure, lifecycle, processing rules and processing options of the form type itself.
· The structure, lifecycle, processing rules and processing options of the actual tax form or registration form.
Designing Form Types
A Form Type needs to be configured for each type of form that the system needs to process.
The following are the steps in configuring a form type:
· Define basic information about the form type, including the business object that controls the behavior of the form type. The base product provides the business object C1-StandardTaxFormType, which is used for automatic generation of tax form business objects. Also determine the applicability of change reasons to the form type.
· Define the sections of the form.
· Define the lines that each section contains.
· Generate the form type.
· Define the valid form change reasons to the form type, if change reasons are applicable.
· Link the form type to form rule groups.
Contents
Assigning Business Names to Sections and Lines
Designing Sections
When designing sections of your form, the first thing to determine is the number of sections. Small or simple forms may contain only one or two sections, while complex forms, such as forms with schedules, usually contain many sections.
Identify any repeating sections. This is common with tax forms that allow multiple occurrences of a schedule. For such recurring sections, determine whether or not recurrence should be limited to a finite number.
Designing Lines
After establishing the sections, you need to define the information that is contained in each of the sections. Some sections could include one or more simple lines. Some sections may include one or more repeating groups of lines. Other sections may have a mix of simple lines and repeating groups.
Define each line. Most lines on a tax form are either character or numeric fields. These lines could simply contain a value or could capture additional information.
The base package supports three common types of lines: Standard Line, Group Line and Label Line
Contents
Standard Lines
Most form lines fall into this category. This type of line usually contains the current value of the line.
This line type may also contain additional information that relates to the line's current values. For example, the value that was originally reported by the taxpayer (also referred to as the 'as reported' value), a reason explaining a difference between the 'as reported' and 'current values', an indication that rules processing should bypass any calculations and take the current value as-is, etc.
Refer to the definition of business object C1-StandardLine for more details.
Group Lines
This type of line is used for defining repeating lines in the section. This line contains header information about the group. Every line that belongs to the group refers to their header line.
Refer to the definition of business object C1-GroupLine for more details.
Label Lines
This line type is used for displaying text on the form.
Refer to the definition of business object C1-LabelLine for more details.
Assigning Business Names to Sections and Lines
Sections and lines are assigned business names to give form rules configuration a way of referencing the sections and lines, without necessarily knowing the specific form types that contain them. This allows form rules to be configured for reuse across several form types.
The actual instances of the sections and lines within a form type are determined when the rules are executed.
Refer to Defining Form Rules for details on how to configure rules.
Designing Form Change Reasons
As part of designing your form types, you will need to decide if the form should require the user to supply a change reason when modifying a form. The form type includes the following configuration:
· Overall Change Reason Applicability - this controls whether change reason is used at the overall form level.
· Set this to Required if the user needs to enter a change reason when making changes to a form.
· Set this to Optional if the user can choose to enter a change reason but is not required.
· Set this to Not Applicable if this form does not use overall change reasons. This will suppress the change reasons grid and comments from the main section of the form’s UI map.
· Line Change Reason Applicability - this controls whether change reasons are used at the individual form line level.
· Set this to Applicable if this form uses change reasons at the form line level for one or more of its form lines. The change reasons definition checkboxes will be enabled when defining a form line.
· Set this to Not Applicable if this form does not allow change reasons at the form line level. The change reason definition checkboxes will be disabled when defining a form line.
In addition to controlling which change reasons fields appear on the form’s UI map, the applicability flags also control the validation for change reasons on the form. See Determining When a Change Reason is Required for more information.
If form change reasons are going to be used with this form type, then a list of one or more change reasons needs to be defined. This list defines the valid change reasons for the form type and is used to create the dropdowns on the form for the user to choose from.
Some change reasons are used by algorithms that update a form, rather than a user. These change reasons will have a system default flag associated with them and will not appear on the dropdown presented to the user. A lookup defines which system transitions can be used. Additional values can be added by an implementation as needed.
The base package provides the algorithm type C1-DFLTFCR that defaults a change reason when a form is suspended or is waiting for information. If your form’s business object is using the business object C1-ParentTaxForm, you will need to have one change reason with the system default flag of Form Transition.
Generating Forms
The base package provides a form type business object C1-StandardTaxFormType that can be used for generating most tax form types. This business object's lifecycle includes a generation step and that allows for regenerations when needed.
Contents
Overriding the Generated UI Maps
The Lifecycle of a Form Type
A form type is created and stays in a 'pending' state while the details about the form type, its sections and its lines are being configured.
Once the structure of the form type, sections and lines are defined, the next step is to generate the form business object and its UI maps.
If form generation encounters any problems, the form type goes into an error state. The user needs to fix the issue(s) and regenerate the form.
On the other hand, if form generation is successful, the form type goes into a 'generated' state until the user activates it.
Activated forms can be inactivated.
If changes need to be made after a form type is already generated, a user could put the form type back into the 'pending' state and change / regenerate the form type accordingly.
The same could be true for activated or inactivated form types - if changes are allowed when the form type is already in either of these states.
The Form Generation Process
The following diagram illustrates the form generation process flow.
Form Generation
The steps are discussed in the following sections.
Generating the Form Type
When using the base business object C1-StandardTaxFormType for generating tax forms, the form generator is invoked when the form type goes into the Generated state.
An 'enter' algorithm (C1-GEN-FORM) invokes the following processes (in order):
· Form Business Object Generation
· Form Display Map Generation
· Form Maintenance Map Generation
All three processes have to run successfully.
If any of the processes fail, the algorithm creates an appropriate log entry to indicate which one failed. Any components that were generated prior to hitting the error are rolled back.
Contents
Form Business Object Generation
Form Display / Maintenance UI Map Generation
Form Business Object Generation
This process creates a form business object using the form definition data on the form type. It includes intermediate steps for: creating Field metadata, creating Lookup Fields / Values and extracting form definition data.
Contents
This process goes through the form type's section and line definitions and creates label fields, definition fields and override label fields based on the section and line configurations. For definition fields that are configured as lookups, this process has an additional step of creating the Lookup Fields and their Lookup Values.
This process extracts the form type / section / line definitions into one XML document that feeds into both the business object creation and UI map generation processes.
This process creates the form business object using the form definition XML data that was extracted prior. The form business object is created as a 'child' BO that inherits from a parent form business object - as defined on the form type business object's 'Form Parent Business Object' option.
Note. The C1-StandardTaxFormType references C1-ParentTaxForm as its 'Form Parent Business Object'.
Any common form elements should be placed in the parent form BO's schema. Other form elements that vary between form types should have corresponding Line definitions. The sections and line definition are generated into the form BO schema accordingly.
This process also creates the Application Service for the generated business object. The associated access modes are the same as the parent business object's access modes.
Note. These generated Application Services must be configured on your user groups accordingly.
Form Display / Maintenance UI Map Generation
These processes create the form's display and maintenance UI maps and automatically link the maps to the generated form BO.
The 'Form Display/Maintenance UI XLS Stylesheet' specified on the form type business object controls how the HTMLs in these maps are generated.
Reserved Primary Keys
The form generator populates the primary keys of the generated components as follows:
· Form BO code (max length 30) = Form Type code (max length 12)
· Display UI Map code (max length 30) = Form Type code (max length 12) + 'Display'
· Maintenance UI Map code (max length 30) = Form Type code (max length 12) + 'Maint'
· BO Application Service ID (max length 20) = Form Type code (max length 12 - note: this is also the generated BO code) + 'BOAS'
If initial generation of BOs / UI maps / application services finds a conflict with any existing CM primary keys for the same objects, form generation will result in an error. Either the existing CM objects or the new Form Type code should be changed accordingly.
Regenerating a Form Type
Refer to The Lifecycle of a Form Type for information on when / how a form type is regenerated.
Once the form business object / UI maps / application services exist, any subsequent form type regeneration will retain the primary key, as well as most of the references associated with the generated objects - e.g. BO options, BO plug-ins, etc. Only the following updates would take place:
· The existing BO’s schema is replaced.
· The existing UI maps’ HTML is replaced.
· If the parent form BO referenced on the form type has changed since the last generation:
· The Parent BO and Maintenance Object references on the existing BO are replaced.
· The access modes on the child application services are replaced.
Overriding the Generated UI Maps
The look-and-feel of the generated UI maps is controlled by an XSL stylesheet that is specified on the form type business object's 'Form Display/Maintenance UI XSL Stylesheet' option.
Contents
Overriding All Generated UI Maps
Overriding Specific Generated UI Maps
Overriding All Generated UI Maps
If your implementation needs to override the look-and-feel of all generated UI maps, you can specify your own XSL Stylesheet on the form type business object.
If you are using the base form type business object, you need toadd a 'Form Display/Maintenance UI XSL Stylesheet' option with a higher sequence.
Overriding Specific Generated UI Maps
If your implementation needs to override the look-and-feel of specific UI maps or if you need to add implementation-specific logic to the generated UI maps, you can do the following:
· Make a CM copy of the generated UI maps and put the additional logic on those copies.
· Plug the CM UI maps into the corresponding BO option types on the generated form BO. Use a higher sequence number than the base-generated BO options. The 'UI map' BO options types are single-instance options, for which the FW knows to use the options with the highest sequence number.
Note. Generated UI maps will use sequence number 10. CM maps must use sequence numbers higher than 10. If your CM maps do not follow this rule, you will lose your CM maps' links to the BO after regeneration.
When the BO and generated UI maps are regenerated, the form generator process simply replaces the XML in the BO schema and the HTML in the UI maps. The BO options added from the initial generation are retained. Thus, any CM UI maps would continue to be in effect.
After regeneration, your implementation must compare the generated maps with the override maps and copy the differences to the override maps accordingly.
Designing The Form's Processing Rules
The final step in configuring a form is the definition of processing rules.
Refer to Defining Form Rules for details on how to configure rules.
A form is likely be modified several times during its lifetime. Whenever one or more changes are made to a form, a new form version is created. The rules that determine which changes constitute a new form version vary from one tax authority to another.
In general, there are two main categories of form changes:
· User correction. These are changes made to a form by a user for a variety of reasons such as correcting a scanning error, correcting a taxpayer error, update of a mailing address resulting from a taxpayer phone call, or correction of a form's receive date.
· Auto correction. These are changes made automatically by the system for reasons such as correction of a calculation error.
The tax authority requires the ability to track changes to a form for a couple of reasons:
· Audit Trail. The need to track who made the changes to the form and when the changes were made.
· Taxpayer Inquiry. The tax authority needs to be able to explain to the taxpayer any differences between the information that the taxpayer reported and the current information on the form.
Contents
Form Changes Typically Require a Reason
Determining When a Change Reason is Required
How are Form Versions Created
A form version is created when the form is modified either by a user or by a backend process (e.g. algorithm, service). The base package business object C1-ParentTaxFormincludes two algorithms, which take a snapshot of the form that is being changed and store it in a special type of log record.
This log record, with a log type of Form Version, includes the details of the form version such as the user who made the change, the date and time of the change and a snapshot of the whole changed form.
The form versions will get created in the following scenarios:
· A pending form is transitioned to the next state. When the form exits the Pending status, the algorithm type C1-PTF-UARI will create the initial form version. This version is also known as the ‘As Reported’ version. Its purpose is to capture the form’s data as reported by the taxpayer.
· A form is modified and is in a status that indicates a version should be created. The base business object includes the audit algorithm type C1-TXCREFRMV. This algorithm type will create a form version if the form is in a status that has the status option Enable Versions set to Y and any of the form’s fields have changed.
Form Version Display
A form version is stored as a snapshot on the tax form log record. A user can view this form version on the Tax Form - Versions portal. This portal contains a list of the form versions for the tax form in context. A user can select a form version from the list and have it displayed below.
The form version is displayed using a derived map zone, which utilizes the same UI map used by the form itself. A derivation script looks at the form’s business object options to determine which display UI map and display map service script should be used. This allows the form version to have the same look and feel as the form itself.
Form Changes Typically Require a Reason
Typically when a user makes a change to a form, they will be required to enter a reason for making the change. Some tax authorities require a user to enter a specific reason for each line that is changed, while others only require a more generic reason that describes the nature of the change for the overall form. The types of form changes supported by the base package are:
· Overall Change Reason. This change reason is specified at the form level and is used to describe the nature of the changes made to the form. Some examples include: corrected scanning error, data entry, and form rules auto correction.
· Line Change Reason. This change reason is specified at the form line level and is used to describe the specific change made to a form line. Some examples include: additional information provided by taxpayer, supporting documentation not accurate. It is possible for some form lines to be associated with a form change reason while others do not. For example, a change to an address might not require a change reason, while a change to the deductions amount will. The forms definition facility allows you to define the lines that need a change reason.
The form type controls which type(s) of change reason are applicable to the form, if any. A form type can be set up to require overall change reasons, form line change reasons, both or none. See Designing Form Change Reasons for more information on how a form type can be set up to use change reasons.
Determining When a Change Reason is Required
The base business object C1-ParentTaxForm includes a validation algorithm type C1-PTF-VCRS. This algorithm type uses the following conditions to determine if a change reason is required:
· Change reasons are only required if the status of the form is configured to enable versions.
· If the form type indicates that the Overall Change Reasons Applicability is Required, at least one form change reason should be supplied. On the other hand, if the form type indicates that the Overall Change Reasons Applicability is Not Allowed, form change reasons cannot be populated.
· If the form type indicates that the Line Change Reason Applicability is Applicable, a form change reason will be required for each line that has changed that is defined to have a form change reason. On the other hand, if Line Change Reason Applicability is Not Applicable, no line change reasons should be specified.
· Any form change reason that is populated on a form must be valid for the form’s form type.
The following topics describe logic related to uploading batches of forms.
Contents
Forms Can Come From Different Sources
Form Batch Header Groups Form Upload Records
A Batch Can Group Forms Into Submissions
Form Upload Staging Holds Form Data
Form Upload Staging Type Controls Everything
Forms Can Come From Different Sources
Forms are created in the system through a number of different ways. These methods of entering forms in the system are often referred to as 'channels'.
Most forms are uploaded in batch. This is a two-step process:
· Your implementation populates the form upload tables. That is referred to as 'Process X'.
· The base product processes the upload data and creates the corresponding tax forms and / or registration forms.
See Designing Form Sources and Setting Up Form Sources for details on how to configure your form sources.
Form Batch Header Groups Form Upload Records
A form batch header is used to group form upload records together. It holds control information - e.g. number of form upload records, total payment amounts, etc.
A form batch header also controls the types of forms that can be put together in the same batch.
Refer Designing Form Batch Headers for details on how to configure form batch headers.
A Batch Can Group Forms Into Submissions
A batch can contain one or more submissions. A submission or a 'return' is a group of related forms that a taxpayer submits. It usually contains a main tax form and zero / one / more child forms. An example is an individual income submission where the income tax form is accompanied by a number of schedules and statements.
The product expects all documents supporting a single submission or 'return' to be included in a single form upload staging record that results in a single tax form or registration form, with sections representing the separate schedules and statements.
Form Upload Staging Holds Form Data
Actual tax / registration form data is uploaded via form upload staging record. A form upload staging record references a type, which determines how the upload data is mapped and stored in into the tax / registration form tables.
If tax / registration form creation is successful, the created form is linked to the form upload staging record.
Form Upload Staging Type Controls Everything
Each form upload staging record has a reference to its type. Form upload staging type controls how form upload data is stored into the product's tax form and registration form tables.
The bulk of your forms upload configuration will be spent configuring form upload staging types and defining the mapping of data from the different sources to your target form schemas in the system.
If your form sources each use a different record format / layout for interfacing a given form, a form upload staging type must be defined per unique combination of the destination form type and form source.
The mapping of the input form data into the target form schemas is done in the Map Form Upload Data algorithm plugged into the business object for the form upload staging type. The base product provides a form upload staging type BO C1-FormUploadStagingType that uses XSL transformation to map the raw XML data into the target tax / registration form schemas.
Base plug-ins. Click here to see the algorithm types available for this system event.
Refer to Designing Form Upload Staging Types and Setting Up Form Upload Staging Types for details on how to configure your form upload staging types.
Forms Upload Process Flow
The following diagram illustrates the general process flows for form batch headers and form upload staging records.
Form upload staging records are not processed until the form batch headers they belong to have passed validation.
Any errors during the validation of a form batch header cause it to suspend for user review. The user is responsible for resolving the issues and re-validating the form batch header. At this point, the form upload staging records are still in their initial states. In some cases, the user may decide that the batch needs to be canceled, in which case the related form upload staging records are also canceled.
When the batch header passes validation, its form upload staging records can start processing. The batch sits in that processing state until either all staging records are in some final state - i.e. form added successfully, rejected or canceled.
Each form upload staging record goes through a number of processing steps before the corresponding tax form or registration form can be added. Any issues from these processing steps prevent the corresponding form from getting added.
· The form upload staging is validated. Any errors during form upload staging validation cause the form upload staging to get suspended for user review. The user is responsible for resolving the issues and re-validating the form upload record. In some cases, the user may decide that the form upload staging needs to be canceled. Note that at this point, the corresponding form is not created yet.
· When a form upload staging suspends, its batch header status stays the same - i.e. in the 'processing' state. The idea is that a user may be able to fix the issue with the staging record or decide to cancel it. Either action on the current staging record should not prevent other staging records in the batch from being processed.
· When the form upload staging passes validation, it goes through the important step of mapping the fields from the raw XML into the target Form business object schema.
· Any problems with this transformation are likely to be technical issues (e.g. malformed XML) that a user would not be able to fix. As a result, the form upload staging record gets rejected.
· On the other hand, if the transformation is successful, the form upload staging goes into a state where the tax form or registration form can be added / loaded.
If any of the form upload staging records is rejected, the batch header requires a user to review the batch and decide what to do next. A user may take either of these actions:
· Cancel the batch. This is likely when a majority of the records are rejected. Canceling the batch also cancels its form upload staging records. Note that at this point, there are no forms existing yet because the batch is in a cancelable state.
· Let the batch complete. This happens if only a few records in the batch got rejected.
When all form upload staging records are either in Ready for Load state or are Canceled, the batch transitions to the Ready to Complete state. This interim state is one where batch cancellation is no longer possible. This ensures two things:
· That forms for that batch are added at the same time
· That once the forms are added, the batch cannot be canceled. Allowing batch cancellation when some forms are already added would require cleaning up the forms - i.e. canceling any pending / suspended / waiting forms get canceled and reversing any posted tax forms.
When the batch is in a Ready to Complete state, the forms in that batch can be added. When the forms are successfully added, their form upload staging records go to their final state, Form Added. Once all form upload staging records are in a final state, the batch is completed.
Including Payments With Forms
Payments are uploaded with tax forms by specifying payments amounts on the corresponding form upload staging records. The actual sum of payment amounts from the form upload staging records within a batch are verified against the total payment amount specified on the form batch header.
The payment amount on the form upload staging record is simply copied over when the tax form is created. The actual payment may be created at different points in the tax form's lifecycle - depending on what's happening with the form.
· When the form posts, the obligation is already identified. Thus, the payment can be created for that obligation.
· When the form suspends, your implementation may want to create the financial transaction upfront and not wait for the suspense issue to be fixed. In this case, the payment can be created for a suspense obligation that is designated on the batch's tender source. When the form subsequently posts, the payment can be transferred to the correct obligation.
· When the form cancels, your implementation may want to create the payment anyway so that the financial transaction is still recorded in the system. In this case, the payment can be created for a suspense obligation that is designated on the batch's tender source. Manual follow-up is assumed in this case.
Refer to Payments With a Tax Form for more details on processing form payments.
Preparing To Upload Forms
The following sections describe the various considerations for preparing the system to upload forms.
A Generic Form Upload Staging Business Object
Designing The Mapping of Upload Data From The Different Sources
Designing Form Upload Staging Types
Designing Form Sources
A form source is defined for each external source that interfaces forms into the system.
The following points describe a recommended design process:
· Define the categories for your form sources by updating the C1_FORM_CHANNEL_FLG lookup flag. Examples of these broad categories are: Lockbox, Third Party Data Capture, In-House Data Capture, etc.
· Determine the information about your external sources that the system needs to capture.
· Configure you tender sources. A unique tender source is usually associated to each form source.
The base product provides a form source business object C1-FormSource that maps all of the fields on the form source maintenance object.
If this BO's structure is sufficient for your implementation, you can use the BO as is. Your implementation can extend the BO's processing logic by adding / overriding algorithms and BO options.
If your implementation needs to capture additional information, you can: inherit from the base BO, copy the base BO or create your own BO.
Refer to existing help on configuration tools for more details on configuring business objects.
A Generic Form Upload Staging Business Object
The base product provides the form upload staging business object C1-FormUploadStaging that was designed to be generic such that your implementation can use it out of the box.
This BO has a raw XML (CLOB) field that is used to hold the actual form details. Staging the form details as raw XML provides the following benefits:
· A uniform way of interfacing form details:
· For different types of forms
· From various external sources that may upload data for a particular form type using different record structures/layouts.
· External sources and Process X (i.e. the process that reads the input files and stores the form data into the form upload tables) do not need to know about the structure of the tax form and registration form business objects in the system.
· Form details can be uploaded into the system with minimal validation.
· As forms change in structure from year to year or as new form types are added, there is no need to create new form upload staging business objects. You implementation just needs to configure new form upload staging types (that reference the generic form upload staging BO), and define the mapping logic for the new forms.
The mapping logic configured on the form upload staging types takes care of transforming the data. This BO also has a transformed XML (CLOB) field that holds the transformed data. The value of this field is used when the tax / registration form is added.
Use C1-FormUploadStaging if the structure and lifecycle suits your implementation's form batch headers. As with any base BO, your implementation can extend the BO's processing logic by adding/overriding algorithms and BO options.
If your implementation needs to capture additional information, you can do any of the following:
· Inherit from the base BO - if the base BO lifecycle and processing logic works for you.
· Copy the base BO or create an entirely new BO - if your form upload staging records have a different lifecycle
Refer to existing help on configuration tools for more details on configuring business objects.
Designing The Mapping of Upload Data From The Different Sources
Given that the system expects the form data to come in as raw XML, your implementation needs to decide on the approach for mapping the raw XML data into the target form BO schemas. This decision usually entails looking at existing tools that are already available to your implementation.
Contents
XSL Transformation Is Not Required
Using XSL Transformation
The base product uses XSL transformation (XSLT) as an example for how to map the raw form upload data into the target form objects.
Since the input raw form upload data and the target form BO schemas are both in XML format, it makes sense to use XSLT. XSLT is a standard technique for transforming one XML document to another XML document. The key components in this approach are the XSLT Processor and the XSL style sheets.
XSL Transformation
The framework is already using an XSLT processor for transforming XMLs not only into other XMLs but also into HTMLs. A base business service calls an existing Java method for invoking that XSLT processor.
The base product provides a sample XSL file for mapping to the existing C1-SalesAndUseTaxForm business object - i.e. C1-SalesAndUseTaxForm.xsl.
Note. The sample Sales & Use XSL logic assumes a very specific 'raw' XML data form that was not based on any single real-life sales & use form. This sample XSL is just meant to demonstrate this particular mapping approach.
Both base product and CM XSL files need to be stored in specific locations in the file system that ETM Release Services designate.
· Base files are stored in @SPLEBASE@/splapp/resources/xsl/.
· CM files are stored in @SPLEBASE@/splapp/resources/xsl/cm/.
XSL Transformation Is Not Required
Although base logic uses XSLT for transforming form upload data, your implementation is not required to use this approach. The base logic that invokes XSLT is in a 'Map Form Upload Data' plug-in on the Form Upload Staging Type BO. You can override the base logic by inactivating the base logic and adding your own. This is done as part of configuring your form upload staging types, which is described in the next section.
Designing Form Upload Staging Types
The following sections describe the various considerations for configuring your form upload staging types.
Form Upload Staging Type (Admin) Business Object
Defining Form Upload Staging Type Data
Form Upload Staging Type (Admin) Business Object
The base product provides the C1-FormUploadStagingType business object. This object maps all of the fields on the maintenance object plus additional fields (in the CLOB) for the suspense To Do Type and To Do Role. Since the form upload staging type does not have a soft status, C1-FormUploadStagingType does not have a lifecycle.
Use the base BO if the structure suits your form upload staging types. Otherwise, you can either subclass the BO or create an entirely different BO. Refer to existing help on configuration tools for more details on configuring business objects.
When opting to use the C1-FormUploadStagingType BO and your chosen mapping technique is not XSLT, you need to do the following:
· Inactivate the base algorithm C1-FUST-XSLT (FUS Type - XSL Transformation) by adding a BO option to C1-FormUploadStagingType with:
· BO option type = Inactivate Algorithm
· BO option value = C1-FUST-XSLT.
· Plug in your CM algorithm on the Map Form Upload Data to Target Form plug-in spot on the C1-FormUploadStagingType BO.
Note. If your chosen approach is to not have mapping logic at all - i.e. Process X will populate the Transformed XML field in the staging record - you still need to plug in the CM algorithm, but the algorithm will do nothing but terminate.
C1-FormUploadStagingType also has BO options for automatic rendering of raw XML data on the UI.
· Display HTML Generator XSL Stylesheet = @SPLEBASE@/splapp/resources/xsl/c1FormUploadStagingUIMapForDisplay.xsl
· Schema Extractor XSL Stylesheet = @SPLEBASE@/splapp/resources/xsl/c1FormUploadStagingSchemaForUIMap.xsl
· Maintenance HTML Generator XSL Stylesheet = @SPLEBASE@/splapp/resources/xsl/c1FormUploadStagingUIMapForInput.xsl
Note. The generated maintenance HTML (third option) is just for editing raw XML data in existing form upload staging records. It is not used for adding form upload staging records online. A mass data entry solution is not included in this release.
If your implementation needs to render the raw XML data in a different way, you simply add option values for these three option types, using a higher sequence number. (For 'single' BO option types, the framework knows to get the highest sequence number.)
Defining Form Upload Staging Type Data
The following describes the steps in defining your form upload staging types.
· Determine the number of form upload staging types needed based on the number of your form types (that can be uploaded) and the sources that can interface those form types.
· Create a form upload staging type for each unique combination of form type and form source.
· Select the form upload staging type (admin) business object. See Form Upload Staging Type (Admin) Business Object for details configuring this BO.
· Specify the form upload staging type code (primary key)
· Put in a description of the form upload staging type
· Specify an Active status if you want to record to be effective immediately. Otherwise, specify an Inactive status and update the status later when the form upload staging type is ready.
· Specify the related transaction business object - the form upload staging BO. The base product provides a generic form upload staging BO for this purpose.
· Specify the form source.
· Specify the form type.
· If you are using XSLT to map raw XML form data to the target form BOs and you are using the base algorithm C1-FUST-XSLT, specify the XSL Transformation File Name. The file name must include the full path - e.g. com/splwg/cm/domain/forms/formUploadStaging/xsl/salesAndUseForm.xsl.
· If you selected the C1-FormUploadStagingType admin base BO, specify the suspense to do type and to do role.
Designing Form Batch Headers
The following points describe a recommended design process:
· Define the information that your form batch headers need to capture, e.g.:
· The valid form types that can be included in the batch - i.e. single vs. multiple
· Record counts
· Total amounts
· Examine the lifecycle of your form batch headers. Part of this effort is figuring out the points in the form batch header's lifecycle in which there is 'handshaking' with the form upload staging records' lifecycles.
· Design your form batch header processing algorithms.
· Identify issues that cause form batch processing to stop until a user can resolve the issues. Determine the appropriate notification action for such issues - e.g. To Dos
· Identify conditions that require a review of the form batch header. Determine the appropriate action for triggering such review - e.g. To Dos
· Identify conditions that cause form batch processing to complete. Determine the actions that need to take place at completion - e.g. final update of counters.
· Etc.
The base product provides the C1-StandardFormBatchHeader business object, which is designed to work for both batch uploads and mass data entry. It allows for multiple valid form types within the same batch. It also includes processing counters that capture the results of processing the included form upload staging records. This BO's lifecycle supports cancellation, validation, suspense, review and completion and is designed to work with the lifecycle of the form upload staging BO that is also provided in base - i.e. C1-FormUploadStaging.
Use C1-StandardFormBatchHeader if the structure and lifecycle suits your implementation's form batch headers. As with any base BO, your implementation can extend the BO's processing logic by adding/overriding algorithms and BO options.
If your implementation needs to capture additional information, you can do any of the following:
· Inherit from the base BO - if the base BO lifecycle and processing logic works for you.
· Copy the base BO or create an entirely new BO - if your form batch headers have a different lifecycle
Refer to existing help on configuration tools for more details on configuring business objects.
The topics in this section discuss the various options for setting up the processing of forms.
Contents
Setting Up The System To Enable Forms Processing
Setting Up Form Change Reasons
Setting Up Form Upload Staging Types
Setting Up The System To Enable Forms Processing
This table describes all objects that must be defined as part of the forms processing setup process. It lists the order in which objects should be defined. It also identifies the other objects that are associated with or referenced by each setup object, thus providing a useful map of the relationships between objects in the system.
|
Seq |
Object |
Description |
Prerequisite |
Associated With / Referenced By |
Admin Submenu |
|
1 |
Form Type |
Type of form |
Obligation Type |
Form Section, Form Line, Child Form Types, Valid Obligation Types, Tax Form, Registration Form, Form Upload Staging Type |
Form Type |
|
2 |
Form Section |
Section of a form type |
Form Type |
Form Type, Form Line |
Form Type |
|
3 |
Form Line |
A line in a section. Defines the type of information captured / displayed on the line |
Form Section |
Form Type, Form Section, Field, Lookup Field |
Form Type |
|
4 |
Form Change Reason |
Predefined reasons for changes to information on the form |
|
Form Type |
Form Change Reason |
|
5 |
Form Rule Group |
A logical grouping of form rules |
|
Form Type, Form Rule |
Form Rule Group |
|
6 |
Form Rule |
Defines how information on the form is processed |
Form Rule Group |
Form Rule Group, Registration Form Exception, Tax Form Exception |
Form Rule |
|
7 |
Form Source |
Predefined sources of forms |
Tender Source |
Tender Source, Form Upload Staging Type, Form Batch Header, Form Upload Staging, Tax Form, Registration Form |
Form Source |
|
8 |
Form Upload Staging Type |
Type of form upload staging record |
Form Source, Form Type |
Form Source, Form Type, Form Batch Header, Form Upload Staging |
Form Upload Staging Type |
Setting Up Form Types
Form Types contain the rules that control how forms are processed. To set up a Form Type, open Admin Menu, Form Type.
Contents
Form Type Query
Use the query portal to search for an existing form type. Once a form type is selected, you are brought to the maintenance portal to view and maintain the selected record.
Form Type Portal
This portal appears when a form type has been selected from the Form Type Query portal.
The topics in this section describe the base-package zones that appear on this portal.
Contents
Form Type Actions
This is a standard actions zone. The Edit, Delete and Duplicate actions are available.
If the form type is in a state that has valid next states, buttons to transition to each appropriate next state are displayed.
Form Type
The Form Type zone contains display-only information about selected form type.
Please see the zone's help text for information about this zone's fields.
Where Used
Follow this link to open the data dictionary where you can view the tables that reference CI_FORM_TYPE.
Child Form Types
This zone displays the list of tax form types to which the current form type is a parent.
Section List
This zone lists the sections of the form type in sequential order. The Edit, Duplicate, and Delete actions are available. You can click the Add link in the zone's title bar to add a new section. You can click a form section hyperlink to go to the maintenance portal for that form section.
Line List
This zone accepts a broadcast form section and lists the section's lines in sequential order. The Edit, Duplicate, and Delete actions are available. You can click the Add link in the zone's title bar to add a new line. You can click a line hyperlink to display the line details.
Form Type - Rules
To view the Form Type - Rules page, open Admin Menu, Form Type, select a form type, and then navigate to the Rules tab.
This page displays the form type's rule groups in prime key order. A row is displayed for every rules linked to the form type rule group. The list includes the form rule information with a hyperlink to the rule's maintenance portal. You can add or edit the form type rule group by clicking the link in the title bar.
Form Type - Log
To view the Form Type - Log page, open Admin Menu, Form Type, select a form type, and then navigate to the Log tab.
This page contains a standard log zone.
Setting Up Sections and Lines
Form Section - Main
This portal appears when a section has been selected from the Section List on the Form Type Query portal or from the Current Form Type's Sections dashboard zone.
The topics in this section describe the base-package zones that appear on this portal.
Contents
Form Section Actions
This is a standard actions zone. The Edit, Delete and Duplicate actions are available.
Form Section
This zone contains display-only information about selected form section.
Please see the zone's help text for information about this zone's fields.
Form Section Line List
This zone accepts a broadcast form section and lists the section's lines in sequential order. The Edit, Duplicate, and Delete actions are available. You can click the Add link in the zone's title bar to add a new line. You can click a line hyperlink to display the line details.
Setting Up Form Change Reasons
Typically the tax authority will want to track the reason/s behind a form change, especially if the changes were made by a user. The user will be required to select from a dropdown of form change reasons whenever making a change that requires a reason. To set up a Form Change Reason, open Admin Menu, Form Change Reason.
The topics in this section describe the base-package zones that appear on the Form Change Reason portal.
Contents
Form Change Reason List
The Form Change Reason List zone lists every form change reason. The following functions are available:
· Click the broadcast icon to open other zones that contain more information about the adjacent form change reason.
· The standard actions of Edit, Duplicate and Delete are available for each form change reason.
· Click the Add link in the zone's title bar to add a new form change reason.
Form Change Reason Actions
This is a standard actions zone. The Edit, Delete and Duplicate actions are available.
Form Change Reason
The Form Change Reason zone contains display-only information about the form change reason. This zone appears when a form change reason has been broadcast from the Form Change Reason List zone or if this portal is opened via a drill down from another page.
Please see the zone's help text for information about this zone's fields.
Form Types
The Form Types List zone displays a list of form types that currently use the broadcast form change reason. The following functions are available:
· Click the Add link in the zone's title bar to link a new form type to the broadcast form change reason.
· Use the Delete action to delete a link between the broadcast form change reason and a form type.
Setting Up Form Sources
A form source is created for every external source that interfaces tax / registration forms into the system.
To set up a form source, select Admin Menu, Form Source.
The topics in this section describe the base-package zones that appear on the Form Source portal.
Contents
Form Source List
The Form Source List zone lists every form source. The following functions are available.
· Click a broadcast button to open other zones that contain more information about the adjacent form source.
· Click the Edit button to maintain the form source.
· Click the Duplicate button to copy the form source.
· Click the Delete button to delete the form source.
· Click the Add link in the zone's title bar to add a new form source.
Form Source Actions
This is a standard actions zone. The Edit, Delete and Duplicate actions are available.
Form Source
The Form Source zone contains display-only information about a form source. This zone appears when a form source has been broadcast from the Forms Source List or if this portal is opened via a drill down from another page.
Please see the zone's help text for information about this zone's fields.
Where Used
Follow this link to open the data dictionary where you can view the tables that reference CI_FORM_SRCE.
Setting Up Tender Sources
A tender source is created for each form source that interfaces payments with tax forms.
These tender sources will be used on the form batch headers' tender controls.
The tender source also specifies the suspense obligation to which payments should be applied if the tax form's obligation is not yet determined at the time of payment creation - e.g. when the form gets suspended or canceled.
To set up a form source, select Admin Menu, Tender Source. Refer to existing help on setting up tender sources.
Setting Up Form Upload Staging Types
A form upload staging type is created for a unique combination of form type and form source.
Use the Form Upload Staging Type transaction to view and maintain form upload staging types. To set up a form upload staging type, select Admin Menu, Form Upload Staging Type.
Contents
Form Upload Staging Type Query
Form Upload Staging Type Portal
Form Upload Staging Type Query
Use the query portal to search for an existing form upload staging type. Once a form upload staging type is selected, you are brought to the maintenance portal to view and maintain the selected record.
You can click the Add link on this portal to add a form upload staging type.
Form Upload Staging Type Portal
This portal appears when a form upload staging type has been selected from the Form Upload Staging Type Query portal or if this portal is opened via drill down from another page.
The topics in this section describe the base-package zones that appear on this portal.
Contents
Form Upload Staging Type Actions
Form Upload Staging Type Actions
This is a standard actions zone. Edit, Delete and Duplicate actions are available.
Form Upload Staging Type
The Form Upload Staging Type zone contains display-only information about the form upload staging type.
Please see the zone's help text for information about this zone's fields.
Where Used
Follow this link to open the data dictionary where you can view the tables that reference CI_FORM_UPLD_STG_TYPE.