Implementing the Cloud API /recover-new-jobs endpoint

This topic only applies to PolicyCenter.

To implement the /recover-new-jobs endpoint, you must do the following:

  1. Define search criteria properties in the RecoverNewJobsWrapperExt class
  2. Define query logic in the RecoverNewJobsExtResource class
  3. Extend the RecoverNewJobsRequestAttributes schema

Sample implementation examples

The following topics contains sample code for a complete implementation for the reauthorize anonymous user flow. In this sample:

  • The caller application submits one or more of the following values:
    • Account number
    • Job number
    • First name (of the primary insured)
    • Last name (of the primary insured)
    • Postal code (of the primary insured)
  • The endpoint returns any jobs that:
    • Meet the implicit criteria for new job recovery (such as the job is an unbound submission)
    • Has an exact match with all values submitted

Note that, as this is a sample implementation, none of the properties are required. This includes First Name and Last Name, each of which can be specified without specifying the other.

Warning: This implementation has not gone through any risk assessment. Guidewire does not recommend using this example in a production environment, as it may expose secure data and it may not have acceptable performance. Guidewire recommends that insurers implement their own search logic and that they ensure their implementation is secure and has sufficient performance.

Define search criteria properties

First, you must define the properties that store the search criteria.

The base configuration includes a class where search criteria properties are to be defined. It is called RecoverNewJobsWrapperExt, and it is declared in the gw.rest.ext.pc.job.v1.security package. The base configuration version is an empty class that looks similar to this:
package gw.rest.ext.pc.job.v1.security

uses gw.rest.core.pc.job.v1.security.RecoverNewJobsWrapper

@Export
class RecoverNewJobsWrapperExt extends RecoverNewJobsWrapper {
}

To enable new job recovery, define the required search criteria in this class.

Sample RecoverNewJobsWrapperExt class

The sample implementation supports new job recovery search on the following values:

  • Account number
  • Job number
  • First name (of the primary insured)
  • Last name (of the primary insured)
  • Postal code (of the primary insured)

This is what the class looks like after configuration.

package gw.rest.ext.pc.job.v1.security

uses gw.rest.core.pc.job.v1.security.RecoverNewJobsWrapper

/*
 This class has recovery extension properties used for the Recover New Jobs endpoint. These recovery properties are examples only and have not gone through Risk Acceptance.
 */

@Export
class RecoverNewJobsWrapperExt extends RecoverNewJobsWrapper {
  var _accountNumber : String as AccountNumber
  var _firstName : String as FirstName
  var _jobNumber : String as JobNumber
  var _lastName : String as LastName
  var _postalCode : String as PostalCode
}

Define the query logic

Next, you must define the query that executes the search.

The base configuration includes a class where the query is to be defined. It is called RecoverNewJobsExtResource, and it is declared in the gw.rest.ext.pc.job.v1.security package.

The class has a single getter named RecoverNewJobsWrapper. In the base configuration, it simply returns a new RecoverNewJobsWrapperExt instance. The base configuration version looks similar to this:

package gw.rest.ext.pc.job.v1.security

uses gw.rest.core.pc.job.v1.security.RecoverNewJobsCoreResource
uses gw.rest.core.pc.job.v1.security.RecoverNewJobsWrapper

@Export
class RecoverNewJobsExtResource extends RecoverNewJobsCoreResource {

  protected override property get RecoverNewJobsWrapper() : RecoverNewJobsWrapper {
    return new RecoverNewJobsWrapperExt()
  }

}

To enable new job recovery, add a method override to the class that overrides the populateRecoverNewJobsQuery method. The new method must return a PolicyPeriod query that specifies whatever query restrictions are required based on the search criteria properties. The following is a high-level syntax statement for the method.

  protected override function populateRecoverNewJobsQuery(recoverNewJobsWrapper : 
RecoverNewJobsWrapper) : IQueryBeanResult<PolicyPeriod> {

    // code that defines query with appropriate search criteria

    return <some_value_of_type_IQueryBeanResult<PolicyPeriod>_>
  }

For more information on writing Gosu queries, see the Gosu Reference Guide. You can also refer to the makeQueryBuilderForNormalSearches method in the PolicyPeriodSearchCriteria.gs for more example properties.

Sample RecoverNewJobsExtResource class

The sample implementation supports new job recovery search on the following values:

  • Account number
  • Job number
  • First name (of the primary insured)
  • Last name (of the primary insured)
  • Postal code (of the primary insured)

Thus, the RecoverNewJobsWrapper getter does the following for each search criteria property:

  • Checks to see if a value was provided for the property
  • Adds the corresponding query logic to the query, if a value was provided

This is what the class looks like after configuration. Comments in the code appear in bold.

package gw.rest.ext.pc.job.v1.security

uses gw.account.AccountQueryBuilder
uses gw.api.database.IQueryBeanResult
uses gw.contact.ContactQueryBuilder
uses gw.contact.PolicyContactRoleQueryBuilder
uses gw.job.JobQueryBuilder
uses gw.policy.PolicyPeriodQueryBuilder
uses gw.policy.PolicyQueryBuilder
uses gw.rest.core.pc.job.v1.security.RecoverNewJobsCoreResource
uses gw.rest.core.pc.job.v1.security.RecoverNewJobsWrapper

@Export
class RecoverNewJobsExtResource extends RecoverNewJobsCoreResource {

  protected override property get RecoverNewJobsWrapper() : RecoverNewJobsWrapper {
    return new RecoverNewJobsWrapperExt()
  }

// Start of the populateRecoverNewJobsQuery override
  protected override function populateRecoverNewJobsQuery(recoverNewJobsWrapper : RecoverNewJobsWrapper) : IQueryBeanResult<PolicyPeriod> {

// Create a new PolicyPeriod query.
    var queryBuilder = new PolicyPeriodQueryBuilder()

// If the job number was specified, add it to the criteria
    if ((recoverNewJobsWrapper as RecoverNewJobsWrapperExt).JobNumber != null) {
      var jobQueryBuilder = new JobQueryBuilder()
          .withJobNumber((recoverNewJobsWrapper as RecoverNewJobsWrapperExt).JobNumber)
      queryBuilder.withJob(jobQueryBuilder)
      }

// If the account number was specified, add it to the criteria
    if ((recoverNewJobsWrapper as RecoverNewJobsWrapperExt).AccountNumber != null) {
      var policyQueryBuilder = new PolicyQueryBuilder()
          .withAccount(new AccountQueryBuilder().withAccountNumber((recoverNewJobsWrapper as RecoverNewJobsWrapperExt).AccountNumber))
      queryBuilder.withPolicy(policyQueryBuilder)
    }

    if ((recoverNewJobsWrapper as RecoverNewJobsWrapperExt).AccountNumber.NotBlank) {
      queryBuilder.withUseAnyArrayForPolicyContactRoleSearch(false)
    }

// Add First Name, Last Name, and Postal Code criteria
    var contactQueryBuilder = new ContactQueryBuilder()
        .withFirstName((recoverNewJobsWrapper as RecoverNewJobsWrapperExt).FirstName)
        .withLastName((recoverNewJobsWrapper as RecoverNewJobsWrapperExt).LastName)
        .withPostalCodeDenorm((recoverNewJobsWrapper as RecoverNewJobsWrapperExt).PostalCode)

// Limit the query to match First Name, Last Name, and Postal Code only
for contacts whose role on the policy the primary insured
    var policyContactRoleQueryBuilder = new PolicyContactRoleQueryBuilder()
        .withSubtype(TC_POLICYPRINAMEDINSURED)
        .withContactDenorm(contactQueryBuilder)
    queryBuilder.withPolicyContactRole(policyContactRoleQueryBuilder)

// Return the query
    return queryBuilder.build().select() as IQueryBeanResult<PolicyPeriod>
  }
}

Extend the RecoverNewJobsRequestAttributes schema

Finally, you must extend the RecoverNewJobsRequestAttributes schema.

The schema file

To extend the schema itself, add your extensions to the policyperiod_ext-1.0.schema.json file.

Guidewire recommends adding an _Ext suffix to all property names you add to a base configuration schema. This is to prevent any conflicts that could arise in future releases with search criteria properties added by Guidewire.

Sample policyperiod_ext-1.0.schema.json file

For the sample implementation, this is what the file looks like after configuration.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "x-gw-combine": [
    "gw.content.pc.policyperiod.v1.policyperiod_content-1.0",
    "ext.common.v1.common_ext-1.0"
  ],
  "definitions": {
    "RecoverNewJobsRequestAttributes": {
      "title": "Recover new jobs request attributes",
      "description": "Recovery properties used to recover new non-complete jobs for an unauthenticated user",
      "type": "object",
      "x-gw-sinceVersion": "1.6.0",
      "properties": {
        "accountNumber_Ext": {
          "title": "Account number",
          "description": "The `accountNumber` of the account",
          "type": "string"
        },
        "firstName_Ext": {
          "title": "First name",
          "description": "The `firstName` of the account's `accountHolder`",
          "type": "string"
        },
        "jobNumber_Ext": {
          "title": "Job number",
          "description": "The number of the job",
          "type": "string"
        },
        "lastName_Ext": {
          "title": "Last name",
          "description": "The `lastName` of the account's `accountHolder`",
          "type": "string"
        },
        "postalCode_Ext": {
          "title": "Postal code",
          "description": "The `postalCode` of the `primaryAddress` on the account's `accountHolder`. Only applicable in certain countries.",
          "type": "string",
          "x-gw-extensions": {
            "countryRestricted": true
          }
        }
      }
    }
  }
}

The mapper file

To extend the mappings, add your extensions to the policyperiod_ext-1.0.mapping.json file.

This file declares search attribute properties, and these properties never store data from PolicyCenter. Therefore, there is no technical requirement to have mappers. However, Cloud API raises a warning if properties are added to a schema without mappers. So, Guidewire recommends adding these mappers solely to suppress this warning.

Sample policyperiod_ext-1.0.mapping.json file

For the sample implementation, this is what the file looks like after configuration.

{
  "schemaName": "ext.policyperiod.v1.policyperiod_ext-1.0",
  "combine": [
    "gw.content.pc.policyperiod.v1.policyperiod_content-1.0",
    "ext.common.v1.common_ext-1.0"
  ],
  "mappers": {
    // Added to suppress "no mappers" warnings
    "RecoverNewJobsRequestAttributes": {
      "schemaDefinition": "RecoverNewJobsRequestAttributes",
      "root": "java.lang.Object",
      "properties": {
        "accountNumber_Ext": {
          "path": "null as String"
        },
        "firstName_Ext": {
          "path": "null as String"
        },
        "jobNumber_Ext": {
          "path": "null as String"
        },
        "lastName_Ext": {
          "path": "null as String"
        },
        "postalCode_Ext": {
          "path": "null as String"
        }
      }
    }
  }
}

The updater file

To extend the updaters, add your extensions to the policyperiod_ext-1.0.updater.json file.

Sample policyperiod_ext-1.0.updater.json file

For the sample implementation, this is what the file looks like after configuration. Note that, for each property, the root is the RecoverNewJobsWrapperExt class.

{
  "schemaName": "ext.policyperiod.v1.policyperiod_ext-1.0",
  "combine": [
    "gw.content.pc.policyperiod.v1.policyperiod_content-1.0",
    "ext.common.v1.common_ext-1.0"
  ],
  "updaters": {
    "RecoverNewJobsRequestAttributes": {
      "schemaDefinition": "RecoverNewJobsRequestAttributes",
      "root": "gw.rest.ext.pc.job.v1.security.RecoverNewJobsWrapperExt",
      "properties": {
        "accountNumber_Ext": {
          "path": "RecoverNewJobsWrapperExt.AccountNumber"
        },
        "firstName_Ext": {
          "path": "RecoverNewJobsWrapperExt.FirstName"
        },
        "jobNumber_Ext": {
          "path": "RecoverNewJobsWrapperExt.JobNumber"
        },
        "lastName_Ext": {
          "path": "RecoverNewJobsWrapperExt.LastName"
        },
        "postalCode_Ext": {
          "path": "RecoverNewJobsWrapperExt.PostalCode"
        }
      }
    }
  }
}