Configuring Form Group Instances

Background

Customers often have a need to generate forms for households, such that when generating bundles of forms, certain family members’ information prefills one form, and not the other. Similarly, customers often have a need to  generate multiple copies of the same form in a single bundle, and prefill different people's data onto the same “role” on each copy.

Form group instances make it easier to logically separate forms according to transactions (e.g. open 3 accounts), whereas form instances are really meant to add duplicate forms into a bundle (e.g. adding extra beneficiaries).

In order to add from group instances in the same generated bundle, there is a method called AddFormIDsGroup.

Field Names with Form Group Instances

Using the example scenario above:

• For the first group of forms, fields are built normally without the field instance extension. If, within the first group, FormIDs are duplicated (e.g. form group 1 has forms "1,2,2" where form ID 2 is repeated) then the field instance will be "-1".  
  • “1own.FName” for the first instance of FormID 1 in this first group of forms.
  • “1own.FName-1” for the second instance of FormID 2 in this first group of forms.
• For the second group of forms, fields will be built with a field instance extension. The extension number will start at 1000 (e.g. "1own.FName-1000") and grow as duplicate forms are included in the same package (e.g. the second copy of the same form could have a field named "1own.FName-1001"). 
  • “1own.FName-1000” for the first instance
  • “1own.FName-1001” for the second instance
• Subsequent groups of forms will increase the instance number by 1000. For example, the third form group will have a field instance number starting with "2000" and increments by 1 for each copy of the same form within that group (e.g. if the group contains FormIDs "1,1,1,1" then the instance numbers would be "2000", "2001", "2002" and "2003" 
  • “1own.FName-2000”
  • “1own.FName-2001”
  • “1own.FName-2002”
  • “1own.FName-2003”

These field name extensions result in unique field names on every form in a bundle, so that different people can be prefilled in desired sections of a form without their information "flowing" to the same section on other copies or forms.

Using Form Groups Instances in SOAP & REST

How To Specify FormIDs in Form Group Instances

When building Form Group instances with a JSON for REST or with an XML for SOAP web services, a dash ( - ) is used to separate form group instances.

Let's say you want to create a package of 3 separate groups of forms (e.g. a household with 3 accounts) using FormIDs 6996, 2 and 12. You want the paperwork for accounts A, B and C to be specified as follows:

• account A gets form IDs 6996, 2, and a second copy of Form ID 2
• account B gets Form IDs 6996 and 12
• and account C gets Form IDs 2 and 12

Thus, you would set the QuikFormID property as follows:

"QuikFormID": "6996,2,2-6996,12-2,12"

See below for sample code:

{
  "HostFormOnQuik": true,
  "FormFields": [
    {
      "FieldName": "1own.FName",
      "FieldValue": "Stephen"
    },
    {
      "FieldName": "1own.FName-1",
      "FieldValue": "Draymond"
    },
    {
      "FieldName": "1own.FName-1000",
      "FieldValue": "Klay"
    },
    {
      "FieldName": "1own.FName-2000",
      "FieldValue": "Andre"
    }
  ],
  "QuikFormID": "6996,2,2-6996,12-2,12"
}

The above example will generate the following form group instances: 

• account A gets form IDs 6996, 2, and a second copy of Form ID 2
• account B gets Form IDs 6996 and 12
• and account C gets Form IDs 2 and 12

Quik! recommends that customers copy and paste the above JSON into the HTMLSettings parameter of the Execute endpoint on Swagger, then open the returned HTML link to see how the first name fields prefill on the forms to aid with understanding how to prefill form group instances. Note: Ensure your account is subscribed to the American Funds form library to test with these forms.

DEPRECATED - Using Form Groups Instances with the Quik! Forms Engine DLL

Example: There is a need to bundle the forms for 3 accounts together but with differing forms. Let's say account A gets form IDs 1,2,2, account B gets Form IDs 1,3 and account C gets Form IDs 2,3. 

The example below will generate 3 group of forms.

QuikFormsEngine qfe = new QuikFormsEngine();

qfe.QuikCustID = "1000123";
qfe.QuikUsername = "myUserName";
qfe.QuikPassword = "myPassword";

qfe.AddFormIDsGroup("1,2,2");
qfe.AddFormIDsGroup("1,3");
qfe.AddFormIDsGroup("2,3");
qfe.Execute();