Generating and installing LOB-specific APIs

The following diagram provides a high-level overview for how a line of business is typically developed using Advanced Product Designer.

Life cycle of product in Advanced Product Designer

The product and its lines of business start as metadata that is captured in either a mind map or a template.
The insurer creates a visualized product by importing the LOB metadata into PolicyCenter.
1. During the import, PolicyCenter generates a set of "in memory" APIs that reflect the structure of the LOB.
While in Advanced Product Designer, the insurer typically edits the product.
1. This is typically an iterative process where the insurer refines the metadata as needed.
2. Every time the product is modified, the "in memory" APIs are regenerated.
Once the refining is complete, the insurer creates a finalized product by installing the product. The finalized products consists of:
1. The necessary artifacts for the product, including database tables and PCFs.
2. A set of "active" APIs that are now part of the system APIs.

Note: When importing, editing, or installing a line of business through Advanced Product Designer, there is no separate step to generate LOB-specific APIs. The APIs are generated automatically whenever the product is imported, edited, or installed.

For more information on Advanced Product Designer, refer to the Advanced Product Designer Guide.

Related developer tasks

When working with LOB-specific APIs, developers can do the following:

Generate LOB-specific APIs as part of an entire product (through Advanced Product Designer)
Generate a template from an existing finalized product
Install LOB-specific APIs without modifying other product-specific artifacts

Generating LOB-specific APIs through APD

When you import, edit, or install a product through Advanced Product Designer, LOB-specific APIs are automatically generated. For more information on how to use Advanced Product Designer, refer to the Advanced Product Designer Guide.

Note that the generation of APIs through Advanced Product Designer can be either seamless or bootstrapped.

If the line of business supports seamless generation, then the LOB-specific APIs are generated automatically from the visualized product. No manual modifications are required.
If the line of business supports only bootstrapped generation, then some manual modification of the generated APIs is required.

Generate LOB-specific APIs

About this task

You can generate an LOB-specific API from an APD template. This process applies to both creating new LOB-specific APIs as well as updating existing APIs.

Note:

PolicyCenter upgrades include new features for use with the Cloud APIs. In order to apply these new features to your LOB-specific APIs, you must update each of those APIs after upgrading PolicyCenter itself.

To execute this task, you must have an APD template for the LOB. If necessary, you can generate an APD template from the existing visualized product and import the template. For more information, see Generate a template using the reverse template generator

Procedure

In PolicyCenter, set Options > Preferences > Product Design Mode to Developer, and then click Update.
To add the template, click Administration > Product Management > Import From Template, browse and select your template, and then click Update.
To generate the API, from the Details pane click Edit Product > Generate Product Code > System APIs > System APIs - Code
Review the model, and if acceptable, click Complete Generation.
Click Return to Product Definition, and then click Save.
Restart PolicyCenter.

Results

To verify the result, browse to the APD Managed pane on the Product Management page. The LOB product will be displayed, and the Last Updated column will have a value, indicating that the product has been installed. For details on viewing the API in Swagger, see View an API definition using Swagger UI.

Generating templates from a finalized product

Products can be created in PolicyCenter using approaches other than Advanced Product Designer. These approaches create a product with several LOB-specific artifacts (such as LOB-specific database tables or PCFs). But, they do not create any LOB-specific APIs. If you want to expose these lines of business to the system APIs, you need to generate LOB-specific APIs.

You can achieve this by doing the following:

Create a template for the product using the reverse template generator.
Import the product into Advanced Product Designer.
From the imported product, install only the LOB-specific APIs.

The reverse template generator is a script that creates an XML template from an installed product. Because the generator generates XML based on the installed product, the resulting template typically has more information in it than what exists in a mind map or in a product that is only visualized.

Advanced Product Designer is not required to run the reverse template generator. Therefore, it is possible to run the reverse template generator in older versions of PolicyCenter to generate a template. However, Advanced Product Designer is required to import the template and install the corresponding APIs.

Generate a template using the reverse template generator

Procedure

In PolicyCenter, select Administration > Product Management > Externally Managed. This pane contains a list of products that have been installed by means other than APD.
In the Installed Products pane, select the product for which you wish to generate an APD template.
In the Details pane, click Extract APD Representation. PolicyCenter generates the APD template and stores it in the <USER_HOME>/Downloads directory.

Results

Once the product is imported as a visualized product and any inconsistencies have been corrected, you can install just the APIs. For details, see Generate LOB-specific APIs.

Installing LOB-specific APIs without installing other artifacts

In some situations, you may have an installed product that has no LOB-specific APIs. For example, this can occur when a product has been created outside of Advanced Product Designer, such as:

A base configuration product
A product installed from a Standards Based Template (SBT)
A product created in Product Designer

You can create a template from the installed product using the reverse template generator, and then import the template into Advanced Product Designer. Once the product has been imported, you can install only the APIs, without modifying any of the other existing product-specific artifacts.

API codegen configuration

APD-generated products adhere to certain naming conventions and behaviors that simplify API generation. However, when generating LOB-specific APIs from an APD template that has been exported from a non-APD product, it is possible for naming conflicts to arise during code generation that cause build failure, since the existing product may have irregular entity names or other functionality not yet supported by APD.

In such a circumstance, you can apply an API codegen configuration file for the non-APD product. The codegen configuration can be used to map any mismatches of type or field names between the non-APD product with those used in the associated APD template. Additionally, it is possible to override certain behaviors, such as constraints, that exist in the non-APD product but are not reflected in its APD template.

Note:

API codegen configuration can become quite complex, depending on the LOB. For assistance, contact Guidewire Support.

Applying API codegen overrides

In order to apply API codegen overrides to a legacy product, the following criteria must be met:

The directory config > Integration > apis > installedlobs must be present in your system. If it is not present, then you must create it.
That directory must contain the API codegen configuration file, in YAML format.
The file name must be in the form <xx>_codegen_config.yaml, in which <xx> is the product suffix.

After meeting the above conditions, you must regenerate the product API.

API codegen configuration syntax

Resolving mismatched type/field names

Sometimes, there can be a mismatch between APD-generated types and the fields in the corresponding product, particularly when the template has been exported from a non-APD product. The API codegen configuration file can be used to specify mapping information that resolve these mismatches.

The API codegen configuration file must have a top-level types property followed by one or more APD-generated types. Each APD-generated type can specify a nameOverride property, which identifies the relevant type name in the product. Product values are case-insensitive, but APD-generated values are case-sensitive and the case must match. The syntax for this is as follows:

types:
  <APDGeneratedName>:
    nameOverride: <TypeNameInProduct>

For example, suppose you have an APD-generated type PALine, which corresponds to the product's PersonalAutoLine. The following code maps these values.

types:
  PALine:
    nameOverride: PersonalAutoLine

For each type, you can also provide type-to-field mapping by specifying a fields property. The fields property includes an array of one or more APD-generated types to override. Each type name contains a nameOverride property that identifies the field name as used in the product. As is the case with the parent type value, APD-generated field-level values must match the case of the APD-generated type values. The syntax for this is as follows:

types:
  <APDGeneratedName>:
    nameOverride: <TypeNameInProduct>
    fields:
      <APDGeneratedName>:
        nameOverride: <FieldNameInProduct>

For example, suppose you have an APD-generated type PALine, which corresponds to the product's PersonalAutoLine. There is also an APD-generated Year type which corresponds to the product's ModelYear field. The following code identifies how to map these values.

types:
  PALine:
    nameOverride: PersonalAutoLine
    fields:
      Year:
        nameOverride: ModelYear

Modifying field constraints

In addition to applying naming overrides, it is also possible to apply or relax type or field constraints enforced in the APD template that differ from the behavior expected in the originating product.

The following optional properties can be used to override specific aspects of a type or field:

autonumber: Accepts resource name of the schema and mapping to be used in lieu of the default sorting
canDelete: Enable or disable DELETE method (Boolean)
canPatch: Enable or disable PATCH method (Boolean)
canPost: Enable or disable POST method (Boolean)
canSplit: Enable or disable the split custom action (Boolean)
createOnly: Enable or disable modifiers (Boolean)
identifier: Override default identifying property
ignored: Hide or expose the field (Boolean)
nullable:: Allow a null value (Boolean)
oneToOne: Enforce a one-to-one relationship by removing the ability to add or remove values
requiredForCreate: Override the APD-derived requiredForCreate value (Boolean)
resourceName: Override default schema and resource name. Apply this value when the resource name differs from the nameOverride name.
toCreateAndAdd: Override default createAndAdd method
toRemove: Override default remove method
wizardStepIds: Add or drop wizard step identifiers (Boolean)

The following code block is an example of an API codegen configuration for a Personal Auto line that includes optional properties:

types:
  PADriver:
    nameOverride: VehicleDriver
    fields:
      PolicyDriver:
        createOnly: true
  PALine:
    nameOverride: PersonalAutoLine
  PAPolicyDriverMVR:
    nameOverride: PolicyDriverMVR
    # PolicyDriverMVRs are managed implicitly via requests to retrieve an MVR on individual drivers and are read-only
    canDelete: false
    canPatch: false
    canPost: false
  PAVehicle:
    nameOverride: PersonalVehicle
    fields:
      GarageLocation:
        requiredForCreate: false
      Year:
        nameOverride: ModelYear
    autonumber: VehicleNumber
    toCreateAndAdd: createAndAddVehicle
    toRemove: removeVehicle
wizardStepIds: false