Form patterns information

Cloud API uses the /admin/v1/form-patterns endpoint to work with all aspects of a form pattern. With this endpoint and its child endpoints you can retrieve and update form pattern basic information, products, transaction types, jurisdiction availability and replacements, and policy change behavior.

Retrieving form patterns

Use the following endpoints to retrieve form patterns:

GET /admin/v1/form-patterns
GET /admin/v1/form-patterns/{policyFormPatternId}

Note:

The information retrieved by these endpoints includes everything located on all tabs of the Form Pattern screen in the user interface except jurisdiction availability. See "Form patterns lookups" below for information on retrieving jurisdiction availability. See Application Guide for user interface information.

The following retrieves all available form patterns:

Command

GET /admin/v1/form-patterns

Response

{
     "data": [
        {
            "attributes": {
                "code": "DecSheet",
                "customFormInference": true,
                "edition": "0100",
                "endorsementNumbered": false,
                "formNumber": "PA 00DS",
                "id": "pc:101",
                "inferenceTime": {
                    "code": "bind",
                    "name": "Bind Time"
                },
                "jobTypes": [
                    {
                        "code": "PolicyChange",
                        "name": "Policy Change"
                    },
                    {
                        "code": "Renewal",
                        "name": "Renewal"
                    },
                    {
                        "code": "Rewrite",
                        "name": "Rewrite"
                    },
                    {
                        "code": "Submission",
                        "name": "Submission"
                    }
                ],
                "name": "Dec Sheet",
                "policyLine": {
                    "displayName": "Personal Auto Line",
                    "id": "PersonalAutoLine"
                },
                "priority": 0,
                "products": [
                    {
                        "displayName": "Personal Auto",
                        "id": "PersonalAuto"
                    }
                ],
                "reissueOnChange": true,
                "removalEndorsement": false
            },
        …
        },
        {
            "attributes": {
                "code": "FormCPP01",
                "edition": "00 00",
                "endorsementNumbered": true,
                "formNumber": "CPP 01",
                "genericFormInference": {
                    "code": "GenericAlwaysAddedForm",
                    "displayName": "No additional criteria"
                },
                "id": "pc:102",
                "inferenceTime": {
                    "code": "quote",
                    "name": "Quote Time"
                },
                "jobTypes": [
                    {
                        "code": "PolicyChange",
                        "name": "Policy Change"
                    },
                    {
                        "code": "Renewal",
                        "name": "Renewal"
                    },
                    {
                        "code": "Rewrite",
                        "name": "Rewrite"
                    },
                    {
                        "code": "Submission",
                        "name": "Submission"
                    }
                ],
                "name": "Commercial Package Policy Definition",
                "priority": 1,
                "products": [],
                "reissueOnChange": false,
                "removalEndorsement": false
            },
            …

Creating form patterns

You can create a new form pattern with the following endpoint:

POST /admin/v1/form-patterns

The following properties are required in the request:

Parameter	Type	Description
`code`	string	The form pattern code. This value must be globally unique. PolicyCenter uses this value to link the form to a form pattern. This value cannot contain spaces.
`edition`	string	The form edition. PolicyCenter uses this value, in conjunction with the `formNumber` field, to indicate that two or more patterns are different editions of the same form. Similar to `formNumber`, this is an arbitrary string, but typically it is the edition used by the issuance system. Note: If you add a new edition, you must also update the availability dates of the old and new patterns. Merely setting the edition is not sufficient.
`endorsementNumbered`	Boolean	True if this form must have an endorsement number assigned to it at inference time. The endorsement number indicates the order in which the form is added to the policy. The insurer decides whether the form requires an endorsement number. Some insurers require an endorsement number for forms added after issuing the policy. For example, a form added in a policy change could require an endorsement number.
`formNumber`	string	The form number. This is an arbitrary string, but it typically is the form number used by the issuance system. This field is the form label that shows in the PolicyCenter user interface.
`genericFormInference`	string	The string must be the name of a class that implements the `gw.forms.GenericFormInference` interface. Depending on the value, other fields could be required. See Form inference below for more details. Note: This property is not required if you’re using a custom inference class. See Form inference below for details.
`inferenceTime`	`FormInferenceTime` Typekey	Forms cannot be assigned directly to policies. They are applied automatically at a specified stage of the policy creation process, such as when the policy is quoted or bound. This field specifies the stage at which the form is applied to the policy.
`jobTypes`	Typekey from the `FormPatternJobs` typefilter on the `Jobs` typelist	An array of job types that use this form pattern.
`name`	string	A human-readable description of the form pattern.
`products`	array of Product code ids	The products to which this form pattern applies.

The following example creates a new form pattern for the PersonalAuto product that gets applied to a policy when a submission or policy change is quoted:

Command

POST /admin/v1/form-patterns

Request

{
  "data": {
    "attributes": {
      "code": "Code001",
      "edition": "0001",
      "endorsementNumbered": true,
      "formNumber": "Test001",
      "genericFormInference": {
        "code": "GenericRemovalAndReplacementEndorsementForm"
      },
      "inferenceTime": {
        "code": "quote"
      },
      "jobTypes": [
        {
          "code": "PolicyChange"
        },
        {
          "code": "Submission"
        }
      ],
      "name": "Test Form 001",
      "products": [
        {
          "id": "PersonalAuto"
        }
      ]
    }
  }
}

Updating form patterns

You can use the following endpoints to update and delete form patterns:

PATCH /admin/v1/form-patterns/{policyFormPatternId}
DELETE /admin/v1/form-patterns/{policyFormPatternId}

The following example changes the job type to Renewal on form pattern pc:910:

Command

PATCH /admin/v1/form-patterns/pc:910

Request

{
  "data": {
    "attributes": {
      "jobTypes": [
        {
          "code": "Renewal"
        }
      ]
    }
  }
}

Note that in this example the Renewal job type is not added to existing job types for this form; all existing job types on form pattern pc:910 are replaced with the value specified in the PATCH request. This is due to the fact that PATCH on an array in Cloud API is destructive, not additive. When you PATCH an array, the new content replaces the previous content. If you want to add to an array, the PATCH request must contain all current members of the array as well as the member being added.

To delete the form pattern in the preceding example, use the following command:

DELETE /admin/v1/form-patterns/pc:910

Note: DELETE works only in development mode. The command will throw an exception if you try to delete a form pattern when the server is in production mode.

Form inference

When you create a new form pattern, you can use custom form inference or generic form inference. This section describes using generic form inference. To use custom form inference, see "Adding a custom inference class for form patterns" in the Application Guide and "Configuring custom form inference" in the Application Guide for more information.

If you use generic form inference, you must include a value for the genericFormInference property. The code is a string that contains the name of a class that implements the gw.forms.GenericFormInference interface.

Depending on the value of the genericFormInference property, there could be properties required for form pattern creation in addition to those specified in the table above. The following table lists the additional required properties for each base configuration generic form inference condition.

`genericFormInference` value	Additional required properties
GenericAdditionalInsuredForm	`policyLine`
GenericAdditionalInterestForm	`policyLine`
GenericAlwaysAddedEveryJobForm	none
GenericAlwaysAddedForm	none
GenericClauseNonExistenceForm	`clause` `policyLine`
GenericClauseSelectionForm	`clause` `policyLine`
GenericCovTermSelectionForm	`clause` `policyLine` `selectedCovTerm`
GenericCoverableTypeKeyForm	`coverableType` `coverableTypeKey` `coverableTypeKeyExistsOnAll` `coverableTypeList` `policyLine`
GenericRemovalAndReplacementEndorsementForm	none
GenericRemovalEndorsementForm	none

You might have a form that requires inference logic beyond what you can specify with the base configuration classes. In this case, you can either configure a new generic forms inference class or specify a custom form inference class. The custom form inference class overrides the base configuration settings.