Guidewire PolicyCenter™

Integration Guide
Release 9.0.6
©2018 Guidewire Software, Inc.
For information about Guidewire trademarks, visit http://guidewire.com/legal-notices.
Guidewire Proprietary & Confidential — DO NOT DISTRIBUTE

Product Name: Guidewire PolicyCenter

Product Release: 9.0.6
Document Name: Integration Guide
Document Revision: 27-November-2018
 Guidewire PolicyCenter 9.0.6 Integration Guide

Contents

About PolicyCenter documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Conventions in this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Part 1
Planning integration projects
1 Integration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Overview of integration methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
PolicyCenter integration elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Preparing for integration development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Integration documentation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
API reference documentation for integration programmers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Data Dictionary documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Regenerating integration libraries and WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Regenerating the Java API libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
WS-I web service regeneration of WSDL for local GUnit tests . . . . . . . . . . . . . . . . . . . . . . . . . .35
What are required files for integration programmers?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Public IDs and integration code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Creating your own public IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Guidewire internal methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Part 2
Web Services
2 Web services introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
What are web services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Publish or consume web services from Gosu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
What happens during a web service call? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Reference of all base configuration web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

3 Publishing web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Overview of web service publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Data transfer objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Web service publishing quick reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Web service publishing annotation reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Publishing and configuring a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Declaring the namespace for a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Specifying minimum run level for a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Specifying required permissions for a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Overriding a web service method name or visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Web service invocation context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Web service class lifecycle and request local scoped variables . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Generating WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Getting WSDL from a running server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Calling a PolicyCenter web service from Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Calling web services using Java and wsimport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

3
Guidewire PolicyCenter 9.0.6 Integration Guide

Adding HTTP basic authentication in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Adding SOAP header authentication in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Testing web services with local WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Generating WSDL for local web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Using your class to test local web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Writing unit tests for your web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Web services authentication plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Web services authentication plugin implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Writing an implementation of the web services authentication plugin . . . . . . . . . . . . . . . . . . . . . .62
Login authentication confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Request or response XML structural transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Transforming a generated schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Converting a Gosu DTO to and from XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Using predefined XSD and WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Add an invocation handler for preexisting WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Example of an invocation handler for preexisting WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Invocation handler responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Reference additional schemas in your published WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Validate requests using additional schemas as parse options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Create an XML schema JAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Setting response serialization options, including encodings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Adding advanced security layers to a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Data stream transformations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Locale and language support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Checking for duplicate external transaction IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Exposing typelists and enums as enumeration values and string values . . . . . . . . . . . . . . . . . . . . . .79
Optional stateful session affinity using cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

4 Calling web services from Gosu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Overview of consuming web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Loading WSDL locally by using web service collections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Loading WSDL directly into the file system for testing purposes . . . . . . . . . . . . . . . . . . . . . . . . .82
Security and authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Types of client connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
How does Gosu process WSDL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Web service API objects are not thread safe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Learning Gosu XML APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
What Gosu creates from your WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Request XML complexity affects appearance of method arguments . . . . . . . . . . . . . . . . . . . . . . .86
Adding configuration options to a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Directly modifying the WSDL configuration object for a service . . . . . . . . . . . . . . . . . . . . . . . . .87
Authentication schemes for consuming WS-I web services from Gosu . . . . . . . . . . . . . . . . . . . . .88
Guidewire suite configuration file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Setting Guidewire transaction IDs on web service requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Setting a timeout on a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Custom SOAP headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Server override URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Setting XML serialization options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Setting locale or language in a Guidewire application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Implementing advanced web service security with WSS4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
One-way methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Asynchronous method calls to web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
MTOM attachments with Gosu as web service client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

5 General web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

Importing administrative data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
4
 Guidewire PolicyCenter 9.0.6 Integration Guide

Prepare exported administrative data for import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

Importing prepared administrative data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
CSV import and conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Advanced import or export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Maintenance tools web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Running batch processes by using web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Manipulating work queues by using web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Stopping startable plugins using web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Mapping typecodes and external system codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
The TypelistToolsAPI web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
The TypecodeMapper class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Profiling web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
System tools web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Getting and setting the run level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Getting server and schema versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Clustering tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Table import web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Template web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Workflow web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Workflow basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Zone data import web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

6 Account and policy web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Date- and time-related DTOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Account web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Add documents to an account. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Add notes to an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Find accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Assign activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Add contacts to an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Add location to an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Retrieve account numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Check for active policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Insert accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Merge accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Transfer policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Job web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Common parameters in the job APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Helper methods of the job APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Policy cancellation and reinstatement web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Begin a cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Rescind a cancellation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Find a cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Reinstate a policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Submission web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Passing in external policy period data for submissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Start a submission. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Start a submission and generate a quote. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Producer web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Product model web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Synchronize product model in database with file system XML. . . . . . . . . . . . . . . . . . . . . . . . . . 120
Synchronize system tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Query the database for product model information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Policy web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Add a referral reason. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

5
Guidewire PolicyCenter 9.0.6 Integration Guide

Close a referral reason. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Add activity from pattern. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Policy period web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Add notes to policies and policy periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Add documents to policy periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Policy earned premium web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Import policy web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Policy change web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Starting an automatic policy change job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Starting a manual policy change job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Specifying what policy data to change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Policy renewal web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Start renewals on existing policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Import a policy for renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Policy renewal methods for billing systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Archiving web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Check if a policy term is archived. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Restore a policy term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Suspend and resume archiving for a policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Quote purging web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Do not purge flag on a policy period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Part 3
Plugins
7 Overview of plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Overview of PolicyCenter plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Implementing plugin interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Choose a plugin implementation type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Writing a plugin implementation class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Registering a plugin implementation class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Deploying Java files, including Java code called from Gosu plugins . . . . . . . . . . . . . . . . . . . . . . 137
Error handling in plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Enabling or disabling a plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Example Gosu plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Special notes for Java plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Getting plugin parameters from the plugins registry editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Getting the local file path of the root and temp directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Plugin registry APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Getting references to plugins from Gosu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Plugin thread safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Using Java concurrent data types, even from Gosu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Avoid singletons due to thread-safety issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Design plugin implementations to support server clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Reading system properties in plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Do not call local web services from plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Creating unique numbers in a sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Restarting and testing tips for plugin developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Summary of all PolicyCenter plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

8 Account and policy plugins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Account plugin details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Performing account name clearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Customizing deleting an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Generate new account number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6
 Guidewire PolicyCenter 9.0.6 Integration Guide

Is account editable? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Customizing checking whether risk is reserved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Customizing behavior after merging accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Populating account summaries with extension properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Customizing transferring policies from one account to another account. . . . . . . . . . . . . . . . . . . . 152
Audit schedule selector plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Conversion on renewal plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Effective time plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
ETL product model loader plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
ETL product model loader plugin implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Non-operational plugin implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Job process creation plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Job number generator plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Location plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Compare locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Customize location cloning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Loss history plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Motor vehicle record (MVR) plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Overview of motor vehicle record integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
How PolicyCenter uses motor vehicle records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Implementations of the motor vehicle record plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Writing a motor vehicle record plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Notification plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Notification by action type (minimum) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Notification by action type (maximum) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Notification by category (minimum) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Notification by category (maximum) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Payment gateway configuration plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Payment gateway plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Policy evaluation plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Policy hold job evaluation plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Policy number generator plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Policy numbers conform to field validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Policy payment plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Policy period plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Set written date for a transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Get the unassigned policy number display string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Customizing behavior after applying changes from a branch . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Specifying types to omit if copying a contractual period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Specifying types to omit if copying a branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Customizing behavior after setting period window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Customizing behavior after creating draft branch in new period . . . . . . . . . . . . . . . . . . . . . . . . . 168
Customizing behavior before promoting a branch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Customizing behavior after handling a preemption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Policy plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Can start cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Can start reinstatement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Can start rewrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Can start policy change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Can start audit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Can start issuance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Can start renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Utility functions in the base configuration plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Policy term plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Calculate the period end date from a term type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

7
Guidewire PolicyCenter 9.0.6 Integration Guide

Calculate a term type from period start and end dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Calculate period end from a based on PolicyPeriod. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Proration plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Leap days and proration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Add a plugin parameter to the proration plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Provide your own prorater subclass. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Quote purging plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Create context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Prepare for purge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Take actions after purge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Skip policy period for purge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Skip orphaned policy period for purge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Get allowed job subtypes for purging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Get allowed job subtypes for pruning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Calculate next purge check date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Get purge job date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Get prune job date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Disable purging archived policy periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Purge context object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Reference date plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Coverage reference date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Exclusion reference date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Modifier reference date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Period reference date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Renewal plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Get renewal start date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Get automated renewal user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Determine whether to use renewal offers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Underwriting company plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

9 Authentication integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Overview of user authentication interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
User authentication source creator plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Handling errors in the authentication source plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Create a custom exception type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Authentication data in HTTP attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Authentication data in parameters in the URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Authentication data in HTTP headers for HTTP basic authentication . . . . . . . . . . . . . . . . . . . . . 186
User authentication service plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Authentication service sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Handling errors in authentication service plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
SOAP API user permissions and special-casing users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Example authentication service authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Deploying user authentication plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Database authentication plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Configuration for database authentication plugins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
WS-I web services authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

10 Document management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Document management overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Document storage overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Storing document content and metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Document storage plugin architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Understanding document IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Document IDs in emails and notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Implementing a document content source for external DMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
8
 Guidewire PolicyCenter 9.0.6 Integration Guide

Check for document existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Add documents and metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Retrieve documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Update documents and metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Remove documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Render a document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Implementing an IDocumentMetadataSource plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Basic methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Linking methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Document storage plugins in the base configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Documents storage directory and file name patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Remember to store public IDs in the external system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Asynchronous document storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Configure asynchronous document storage (sync-first or async-only) . . . . . . . . . . . . . . . . . . . . . 209
Disable asynchronous document content storage completely (sync-only). . . . . . . . . . . . . . . . . . . 210
Errors and document validation in asynchronous document storage . . . . . . . . . . . . . . . . . . . . . . 210
Final documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Final documents with IDocumentMetadataSource enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Final documents with IDocumentMetadataSource disabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Document interactions also depend on user permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
APIs to attach documents to business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Gosu APIs to attach documents to business objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Web service APIs to attach documents to business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

11 Document production. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Document production overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Document production types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Understanding synchronous and asynchronous document production . . . . . . . . . . . . . . . . . . . . . 214
User interface flow for document production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Document production plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Implementing synchronous document production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Implementing asynchronous document production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Configuring document production implementation mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Add a custom MIME type for document production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Licensing for server-side document production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Licensing for Microsoft Excel and Word document production . . . . . . . . . . . . . . . . . . . . . . . . . 220
Licensing for PDF document production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Write a document template descriptor and install a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Example simple template descriptor XML file with no context objects . . . . . . . . . . . . . . . . . . . . 222
Example template descriptor XML file with context objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Form fields and field groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Field groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Display values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Context objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Gosu APIs on template descriptor instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Template descriptor fields related to form fields and values to merge . . . . . . . . . . . . . . . . . . . . . 231
XML format for document template descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Add custom attributes document template descriptor XML format . . . . . . . . . . . . . . . . . . . . . . . 232
Create your actual template file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Adding document templates and template descriptors to a configuration . . . . . . . . . . . . . . . . . . . 233
Creating new documents from Gosu rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Example document creation after sending an email. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Important notes about cached document UIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Profile document production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

9
Guidewire PolicyCenter 9.0.6 Integration Guide

12 Geographic data integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Geocoding plugin integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
How PolicyCenter uses geocode data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
What the geocoding plugin does. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Synchronous and asynchronous calls to the geocoding plugin . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Using a proxy server with the geocoding plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Batch geocoding only some addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Built-in Bing maps geocoding plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
BingMapsPluginRest plugin implementation class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Geocoding and routing responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Geocoding request generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Deploy a geocoding plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Writing a geocoding plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Using the abstract geocode Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
High-level steps to writing a geocoding plugin implementation . . . . . . . . . . . . . . . . . . . . . . . . . 241
Geocoding an address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Getting driving directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Getting a map for an address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Getting an address from coordinates (reverse geocoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Geocoding status codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
List of geocoding status codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

13 Encryption integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Defining the encryption algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Sending encrypted properties to external systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Sending encrypted properties to other InsuranceSuite applications . . . . . . . . . . . . . . . . . . . . . . . 247
Setting encrypted properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Querying encrypted properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Writing your encryption plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Example encryption plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Detecting accidental duplication of encryption or decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Installing your encryption plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Enable your encryption plugin implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Adding or removing encrypted properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Changing your encryption algorithm later. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Changing your encryption algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

14 Management integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Overview of management integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Management plugin examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Calling the example JMXManagementPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

15 Other plugin interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

SharedBundlePlugin marker interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Credentials plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Preupdate handler plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Validation plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Work item priority plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Exception and escalation plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Sending emails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
IEmailTemplateSource plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Defining base URLs for fully qualified domain names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Vehicle identification number plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Automatic address completion and fill-in plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Phone number normalizer plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Official IDs mapped to tax IDs plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
10
 Guidewire PolicyCenter 9.0.6 Integration Guide

Testing clock plugin (for non-production servers only). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Using the testing clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

16 Startable plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Overview of startable plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Specifying when a startable plugin begins execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Initializing a startable plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Registering startable plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Manually starting and stopping a startable plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Writing a singleton startable plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
User contexts for startable plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Simple startable plugin example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Writing a distributed startable plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Java and startable plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Defining startable plugins in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Persistence and startable plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

17 Multi-threaded inbound integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Overview of multi-threaded inbound integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Overview of inbound integration configuration XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Inbound integration core plugin interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Inbound integration handlers for file and JMS integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Making import actions repeatable without side effects or errors . . . . . . . . . . . . . . . . . . . . . . . . . 279
Configuring inbound integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Thread pool configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Varying the inbound integration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Inbound integration XML elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Using the inbound integration polling and throttle intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Inbound file integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Create an inbound file integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Example file integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Inbound JMS integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Create an inbound JMS integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Custom inbound integrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Writing a work agent implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Install a custom inbound integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Part 4
Messaging
18 Messaging and events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Overview of messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Message history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Messaging destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Root object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Primary entity and primary object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Safe ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Transport neutrality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Overview of messaging flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Messaging flow details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Overview of message destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Use the Messaging editor to create new messaging destinations . . . . . . . . . . . . . . . . . . . . . . . . . 303

11
Guidewire PolicyCenter 9.0.6 Integration Guide

Sharing plugin classes across multiple destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Handling acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Messaging database transactions during sending. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Destinations in the base configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Message processing cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Sending non-safe-ordered messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Sending safe-ordered messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Improving messaging performance for Oracle databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Messaging plugin interaction and flow diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
List of messaging events in PolicyCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
At what time does a remove-related event trigger? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Triggering custom event names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Custom events from SOAP acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
How custom events affect preupdate and validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
No events from import tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Generating new messages in event fired rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Rule set structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Simple message payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Message payloads and setting message root or primary entities . . . . . . . . . . . . . . . . . . . . . . . . . 320
Multiple messages for one event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Determining what changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Rule sets must never call message methods for ACK, error, or skip . . . . . . . . . . . . . . . . . . . . . . 321
Save values across rule set executions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Creating a payload by using Gosu templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Setting a message root object or primary object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Creating XML payloads by using GX models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Using Java code to generate messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Saving attributes of a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Maximum message size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
If multiple events fire, which message sends first?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Restrictions on entity data in messaging rules and messaging plugins . . . . . . . . . . . . . . . . . . . . . . 325
Event fired rule set restrictions for entity data changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Messaging plugin restrictions for entity data changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Messaging interacts with PolicyCenter workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Database transactions when creating messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Messaging plugins must not call SOAP APIs on the same server . . . . . . . . . . . . . . . . . . . . . . . . 326
Delaying or censoring message generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Validity and rule-based event filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Late binding data in your payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Implement late binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Tracking a specific entity with a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Implementing messaging plugins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Ensuring thread safety in messaging plugin code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Initializing a messaging plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Getting messaging plugin parameters from the plugin registry . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Implementing message payload transformations before send . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Implementing a message transport plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Implementing post-send processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Implementing a MessageReply plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Error handling in messaging plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Suspend, resume, and shut down a messaging destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Map message payloads by using tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Message status code reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Reporting acknowledgments and errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Message sending error behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

12
 Guidewire PolicyCenter 9.0.6 Integration Guide

Submitting ACKs, errors, and duplicates from messaging plugins . . . . . . . . . . . . . . . . . . . . . . . 341

Using web services to submit ACKs and errors from external systems . . . . . . . . . . . . . . . . . . . . 342
Using web services to retry messages from external systems . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Message error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Resynchronizing messages for a primary object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Cloning new messages from pending messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
How resynchronization affects preupdate and validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Resync in ContactManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Monitoring messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Messaging tools web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Acknowledging messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Getting the ID of a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Retrying messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Skipping a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Resynchronizing an account for a destination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Purging completed messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Suspending a destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Resuming a destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Getting messaging statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Getting the status of a destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Getting configuration information from a destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Changing messaging destination configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Included messaging transports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Email message transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Register and enable the console message transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Part 5
Policy-related integrations
19 Rating integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
The rating framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Guidewire Rating Management and PCRatingPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Overview of cost data objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Where to override the default rating engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Common questions about the default rating engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Optional asynchronous rating. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Implementing rating for a new line of business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
What do cost data objects contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Cost core properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Adding line-specific cost properties and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Fixed ID keys link a cost data object to another object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Cost data object methods and constructors to override. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Cost data APIs that you can call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Checklist for relationship changes in cost data objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Writing your own line-specific rating engine subclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
A rating line example for Personal Auto: PersonalAutoCovCostData. . . . . . . . . . . . . . . . . . . . . . . 393
A close look at PersonalAutoCovCostData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Constructors for PersonalAutoCovCostData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Setting specific properties on cost for PersonalAutoCovCostData. . . . . . . . . . . . . . . . . . . . . . . . 395
Versioned costs for PersonalAutoCovCostData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Key values for PersonalAutoCovCostData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Rating slice details for PersonalAutoCovCostData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Rate window method for PersonalAutoCovCostData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Rating variations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

13
Guidewire PolicyCenter 9.0.6 Integration Guide

Workers’ compensation rating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Inland marine rating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
General liability rating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

20 Reinsurance integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Reinsurance integration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Reinsurance data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Risk entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Risk version list entity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Reinsurance plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Architecture of the Reinsurance Management plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Configuration plugins for Guidewire Reinsurance Management . . . . . . . . . . . . . . . . . . . . . . . . . 406
Creating a plugin implementation for your own reinsurance system . . . . . . . . . . . . . . . . . . . . . . 406
Reinsurance plugin interface methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Reinsurance configuration plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Reinsurance configuration plugin implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Reinsurance configuration plugin methods and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Reinsurance ceding plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Reinsurance ceding plugin implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Reinsurance ceding plugin methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Reinsurance coverage web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Methods of the PolicyCenter reinsurance coverage web service . . . . . . . . . . . . . . . . . . . . . . . . . 415

21 Forms integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

Forms integration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Forms inference classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Creating inference data and XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Determining whether to add or reprint a form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Form data helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Handling multiple instances of one form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Reference dates on a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Forms messaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Messaging plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Creating documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

22 Policy difference customization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

Overview of policy differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Difference item subclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Comparing branches by using difference helper classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Difference API classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Difference methods on the DiffHelper class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Difference methods on the DiffUtils class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Comparing individual objects by using matchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Planning how to match entity instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Writing delegate-based matcher classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Customizing the classes that perform matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Copier classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Bean matcher classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Important files for customizing policy differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Filtering difference items after creation of database records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Difference tree XML configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
Editing the difference tree XML files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Customizing differences for new lines of business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Filtering difference items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Customizing personal auto line of business. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
APIs for calculating differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
14
 Guidewire PolicyCenter 9.0.6 Integration Guide

Differences between a branch and its based-on branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

Differences between any two branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

Part 6
Claim and policy integrations
23 Claim and policy integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Claim search from PolicyCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Get claim details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
Permission to view a claim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
Policy system notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
Receiving a notification of a large loss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
PolicyCenter implementation of the large loss notification web service . . . . . . . . . . . . . . . . . . . . 450
Claim to policy system notification web service API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Policy search web service for claim system integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Retrieving a policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Extend the search criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Typecode maximum length and trimmed typecodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Policy search SOAP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
PolicyCenter exit points to ClaimCenter and BillingCenter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
PolicyCenter product model import into ClaimCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Configuring the ClaimCenter typelist generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Run the ClaimCenter typelist generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
Using generated typelists in ClaimCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Typelist localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Policy location search API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Dependencies of the policy location search API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Finding policy locations within geographic bounding boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

Part 7
Billing integrations
24 Billing integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Billing integration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Mechanisms for integrating PolicyCenter and a billing system . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Integrating PolicyCenter and BillingCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Integrating policy center with another billing system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
How billing data flows between applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Notifying a billing system of policy changes and premiums. . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Tracking policies term by term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
PolicyCenter properties for billing system usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Asynchronous communication between PolicyCenter and billing system. . . . . . . . . . . . . . . . . . . 472
Exit points between PolicyCenter and billing system applications . . . . . . . . . . . . . . . . . . . . . . . 474
Configuring which system receives contact updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Using integration-specific containers for integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Billing producers and producer codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Using producer information in BillingCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Comparison of producer codes in PolicyCenter and BillingCenter . . . . . . . . . . . . . . . . . . . . . . . 476
PolicyCenter producer to BillingCenter properties mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Billing accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
PolicyCenter billing account to BillingCenter properties mapping . . . . . . . . . . . . . . . . . . . . . . . 477
Billing plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Delinquency plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Invoicing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
15
Guidewire PolicyCenter 9.0.6 Integration Guide

Contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Policy period merges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Service tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Billing instructions in BillingCenter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Billing instruction subtypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
PolicyCenter financials to BillingCenter charge properties mapping . . . . . . . . . . . . . . . . . . . . . . 483
Sending PolicyCenter transaction information to BillingCenter . . . . . . . . . . . . . . . . . . . . . . . . . 483
Billing flow for new-period jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Flow of submission, renewal, and rewrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Policy period mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Billing methods and payment plans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
New periods and term confirmed flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Billing flow for existing-period jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Billing implications of midterm changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Midterm changes to a policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Midterm changes to billing method or payment plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Holding billing on midterm policy transaction charges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Midterm changes to producer of record or producer of service . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Moving a policy to a new account in midterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Billing implications of renewals or rewrites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Choosing the renewal flow type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Account creation for conversion on renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Copying billing data to new periods on renewal or rewrite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Billing implications for cancellations and reinstatements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Cancellations that start in PolicyCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Cancellations that start in BillingCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Billing implications of audits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Holding periods open for audits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Generating an audit report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Sending audit premiums as incremental. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Audit reversals and revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Billing implications for premium reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Billing implications of delinquency for failure to report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Billing implications of deposits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Deposits in submission, renewal, or rewrite jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Deposits in policy change and reinstatement jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Deposits in premium reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Deposits in cancellation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Deposits in final audit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Billing implications of up-front payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Implementing the billing system plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Account management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Policy period management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Getting period information from the billing system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Billing system notifications of PolicyCenter policy actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Producer management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Agency bill plan availability retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Commission plan management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Payment plans and installment previews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Updating contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Other billing system plugin methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Implementing the billing summary plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Interfaces used by the billing summary plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Getting policies billed to accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Retrieving account billing summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511

16
 Guidewire PolicyCenter 9.0.6 Integration Guide

Retrieving account invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512

Retrieving billing summaries for policy periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Retrieving policy billing summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Payment integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Overview of integration with a payment system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Entities and classes for tracking payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Integration points to external payment systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Accessing an external payment system to add a new payment instrument . . . . . . . . . . . . . . . . . . 514
Configure PolicyCenter to use a real payment system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Accessing an external payment gateway to add an up-front payment. . . . . . . . . . . . . . . . . . . . . . 516
Configuring PolicyCenter to use a real payment gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518

Part 8
Contact integrations
25 Contact integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Integrating with a contact management system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Inbound contact integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Asynchronous messaging with the contact management system . . . . . . . . . . . . . . . . . . . . . . . . . 530
Retrieve a contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Contact searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Support for finding duplicate contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Finding duplicate contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Find duplicate contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Adding contacts to the external system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Updating contacts in the external system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Overwriting the local contact with latest values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Configuring how PolicyCenter handles contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Configuring available account contact role types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Configuring mapping of contact type to account contact role . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Configuring account contact role type display name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Configuring account contact role type for a policy contact role . . . . . . . . . . . . . . . . . . . . . . . . . 535
Configuring allowed contact types for policy contact role type. . . . . . . . . . . . . . . . . . . . . . . . . . 535
Configuring whether to treat an account contact type as available. . . . . . . . . . . . . . . . . . . . . . . . 535
Synchronizing contacts with accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Account contact plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Account contact role plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Contact web service APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Deleting a contact. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Adding a contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Updating a contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Merging contact addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Merging contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Handling rejection and approval of pending changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Activating and deactivating contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Getting associated policy transactions for a contact. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Getting associated policies for a contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Getting associated accounts for a contact. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Address APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Updating an address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

Part 9
Importing policy data

17
Guidewire PolicyCenter 9.0.6 Integration Guide

26 Importing from database staging tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547

Overview of importing staging tables and zone data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
Importing zone data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
Files for zone data import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
Zone data files supplied by Guidewire. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
Zone data configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
Database import tables and columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
Staging tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
Load error table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
Load history table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
Load command IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
Load user IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Load time stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Tools and commands for data Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Server modes and run levels for database staging table import . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Database consistency checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Integrity checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Database performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Loading zone data into staging tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Clearing errors from staging tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Importing data into operational tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
Detailed work flow for a typical database staging table import . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
Prepare the data and the PolicyCenter database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
Import data into the staging tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
Load staging table data into operational tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
Perform post-import tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
Table import tips and troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558

Part 10
Other integration topics
27 GX models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
GX models overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Create a GX model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Including a GX model inside another GX model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
Mappable and unmappable properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
Normal and key properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
Automatic publishing of the generated XSD schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
Create an instance of a GX model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
GXOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
GX model labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
Assign a label to a GX model property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Reference a GX model label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Create an instance of a GX model with labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
GX model label example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
Serialize a GX model object to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
Arrays of entities in XML output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
Sending a message only if data model fields changed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
Conversion from Gosu types to XSD types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

28 Archiving integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

Overview of archiving integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
Basic integration flow for archiving storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
Basic integration flow for archiving retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
PolicyCenter web service for archiving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
18
 Guidewire PolicyCenter 9.0.6 Integration Guide

Check for archiving before accessing policy data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

Upgrading the data model of retrieved data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Error handling during archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Archiving storage integration detailed flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Archiving retrieval integration detailed flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Archive source plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Archive source plugin methods and archive transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
Archive source plugin storage methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
Archive source plugin retrieve methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
Archive source plugin utility methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Archiving eligibility plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

29 Custom batch processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

Overview of custom batch processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
Batch processing modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
Choosing a mode for custom batch processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
About scheduling batch processing types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
About manually executing batch processing types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Batch processing typecodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Custom work queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Custom work queue overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Considerations for developing a custom work queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
Define a typecode for a custom work queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
Define a custom work item type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
Creating a custom work queue class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
Developing the writer for your custom work queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
Developing workers for your custom work queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
Bulk insert work queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Overview of bulk insert work queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Bulk insert work queue declaration and constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Querying for targets of a bulk insert work queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
Eliminating duplicate items in bulk insert work queue queries . . . . . . . . . . . . . . . . . . . . . . . . . . 600
Processing work items in a custom bulk insert work queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
Example work queue that bulk inserts its work items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601
Examples of Custom Workqueues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Example work queue that extends WorkQueueBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Example work queue for updating entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
Example work queue with a custom work item type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
Developing custom batch processing types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
Custom batch process overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
Create a custom batch process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
Define a typecode for a custom batch process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
Batch process base class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
Useful properties on class BatchProcessBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
Useful methods on class BatchProcessBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Examples of custom batch processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
Example batch process for a background task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
Example batch process for unit of work processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Working with custom batch processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
Categorizing a batch processing typecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
Updating the work queue configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Implementing the processes plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Monitoring batch processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
Monitoring batch processing by using the administration screens . . . . . . . . . . . . . . . . . . . . . . . . 619
Monitoring batch processing for completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620

19
Guidewire PolicyCenter 9.0.6 Integration Guide

Monitoring batch processes by using maintenance tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620

Periodically purging batch processing entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
Managing user entity updates in batch processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Set the external user field in batch processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

30 Free-text search integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623

Free-text search plugins overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
Connecting the free-text plugins to the Guidewire Solr Extension. . . . . . . . . . . . . . . . . . . . . . . . 623
Enabling and disabling the free-text plugins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Running the free-text plugins in debug mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Free-text load and index plugin and message transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Message destination for free-text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Enable the message destination for free-text search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
ISolrMessageTransportPlugin plugin parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Free-text search plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
ISolrSearchPlugin plugin parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626

31 Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
Implementing servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
Create a basic servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
Test your basic servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
Example of a basic servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
@Servlet annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
Important HTTPServletRequest object properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
Implementing servlet authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
Create a servlet that provides basic authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
Test your basic authentication servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Example of a basic authentication servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Supporting multiple authentication types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
Abstract HTTP basic authentication servlet class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
Abstract Guidewire authentication servlet class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
ServletUtils authentication methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Example of a servlet using multiple authentication types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
Test your servlet using multiple authentication types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636

32 Database connection pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639

Reserving a single database connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639

33 Data extraction integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641

Why Gosu templates are useful for data extraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
Data extraction using web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Error handling in templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Getting parameters from URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Example templates in the base configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Using loops in templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Structured export formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Handling data model extensions in Gosu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
Gosu template APIs for data extraction integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644

34 Proxy servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645

Proxy server overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
Resources for understanding and implementing SSL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
Web services and proxy servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Configuring a proxy server with Apache HTTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Apache basic installation checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Certificates, private keys, and passphrase scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647

20
 Guidewire PolicyCenter 9.0.6 Integration Guide

Proxy server integration types for PolicyCenter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647

Bing maps geocoding service communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Proxy building blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
Downstream proxy with no encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
Downstream proxy with encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
Upstream (reverse) proxy with encryption for service connections . . . . . . . . . . . . . . . . . . . . . . . 649
Upstream (reverse) proxy with encryption for user connections . . . . . . . . . . . . . . . . . . . . . . . . . 650

35 Java and OSGi support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

Overview of Java and OSGi support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Accessing Gosu types from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Implementing plugin interfaces in Java and optionally OSGi . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Choosing between a Java plugin and an OSGi plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Your IDE options for plugin development in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Java IDE inspections that flag unsupported internal APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Install the internal API inspection in IntelliJ IDEA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Accessing entity data from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
Regenerate Java API libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
Java API reference documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Accessing entity instances from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Accessing typecodes from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Getting a reference to an existing bundle from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
Creating a new bundle from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
Creating a new entity instance from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
Querying for entity data from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
Using reflection to access Gosu classes from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
Using Gosu enhancement properties and methods from Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
Class loading and delegation for non-OSGi Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
Deploying non-OSGi Java classes and JAR files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Deploy an example Java class with no plugins and no entities . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Using IntelliJ IDEA with OSGi editor to deploy an OSGi plugin. . . . . . . . . . . . . . . . . . . . . . . . . . 662
Generating Java API libraries before using OSGi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
Launching IntelliJ IDEA with OSGi editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
Create a new project with an OSGi plugin module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
Create an OSGi-compliant class that implements a plugin interface . . . . . . . . . . . . . . . . . . . . . . 664
Example startable plugin in Java using OSGi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
The OSGi Ant build script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
Compile and install your OSGi plugin as an OSGi bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
Configuring third-party libraries in an OSGi plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
Advanced OSGi dependency and settings configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
OSGi dependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
OSGi build properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
OSGi bundle metadata configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
OSGi build configuration Ant script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Update your OSGi plugin project after product location changes . . . . . . . . . . . . . . . . . . . . . . . . . . 672

21
Guidewire PolicyCenter 9.0.6 Integration Guide

22
 Guidewire PolicyCenter 9.0.6 Integration Guide

About PolicyCenter documentation

The following table lists the documents in PolicyCenter documentation:

Document Purpose
InsuranceSuite Guide If you are new to Guidewire InsuranceSuite applications, read the InsuranceSuite Guide for informa‐
tion on the architecture of Guidewire InsuranceSuite and application integrations. The intended read‐
ers are everyone who works with Guidewire applications.
Application Guide If you are new to PolicyCenter or want to understand a feature, read the Application Guide. This guide
describes features from a business perspective and provides links to other books as needed. The in‐
tended readers are everyone who works with PolicyCenter.
Database Upgrade Guide Describes the overall PolicyCenter upgrade process, and describes how to upgrade your PolicyCenter
database from a previous major version. The intended readers are system administrators and imple‐
mentation engineers who must merge base application changes into existing PolicyCenter application
extensions and integrations.
Configuration Upgrade Guide Describes the overall PolicyCenter upgrade process, and describes how to upgrade your PolicyCenter
configuration from a previous major version. The intended readers are system administrators and im‐
plementation engineers who must merge base application changes into existing PolicyCenter applica‐
tion extensions and integrations. The Configuration Upgrade Guide is published with the Upgrade
Tools and is available from the Guidewire Community.
New and Changed Guide Describes new features and changes from prior PolicyCenter versions. Intended readers are business
users and system administrators who want an overview of new features and changes to features. Con‐
sult the “Release Notes Archive” part of this document for changes in prior maintenance releases.
Installation Guide Describes how to install PolicyCenter. The intended readers are everyone who installs the application
for development or for production.
System Administration Guide Describes how to manage a PolicyCenter system. The intended readers are system administrators re‐
sponsible for managing security, backups, logging, importing user data, or application monitoring.
Configuration Guide The primary reference for configuring initial implementation, data model extensions, and user inter‐
face (PCF) files for PolicyCenter. The intended readers are all IT staff and configuration engineers.
PCF Reference Guide Describes PolicyCenter PCF widgets and attributes. The intended readers are configuration engineers.
Data Dictionary Describes the PolicyCenter data model, including configuration extensions. The dictionary can be gen‐
erated at any time to reflect the current PolicyCenter configuration. The intended readers are configu‐
ration engineers.
Security Dictionary Describes all security permissions, roles, and the relationships among them. The dictionary can be
generated at any time to reflect the current PolicyCenter configuration. The intended readers are con‐
figuration engineers.
Globalization Guide Describes how to configure PolicyCenter for a global environment. Covers globalization topics such as
global regions, languages, date and number formats, names, currencies, addresses, and phone num‐
bers. The intended readers are configuration engineers who localize PolicyCenter.
Rules Guide Describes business rule methodology and the rule sets in Guidewire Studio for PolicyCenter. The in‐
tended readers are business analysts who define business processes, as well as programmers who
write business rules in Gosu.
Contact Management Guide Describes how to configure Guidewire InsuranceSuite applications to integrate with ContactManager
and how to manage client and vendor contacts in a single system of record. The intended readers are
PolicyCenter implementation engineers and ContactManager administrators.

About PolicyCenter documentation 23

Guidewire PolicyCenter 9.0.6 Integration Guide

Document Purpose
Best Practices Guide A reference of recommended design patterns for data model extensions, user interface, business
rules, and Gosu programming. The intended readers are configuration engineers.
Integration Guide Describes the integration architecture, concepts, and procedures for integrating PolicyCenter with ex‐
ternal systems and extending application behavior with custom programming code. The intended
readers are system architects and the integration programmers who write web services code or plu‐
gin code in Gosu or Java.
Java API Reference Javadoc‐style reference of PolicyCenter Java plugin interfaces, entity fields, and other utility classes.
The intended readers are system architects and integration programmers.
Gosu Reference Guide Describes the Gosu programming language. The intended readers are anyone who uses the Gosu lan‐
guage, including for rules and PCF configuration.
Gosu API Reference Javadoc‐style reference of PolicyCenter Gosu classes and properties. The reference can be generated
at any time to reflect the current PolicyCenter configuration. The intended readers are configuration
engineers, system architects, and integration programmers.
Glossary Defines industry terminology and technical terms in Guidewire documentation. The intended readers
are everyone who works with Guidewire applications.
Product Model Guide Describes the PolicyCenter product model. The intended readers are business analysts and implemen‐
tation engineers who use PolicyCenter or Product Designer. To customize the product model, see the
Product Designer Guide.
Product Designer Guide Describes how to use Product Designer to configure lines of business. The intended readers are busi‐
ness analysts and implementation engineers who customize the product model and design new lines
of business.

Conventions in this document

Text style Meaning Examples
italic Indicates a term that is being defined, A destination sends messages to an external system.
added emphasis, and book titles. In Navigate to the PolicyCenter installation directory by running the
monospace text, italics indicate a variable to following command:
be replaced.
cd installDir

bold Highlights important sections of code in for (i=0, i<someArray.length(), i++) {

examples. newArray[i] = someArray[i].getName()
}

narrow bold The name of a user interface element, such Click Submit.
as a button name, a menu item name, or a
tab name.
monospace Code examples, computer output, class and The getName method of the IDoStuff API returns the name of the
method names, URLs, parameter names, object.
string literals, and other objects that might
appear in programming code.
monospace italic Variable placeholder text within code Run the startServer server_name command.
examples, command examples, file paths, Navigate to http://server_name/index.html.
and URLs.

Support
For assistance, visit the Guidewire Community.
24 About PolicyCenter documentation
 Guidewire PolicyCenter 9.0.6 Integration Guide

Guidewire customers
https://community.guidewire.com

Guidewire partners
https://partner.guidewire.com

About PolicyCenter documentation 25

Guidewire PolicyCenter 9.0.6 Integration Guide

26 About PolicyCenter documentation

part 1

Planning integration projects

Guidewire PolicyCenter 9.0.6 Integration Guide
chapter 1

Integration overview

You can integrate a variety of external systems with PolicyCenter by using services and APIs that link PolicyCenter
with custom code and external systems. This overview provides information to help you plan integration projects for
your PolicyCenter deployment and provides technical details critical to successful integration efforts.

Overview of integration methods

PolicyCenter addresses the following integration architecture requirements.

A service-oriented architecture.
Encapsulate your integration code so that upgrading the core application requires few other changes. Also, a
service-oriented architecture enables APIs to use different languages or platforms.

Customize behavior with the help of external code or external systems.

For example, implement special policy validation logic, use a legacy system that generates policy numbers, or
query a legacy system.

Send messages to external systems in a transaction-safe way.

Trigger actions after important events happen in PolicyCenter, and notify external systems only if the change is
successful and no exceptions occurred. For example, alert a policy database if anyone changes policy
information.

Flexible export.
Providing different types of export minimizes data conversion logic. Simplifying the conversion logic improves
performance and code maintainability for integrating with diverse and complex legacy systems.

Predictable error handling.

Find and handle errors cleanly and consistently for a stable integration with custom code and external systems.

Link business rules to custom task-oriented Gosu or Java code.

Let Gosu-based business rules in Guidewire Studio or Gosu templates call Java classes directly from Gosu.

Import or export data to or from external systems.

There are multiple ways to import data to and export data from PolicyCenter. You can choose which methods
make the most sense for your integration project.

Integration overview 29
Guidewire PolicyCenter 9.0.6 Integration Guide

Use clearly-defined industry standard protocols for integration points.

PolicyCenter provides APIs to retrieve policies, create users, manage documents, trigger events, validate records,
and trigger bulk import/export. However, most legacy system integrations require additional integration points
customized for each system.
To achieve these goals, the PolicyCenter integration framework provides multiple ways to integrate external code
with PolicyCenter.

Web service APIs

Web service APIs are a general-purpose set of application programming interfaces that you can use to query, add,
or update Guidewire data, or trigger actions and events programmatically. Because these APIs are web services,
you can call them from any language and from any operating system.
A typical use of the web service APIs is to programmatically add submissions, policy revisions, and policies to
PolicyCenter.
PolicyCenter supports WS-I web services that use the SOAP protocol. You can use the built-in SOAP APIs, but
you can also design your own SOAP APIs in Gosu and expose them for use by remote systems. Additionally,
your Gosu code can call web services hosted on other computers to trigger actions or retrieve data.

Plugins
PolicyCenter plugins are classes that PolicyCenter invokes to perform an action or calculate a result. Guidewire
recommends writing plugins in Gosu, although you can also write plugins in Java. Gosu code, like Java code, can
call third-party Java classes and Java libraries.
Several types of plugins are supported.

Messaging plugins
Send messages to remote systems, and receive acknowledgments of each message. PolicyCenter has a
sophisticated transactional messaging system to send information to external systems in a reliable way. Any
server in the cluster can create a message for any data change. The only servers that send messages are servers
with the messaging server role.

Authentication plugins
Integrate custom authentication systems. For instance, define a user authentication plugin to support a
corporate directory that uses the LDAP protocol. Or define a database authentication plugin to support custom
authentication between PolicyCenter and its database server.

Document and form plugins

Transfer documents to and from a document management system, and help prepare new documents from
templates. Additionally, use Gosu APIs to create and attach documents.

Inbound integration plugins

Multi-threaded inbound integrations for high-performance data import. PolicyCenter provides
implementations for reading files and receiving JMS messages, but you can also write your own
implementations that leverage the multi-threaded framework.

Other plugins
Some examples are plugins that generate policy numbers (IPolicyNumGenAdapter) or get a claim related to a
policy from a claims system (IClaimSearchAdapter).

Templates
Generate text-based formats that contain combinations of PolicyCenter data and fixed data. Templates are ideal
for name-value pair export, HTML export, text-based form letters, or simple text-based protocols.
The following table compares the main integration methods.

30 chapter 1: Integration overview

 Guidewire PolicyCenter 9.0.6 Integration Guide

Integration type Description What you write

Web services A full API to manipulate PolicyCenter data and • To publish web services, write Gosu classes
trigger actions externally from any programming that implement each operation as a class
language or platform that uses PolicyCenter Web method.
services APIs. Accessed by using the platform‐ • To consume web services that a Guidewire
independent SOAP protocol. application publishes, write Java or Gosu code
on an external system. The external system
calls web services by using the WSDL that
PolicyCenter generates.
• To consume external web services from Gosu,
write Gosu code that uses WSDL from the
external system. Gosu creates native types
from the WSDL that you download to the
Studio environment.
• In all cases, define objects that encapsulate
only the data you need to transfer to and
from PolicyCenter. The general name for such
objects are Data Transfer Objects (DTOs).
Define DTOs as Gosu classes or by using XSDs.
Plugins Classes that PolicyCenter calls to perform tasks or • Gosu classes that implement a Guidewire‐
calculate a result. Plugins run in the same Java defined interface.
virtual machine (JVM) as PolicyCenter. • Java classes that implement a Guidewire‐
defined interface. Optionally use OSGi, a Java
component system.
Messaging code Changes to application data trigger events that • Gosu code in the Event Fired rule set. These
generate messages to external systems. You can rules create messages (Message objects) that
send messages to external systems and track re‐ are processed in a separate transaction,
sponses called acknowledgments. possibly on other nodes in the cluster.
Messages represent data to send to external
systems.
• Messaging plugin implementations send the
messages to external systems. The most
important interface is MessageTransport.
There are other optional plugins.
• Configure one or more messaging
destinations in Studio to specify your
messaging plugins. After you register your
plugins in the Plugins editor, you must also
use the Messaging editor for each
destination.
• In all cases, define objects that encapsulate
only the data you need to transfer to and
from PolicyCenter. The general name for such
objects is Data Transfer Objects (DTOs).
Define DTOs as Gosu classes or by using XSDs.
GX models GX models enable the properties of an entity or • Using the GX Model editor in Studio, you
other data type to be converted to XML. The GX customize the properties in an entity or other
model editor in Studio defines the data type’s data type to export in XML format.
properties to include in the GX model. As the • Various integration code that uses the GX
model is defined, an XSD schema definition is au‐ model.
tomatically generated.
Subsequently, an instance of the GX model con‐
taining XML data can be used to integrate with
external systems. For example, messaging plugins
could use a GX model to send XML to external
systems. Also, a web service could accept the
XML data contained in a GX model as a payload
from an external system.

Integration overview 31
Guidewire PolicyCenter 9.0.6 Integration Guide

Integration type Description What you write

Templates Several data extraction mechanisms that perform • Text files that contain small amounts of Gosu
database queries and format the data as necessa‐ code.
ry. For example:
• Send notifications as form letters and use
plain text with embedded Gosu code to
simplify deployment and ongoing updates.
• Design a template that exports HTML for easy
development of web‐based reports of
PolicyCenter data.
Links Link from a PolicyCenter screen to a URL address, • Create an ExitPoint PCF file.
such as a screen in another InsuranceSuite • Incorporate the ExitPoint into the
application or an external application. The link is originating PolicyCenter screen.
implemented by using an ExitPoint PCF file.

PolicyCenter integration elements

The following diagram summarizes some common elements of policy management using PolicyCenter.

PolicyCenter Integration Elements

Notify of new claims Send policy data External Rating

Return quotes Entgine
Search claims
Guidewire Return claim searches
ClaimCenter Risk Analysis Tools
Add risk data
D&B, MVR
Search policies
Guidewire
Return policy searches PolicyCenter Upload/download Doc Management
documents System

Add and edit policies

Web Service Get/set contacts
API Clients Search policies
Guidewire
Return policy searches ContactManager

Renewal Policy
Reporting added to
Send PolicyCenter
Send
payment payment Legacy
status info
Policy Admin System
Reporting Tools (PAS)

Guidewire BillingCenter

Solid lines indicate action

Dotted lines indicate results

32 chapter 1: Integration overview

 Guidewire PolicyCenter 9.0.6 Integration Guide

See also

• For information about integrating with BillingCenter, see “Billing integration” on page 469.
• For information about integrating with ClaimCenter, see “Claim and policy integration” on page 449.
• For information about integrating with ContactManager, see the Contact Management Guide.

Preparing for integration development

During integration development, edit configuration files in the hierarchy of files in the product installation directory.
In most cases, you modify data only through the Studio interface, which handles any SCM (Source Configuration
Management) requests. The Studio interface also copies read-only files to the configuration module in the file
hierarchy for your files and makes files writable as appropriate.
However, in some cases you need to add files directly to certain directories in the configuration module hierarchy,
such as Java class files for Java plugin support. The configuration module hierarchy for your files is in the hierarchy:

PolicyCenter/modules/configuration

Some of the main configuration subdirectories are described in the following table.

Directory under the Files that the directory contains

configuration module

config/web Your web application configuration files, also known as PCF files.
config/logging The logging configuration file logging.properties.
config/templates Two types of templates relevant for integration.
Plugin templates
Use Gosu plugin templates for a small number of plugin interfaces that require them. These
plugin templates extract important properties from entity instances and generate text that
describes the results. Whenever PolicyCenter needs to call the plugin, PolicyCenter passes the
template results to the plugin as String parameters.
Messaging templates
Use optional Gosu messaging templates for your messaging code. Use messaging templates to
define notification letters or other similar messages contain large amounts of text but a small
amount of Gosu code.
The base configuration provides versions of some of these templates.
plugins Your Java plugin files.
Register your plugin implementations in the Plugins registry in Studio. When you register the plu‐
gin in the Plugins registry, you can specify a plugin directory, which is the name of a subdirectory of
the plugins directory. If you do not specify a subdirectory, PolicyCenter uses the shared subdirec‐
tory as the plugin directory.
For a messaging plugin, you must register this information in two different registries:
• The plugin registry in the plugin editor in Studio
• The messaging registry in the Messaging editor in Studio.

Some additional important integration-related directories are described in the following table.

Directory under the PolicyCenter installation Files that the directory contains
directory
PolicyCenter installation directory Command‐prompt tools such as gwb.bat. Use for the following integration
tasks:
• Regenerating the Java API libraries and local WSI web service WSDL.
• Regenerating the Data Dictionary.

Integration overview 33
Guidewire PolicyCenter 9.0.6 Integration Guide

Directory under the PolicyCenter installation Files that the directory contains
directory
modules/configuration/gsrc/wsi/ WSDL files generated locally.
local/gw/webservice/
modules/configuration/gsrc/wsi/
local/gw/wsi/

admin Command‐prompt tools that control a running PolicyCenter server. Almost all
of these tools are small Gosu scripts that call public web service APIs.

Integration documentation overview

The Integration Guide is the main source for integration information. Other useful information can be found in the
various API References and the Data Dictionary.

API reference documentation for integration programmers

The easiest way to learn what interfaces are available is by reading the various API References.

Java API reference

The Java API Reference includes the specification of the plugin definitions for Java plugin interfaces, entity types,
typelist types, and other types available from Java.
The Reference contents are static. The script that regenerates the Java API (gwb genJavaApi) does not regenerate
the Reference. Therefore, your own data model changes are not reflected in the Reference documentation. However,
your changes to entity types, typecodes, and new properties are available from Java code in your Java IDE.

Web service API reference documentation

On a running PolicyCenter server, you can get up-to-date WSDL from published services.
For WS-I web services, there is no built-in Javadoc-style generation. The exact method signatures and syntax vary
based on the language which the SOAP implementation that generates libraries from the WSDL.

See also

• “Getting WSDL from a running server” on page 54.

Gosu API reference

The Gosu API Reference is a browser-based listing of Gosu classes, methods, and data. The Reference is particularly
valuable for programmers implementing Gosu plugins.
The Gosu API Reference can be generated from the command line by using the gwb gosudoc tool.

Data Dictionary documentation

The PolicyCenter Data Dictionary provides documentation on classes that correspond to PolicyCenter data. You
must generate the Data Dictionary before using it.
The PolicyCenter Data Dictionary typically has more information about data-related objects than the various API
References have for the same class/entity. The Data Dictionary documents only classes corresponding to data
defined in the data model. It does not document any API functions or utility classes.
34 chapter 1: Integration overview
 Guidewire PolicyCenter 9.0.6 Integration Guide

Regenerating integration libraries and WSDL

You must regenerate the Java API libraries and SOAP WSDL after you make certain changes to the product
configuration. Regenerate these files in the following situations.
• After you install a new PolicyCenter release.
• After you make changes to the PolicyCenter data model, such as data model extensions, typelists, field
validators, and abstract data types.
As you work on both configuration and integration tasks, you may need to regenerate the Java API libraries and
SOAP WSDL frequently. However, if you make significant configuration changes and then work on integration at a
later stage, wait until you need the APIs updated before regenerating PolicyCenter files.

Regenerating the Java API libraries

For Java development, generate the Java entity libraries with the following command.

gwb genJavaApi

As part of its normal behavior, the script displays some warnings and errors. Note that the Java API libraries are
regenerated, but the command does not regenerate the static Java API Reference documentation.
The location for the Java generated libraries is:

PolicyCenter/java-api/lib

WS‐I web service regeneration of WSDL for local GUnit tests

For web service development, you can write unit tests that call web services on the same computer. Generate WSDL
for testing only using the following command.

gwb genWsiLocal

As part of its normal behavior, the script displays some warnings and errors.
The location for WS-I web service WSDL that you can use for writing test classes is:

PolicyCenter/modules/configuration/gsrc/wsi/local/

What are required files for integration programmers?

Depending on what kind of integrations you require, there are special files you must use. For example, libraries to
compile your Java code against, to import in a project, or to use in other ways.
There are several types of integration files.
• Web services – Some files represent files you can use with SOAP API client code.
• Plugin interfaces – Some files represent plugin interfaces for your code to respond to requests from PolicyCenter
to calculate a value or perform a task.
• Java API libraries – Some files represent entities, which are PolicyCenter objects defined in the data model with
built-in properties and can also have data model extension properties. For example, Policy and Address are
examples of Guidewire entities. To access entity data and methods from Java, you need to use Java API libraries.
In all cases, PolicyCenter entities such as Policy contain data properties that can be manipulated either directly or
from some contexts using getters and setters (get... and set... methods).
Depending on the type of integration point, there may be additional methods available on the objects. These
additional domain methods often contain valuable functionality.
Integration overview 35
Guidewire PolicyCenter 9.0.6 Integration Guide

Entity access Description Entities Necessa‐

ry libra‐
ries
Gosu plugin im‐ Plugin interface defined Full entity instances None
plementation in Gosu.
Java plugin im‐ Java code that accesses Full entity instances Java API
plementation, in‐ an entity associated libraries
cluding optional with a plugin interface
OSGi support parameter or return
value.
Java class called Java code called from Full entity instances Java API
from Gosu Gosu that accesses an libraries
entity passed as a pa‐
rameter from Gosu, or
a return result to be
passed back to Gosu.
Web services WS‐I web services No support for entity types as arguments or return values. n/a
Instead, create your own data transfer objects (DTOs) as one of the fol‐
lowing:
• Gosu class instances that contain only the properties required for
each integration point. You also need to declare the class final
and add the annotation gw.xml.ws.annotation.WsiExportable.
• XML objects with structure defined in XSD files.
• XML objects with structure defined with the GX modeler. The GX
modeler is a tool to generate an XML model with only the desired
subset of properties for each entity for each integration point.

Public IDs and integration code

PolicyCenter creates its own unique ID for every entity in the system after it fully loads in the PolicyCenter system.
However, this internal ID cannot be known to an external system while the external system prepares its data.
Consequently, if you get or set PolicyCenter information, use unique public ID values to identify an entity from
external systems connecting to a Guidewire application.
Your external systems can create this public ID based on its own internal unique identifier, based on an incrementing
counter, or based on any system that can guarantee unique IDs. Each entity type must have unique public IDs within
its class. For instance, two different Address objects cannot have the same public ID.
However, a policy and a policy revision may share the same public ID because they are different entities.
If loading two related objects, the incoming request must tell PolicyCenter that they are related. However, the web
service client does not know the internal PolicyCenter IDs as it prepares its request. Creating your own public IDs
guarantees the web service client can explain all relationships between objects. This is true particularly if entities
have complex relationships or if some of the objects already exist in the database.
Additionally, an external system can tell PolicyCenter about changes to an object even though the external system
might not know the internal ID that PolicyCenter assigned to it. For example, if the external system wants to change
a contact’s phone number, the external system only needs to specify the public ID of the contact record.
PolicyCenter allows most objects associated with data to be tagged with a public ID. Specifically, all objects in the
Data Dictionary that show the keyable attribute contain a public ID property. If your API client code does not need
particular public IDs, let PolicyCenter generate public IDs by leaving the property blank. However, other non-API
import mechanisms require you to define an explicit public ID, for instance database table record import.
If you choose not to define the public ID property explicitly during initial API import, later you can query
PolicyCenter with other information. For example, you could pass a contact person’s full name or taxpayer ID if you
need to find its entity programmatically.
You can specify a new public ID for an object. From Gosu, set the PublicID property.
36 chapter 1: Integration overview
 Guidewire PolicyCenter 9.0.6 Integration Guide

Creating your own public IDs

Suppose a company called ABC has two external systems, each of which contains a record with an internal ID
of 2224. Each system generates public ID by using the format "{company}:{system}:{recordID}" to create
unique public ID strings such as "abc:s1:2224" and "abc:s2:2224".
To request PolicyCenter automatically create a public ID for you rather than defining it explicitly, set the public ID
to the empty string or to null. If a new entity’s public ID is blank or null, PolicyCenter generates a public ID. The
ID is a two-character ID, followed by a colon, followed by a server-created number. For example, "pc:1234".
Guidewire reserves for itself all public IDs that start with a two-character ID and then a colon.
Public IDs that you create must never conflict with PolicyCenter-created public IDs. If your external system
generates public IDs, you must use a naming convention that prevents conflict with Guidewire-reserved IDs and
public IDs created by other external systems.
The prefix for auto-created public IDs is configurable using the PublicIDPrefix configuration parameter. If you
change this setting, all explicitly-assigned public IDs must not conflict with the namespace of that prefix.
The maximum public ID length is 64 characters.
Important – Integration code must never set a public IDs to a String that starts with a two-character ID and then a
colon. Guidewire strictly reserves all such IDs. If you use the PublicIDPrefix configuration parameter, integration
code that sets explicit public IDs also must not conflict with that namespace. Additionally, plan your public ID
naming to support large (long) record numbers. Your system must support a significant number of records over time
and stay within the public ID length limit.

Guidewire internal methods

Some code packages contain Guidewire internal methods that are reserved for Guidewire use only. Gosu code
written to configure PolicyCenter must never call an internal method for any reason. Future releases of PolicyCenter
can change or remove an internal method without notification.
The following packages contain Guidewire internal methods.
• All packages in com.guidewire.*
• Any package whose name or location includes the word internal
Gosu configuration code can safely call methods defined in any gw.* package (except for those packages whose
name or location includes the word internal).

Integration overview 37
Guidewire PolicyCenter 9.0.6 Integration Guide

38 chapter 1: Integration overview

part 2

Web Services
Guidewire PolicyCenter 9.0.6 Integration Guide
chapter 2

Web services introduction

You can write web service APIs in Gosu and access them from remote systems using the standard web services
protocol SOAP, the standard Simple Object Access Protocol. Web services provide a language-neutral, platform-
neutral mechanism for invoking actions or requesting data from other applications across a network. The SOAP
protocol defines request/response mechanisms for translating a function call and its response into XML-based
messages, typically across the standard HTTP protocol. PolicyCenter publishes its own built-in web service APIs
that you can use.

What are web services?

Web services define request-and-response APIs that let you call an API on a remote computer using an abstracted
well-defined interface. A data format called the Web Service Description Language (WSDL) describes available
web services that other systems can call using the SOAP protocol. Many languages and third-party packages provide
bindings implementations of WSDL and SOAP, including Gosu (built into PolicyCenter), Java, Perl, and other
languages.

Publish or consume web services from Gosu

Gosu natively supports web services in two ways.
• Publish your Gosu code as new web service APIs – Write Gosu code that external systems call as a web
service using the SOAP protocol. Simply add a single line of code before the definition of the implementation
Gosu class. The application parses the class methods and generates a web service definition (WSDL) and
publishes the web service to external systems.
• Call web service APIs that external applications publish from your Gosu code – Write Gosu code that
imports and calls web service APIs published by external systems. Gosu parses the WSDL for the service. Gosu
uses the WSDL to create Gosu types that enable you to call the remote API. You can call methods on the API and
access types from the WSDL, all with a natural Gosu syntax.
Warning – Your web service definition in the WSDL defines a strict programmatic interface to external systems
that use your service. The WSDL encodes the structure of all parameters and return values. After moving code
into production, be careful not to change the WSDL. For example, do not modify data transfer objects (DTOs)
after going into production or widely distributing the WSDL in a user acceptance testing (UAT) environment.

Web services introduction 41

Guidewire PolicyCenter 9.0.6 Integration Guide

What happens during a web service call?

For all types of web services, PolicyCenter converts the server’s local Gosu objects to and from the flattened text-
based format that the SOAP protocol requires. These processes are called serialization and deserialization.
• Suppose you write a web service in Gosu and publish it from PolicyCenter and call it from a remote system.
Gosu must deserialize the text-based request into a local object that your Gosu code can access. If one of your
web service methods returns a result, PolicyCenter serializes that local in-memory Gosu result object.
PolicyCenter serializes it into a text-based reply to the remote system.
• Suppose you use Gosu to call a web service hosted by an external system. Before calling the API, Gosu
automatically serializes any API parameters to convert a local object into a flattened form to send to the API. If
the remote API returns a result, PolicyCenter deserializes the response into local Gosu objects for your code to
examine.
Writing your own custom web service for each integration point is the best approach for maximum performance and
maintainability. Guidewire strongly encourages you to write as many web services as necessary to elegantly provide
APIs for each integration point.
For example, write new web services to communicate with a check printing service, a legacy financials system,
reporting service, or document management system. External systems can query PolicyCenter to calculate values,
trigger actions, or to change data within the PolicyCenter database.
Publishing a web service can be as simple as adding one special line of code called an annotation immediately
before your Gosu class.
For consuming a web service, Gosu creates local objects in memory that represent the remote API. Gosu creates
types for every object in the WSDL, and you can create these objects or manipulate properties on them.

Reference of all base configuration web services

The following table lists all base configuration web services.

Web Service Name Description

Job‐related web services
CancellationAPI Starts a cancellation job or rescinds a cancellation that has not completed. See “Pol‐
icy cancellation and reinstatement web services” on page 116.
JobAPI Adds an activity to a job. See “Job web services” on page 116.
PolicyChangeAPI Starts a policy change job. See “Policy change web services” on page 125.
PolicyRenewalAPI Starts a renewal job. See “Policy renewal web services” on page 126.
ReinstatementAPI Starts a reinstatement job for a policy that has been canceled. See “Policy cancella‐
tion and reinstatement web services” on page 116.
SubmissionAPI Starts a submission job. See “Submission web services” on page 119.
Other application web services
AccountAPI Performs various actions on an account, such as adding a note or a document. See
“Account web services” on page 114.
AddressAPI Notifies PolicyCenter of updates to addresses from an external contact system. See
“Address APIs” on page 542.
ArchiveAPI Manipulates archiving from external systems. See “Archiving web services” on page
128.
CCPolicySearchIntegration Retrieves policy summaries for claim systems such as ClaimCenter. If you configure
ClaimCenter to connect to PolicyCenter, ClaimCenter uses this web service automat‐
ically. See “Policy search web service for claim system integration” on page 451.

42 chapter 2: Web services introduction

 Guidewire PolicyCenter 9.0.6 Integration Guide

Web Service Name Description

ClaimToPolicySystemNotificationAPI Notifies PolicyCenter about large losses on a claim. If you configure ClaimCenter to
connect to PolicyCenter, ClaimCenter uses this web service automatically. See “Poli‐
cy system notifications” on page 450.
ContactAPI Notifies PolicyCenter of changes to contacts, including merging of contacts and
merging of contact addresses. See “Contact web service APIs” on page 537.
ImportPolicyAPI Adds an activity to a policy. See “Import policy web services” on page 125.
PolicyAPI Adds an activity to a policy. See “Policy web services” on page 122.
PolicyEarnedPremiumAPI Calculates earned premiums for a policy number as of a specific date. See “Policy
earned premium web services” on page 124.
ProductModelAPI Modifies the product model on a running development (non‐production) server.
See “Product model web services” on page 120.
PolicyLocationSearchAPI Retrieves a list of policy location summaries within a rectangular geographic bound‐
ing box. See “Policy location search API” on page 465.
PolicyPeriodAPI Performs various actions on a policy period, such as adding a note or a document.
See “Policy period web services” on page 124.
PolicySearchAPI Retrieves the public ID of a policy period based on a policy number and a date. See
“Policy search web service for claim system integration” on page 451.
ProducerAPI Performs various actions on producers, agencies, and branches. See “Producer web
services” on page 120.
ProductModelAPI Modifies the Product Model on a development (non‐production) server. See “Prod‐
uct model web services” on page 120.
RICoverageAPI Finds reinsurance risk information for use by an external system. This web service
requires Guidewire Reinsurance Management, which you license separately from
PolicyCenter. See “Reinsurance coverage web service” on page 415.
General web services
DataChangeAPI Tool for rare cases of mission‐critical data updates on running production systems.
See the System Administration Guide for more information.
ImportTools Imports administrative data from an XML file. You must use this only with adminis‐
trative database tables (entities such as User). This system does not perform com‐
plete data validation tests on any other type of imported data. See “Importing ad‐
ministrative data” on page 97.
LoginAPI The WS‐I web service LoginAPI is not used for authentication in typical use. It is
only used to test authentication or force a server session for logging. For details,
see “Login authentication confirmation” on page 62.
MaintenanceToolsAPI Starts and manages various background processes. The methods of this web service
are available only when the server run level is maintenance or higher. See “Mainte‐
nance tools web service” on page 98.
MessagingToolsAPI Manages the messaging system remotely for message acknowledgments error re‐
covery. The methods of this web service are available only when the server run lev‐
el is multiuser. See “Messaging tools web service” on page 347.
ProfilerAPI Sends information to the built‐in system profiler. See “Profiling web service” on
page 103.
SystemToolsAPI Performs various actions related to server run levels, schema and database consis‐
tency, module consistency, and server and schema versions. The methods of this
web service are available regardless of the server run level. See “System tools web
service” on page 105.

Web services introduction 43

Guidewire PolicyCenter 9.0.6 Integration Guide

Web Service Name Description

TemplateToolsAPI Lists and validates Gosu templates available on the server. See “Template web serv‐
ice” on page 109.
TableImportAPI Loads geographic zone data from the staging table into the operational table. In
PolicyCenter, this tool supports zone data only, not other data such as policy data or
administrative data. Key methods of this web service are available only when the
server run level is maintenance. See “Table import web service” on page 107.
TypelistToolsAPI Retrieves aliases for PolicyCenter typecodes in external systems. See “Mapping
typecodes and external system codes” on page 100.
WorkflowAPI Performs various actions on a workflow, such as suspending and resuming work‐
flows and invoking workflow triggers. See “Workflow web service” on page 110.
ZoneImportAPI Imports geographic zone data from a comma separated value (CSV) file into a stag‐
ing table, in preparation for loading zone data into the operational table. See “Zone
data import web service” on page 111.

44 chapter 2: Web services introduction

chapter 3

Publishing web services

You can write web service APIs in Gosu and access them from remote systems using the standard web services
protocol SOAP. The SOAP protocol defines request/response mechanisms for translating a function call and its
response into XML-based messages typically sent across computer networks over the standard HTTP protocol. Web
services provide a language-neutral and platform-neutral mechanism for invoking actions or requesting data from
another application across a network. PolicyCenter publishes its own built-in web service APIs that you can use.

Overview of web service publishing

Web services define request-and-response APIs that let you call an API on a remote computer, or even the current
computer, using an abstracted well-defined interface. A data format called the Web Service Description Language
(WSDL) describes available web services that other systems can call using the SOAP protocol. Many languages or
third-party packages provide bindings implementations of WSDL and SOAP, including Gosu (built into
PolicyCenter), Java, Perl, and other languages.
Gosu natively supports web services in two different ways.
• Publish your Gosu code as new web service APIs – Write Gosu code that external systems call as a web service
using the SOAP protocol. Add a single line of code before the definition of the implementation Gosu class. The
application parses the class methods and generates a web service definition (WSDL) and publishes the web
service to external systems.
Your web service definition in the WSDL defines a strict programmatic interface to external systems that use
your service. The WSDL encodes the structure of all parameters and return values. After moving code into
production, be careful not to change the WSDL. For example, do not modify data transfer objects (DTOs) after
going into production or widely distributing the WSDL in a user acceptance testing (UAT) environment.
• Call web service APIs that external applications publish from your Gosu code – Write Gosu code that imports
and calls web service APIs published by external systems. Gosu parses the WSDL for the service. Gosu uses the
WSDL to create Gosu types that enable you to call the remote API. You can call methods on the API and access
types from the WSDL, all with a natural Gosu syntax.
In both cases PolicyCenter converts the server’s local Gosu objects to and from the flattened text-based format
required by the SOAP protocol. This process is serialization and deserialization.
• Suppose you write a web service in Gosu and publish it from PolicyCenter and call it from a remote system.
Gosu must deserialize the text-based XML request into a local object that your Gosu code can access. If one of
your web service methods returns a value, PolicyCenter serializes that local in-memory Gosu object and
serializes it into a text-based XML reply for the remote system.
• Suppose you use Gosu to call a web service hosted by an external system. Before calling the API, Gosu
automatically serializes any API parameters to convert a local object into a flattened text-based XML format to
Publishing web services 45
Guidewire PolicyCenter 9.0.6 Integration Guide

send to the API. If the remote API returns a result, PolicyCenter deserializes the XML response into local Gosu
objects for your code to use.
Guidewire provides built-in web service APIs for common general tasks and tasks for business entities of
PolicyCenter. However, writing your own custom web service for each integration point is the best approach for
maximum performance and maintainability. Guidewire strongly encourages you to write as many web services as
necessary to elegantly provide APIs for each integration point.
For example, write new web services to communicate with a check printing service, a legacy financials system,
reporting service, or document management system. External systems can query PolicyCenter to calculate values,
trigger actions, or to change data within the PolicyCenter database.
Publishing a web service may be as simple as added one special line of code called an annotation immediately
before your Gosu class declaration.
Guidewire provides a Java language binding for published web services. Using these bindings, you can call the
published web services from Java program as easy as making a local method invocation. You can use other
programming languages if it has a SOAP implementation and can access the web service over the Internet. Because
Gosu and Java are the typical languages for web service client code, PolicyCenter documentation uses Gosu and
Java syntax and terminology to demonstrate APIs. If you write APIs to integrate two or more Guidewire
applications, you probably will write your web service code in Gosu using its native SOAP syntax rather than Java.

Data transfer objects

A web service can accept a Gosu object as an argument. It can also return a Gosu object. Such an object passed by a
web service between remote processes is often referred to as a data transfer object or DTO.
Most integration points need to transfer only a subset of an object's properties and object graph. Do not pass large
object graphs. Be aware of any objects that in edge cases might be very large in your deployed production system. If
you try to pass too much data, production systems can potentially experience memory problems. Design web
services to pass DTOs that contain only the properties needed by the integration point. If an integration point needs
only a record’s main contact name and phone number, for example, then create a DTO that contains only those
properties, plus the standard public ID property.
Web service arguments and return values can be of the following types.
• Gosu class – Such as a Gosu class that contains properties for a particular integration point
In order for a Gosu class to be used as a DTO, it must meet certain requirements. For example, the class must be
declared as final and it must specify the @WsiExportable annotation. Other requirements are described later in
this topic.

package example.wsi.myobjects

uses gw.xml.ws.annotation.WsiExportable

@WsiExportable
final class MyCheckPrintInfo {
var checkID : String
var checkRecipientDisplayName : String
}

• XSD types – For example, an XML object based on an XSD type

Store an XSD file in the Gosu source code tree and then reference the XSD types using the Gosu XML API.
Optionally, define a Guidewire GX model that contains the desired subset of properties from one or more entity
types. Then use the GX model to import or export XML data, as needed.
PolicyCenter generates a WSDL from the Gosu web service definitions that you create and their related DTO types.
In addition, PolicyCenter includes a variety of DTOs used by web services to integrate between individual
Guidewire applications. These DTOs define the contract between the applications and can be modified if you need
to expand the set of properties exchanged in an integration.

Requirements for a Gosu object used as a DTO

A web service can accept arguments and define return values that contain or reference instances of Gosu classes,
sometimes called Plain Old Gosu Objects (POGOs).
46 chapter 3: Publishing web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

However, the Gosu class must have the following qualities.

• The class must be declared as final.
• The class must specify the @gw.xml.ws.annotation.WsiExportable annotation. The annotation accepts an
optional String argument to specify a namespace.
• The class cannot define a property that has a getter or setter method of an XSD type.
• The class cannot define a method with an argument or return value of an XSD type.

Committing entity data to the database using a bundle

Guidewire applications use bundles to track changes to entity data.
No default bundle exists for a web service that changes and persists entity data. If your web service modifies entity
data, you must create your own bundle. To create a bundle, use the runWithNewBundle API.
A web service does not need to create a bundle if it only retrieves entity data and does not modify and persist it.

Web service publishing quick reference

The following table summarizes important qualities of web services published by Guidewire applications.

Feature Web service behavior

Basic publishing of a web service Add the annotation @WsiWebService to the implementation class, which must be a Gosu
class that does not inherit from any other class. This annotation supports one optional argu‐
ment for the web service namespace. See “Declaring the namespace for a web service” on
page 50. If you do not declare the namespace, Gosu uses the default namespace http://
example.com.

Does PolicyCenter automatically Yes. See “Getting WSDL from a running server” on page 54.
generate WSDL files from a run‐
ning server?
Does PolicyCenter automatically Yes. See “Generating WSDL” on page 54.
generate WSDL files locally if you
regenerate the SOAP API files?
Does PolicyCenter automatically No, but it is easy to generate with the Java built‐in utility wsimport. The documentation in‐
generate JAR files for Java SOAP cludes examples. See “Calling a PolicyCenter web service from Java” on page 56.
client code if you regenerate the
SOAP API files?
Can serialize Gosu class instan‐ Yes, but with certain requirements. See “Overview of web service publishing” on page 45.
ces, sometimes called POGOs:
Plain Old Gosu Objects?
Can web services serialize or de‐ No. To transfer entity data, create your own data transfer objects (DTOs) that contain only
serialize Guidewire entity instan‐ the data you need for the service. DTO objects can be either Gosu class instances or XML
ces? objects from XSD types. See in this table “Can serialize Gosu class instances”).
Can serialize a XSD‐based type Yes. Add the XSD to the source tree, run the code generation command in Studio, and write
Gosu using the XmlElement APIs. See “Using predefined XSD and WSDL” on page 65.
Can you use GX models to gen‐ Yes
erate XML types that can be ar‐
guments or return types?
Can web services serialize a GX Yes. The web services framework will generate matching XSD types in the WSDL.
model as an argument or return
type?
Can web services serialize a Java Generally speaking, no. Exceptions include Simple Java objects. Such objects include but are
object as an argument type or not limited to Date, Double, and String.
return type?

Publishing web services 47

Guidewire PolicyCenter 9.0.6 Integration Guide

Feature Web service behavior

Can web services serialize an Yes. See “Exposing typelists and enums as enumeration values and string values” on page
enumeration—typelist, Java 79
enum, or Gosu enum—as an
argument type or return type?
Automatically throw No. Declare the actual exceptions you want thrown. In general, this requirement reduces
SOAPException exceptions? typical WSDL size.
To declare the exceptions a method can throw, use the @Throws annotation.

class MyClass{

@Throws(SOAPServerException,
"If communication error or any other SOAP problem occurs.")
public function myMethod() { ... }
}

Logging in to the server Each web service request embeds necessary authentication and security information in
each request. If you use Guidewire authentication, you must add the appropriate SOAP
headers before making the connection.
Package name of web services The package in which you put your web service implementation class defines the package
from the SOAP API client per‐ for the web service from the SOAP API client perspective. The biggest benefit from this
spective change is reducing the chance of namespace collisions in general. In addition, the web serv‐
ice namespace URL helps prevent namespace collisions. See “Declaring the namespace for a
web service” on page 50.
Calling a local version of the web Gosu creates types that use the original package name to avoid namespace collisions.
service from Gosu API references in the package wsi.local.ORIGINAL_PACKAGE_NAME
In production environments, if the operation is exposed only as a web service, instantiate
the web service implementation class directly and call the method. This technique avoids
having multiple transactions process the same action, which can result in possible race con‐
ditions, CDCEs (concurrent data change exceptions), or rollback issues.
For testing purposes only, the local files must be rebuilt by running the following command
from the PolicyCenter installation directory.

gwb genWsiLocal

Create SOAP 1.2 custom fault Custom fault subcodes are not supported in PolicyCenter. However, configuration code can
subcodes throw a gw.xml.ws.WsdlFault exception, which includes properties that can be populated
and subsequently retrieved.

setActorRole(String actorRole) // SOAP 1.1 actor role

getActorRole() : String

setCode(FaultCode code)
getCode() : FaultCode

setCodeQName(QName codeQName)
getCodeQName() : QName

setDetail(XmlElement detail)
getDetail() : XmlElement

The properties returned by the WsdlFault will not be documented in the generated WSDL.

Web service publishing annotation reference

The following table lists annotations related to web service declaration and configuration.

48 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

Annotation Description
@WsiAdditionalSchemas Expose additional schemas to web service clients in the WSDL.Use this to pro‐
vide references to schemas that might be required but are not automatically in‐
cluded.
“Reference additional schemas in your published WSDL” on page 69
@WsiAvailability Set the minimum server run level for this service
“Specifying minimum run level for a web service” on page 51
@WsiCheckDuplicateExternalTransaction Detect duplicate operations from external systems that change data
“Checking for duplicate external transaction IDs” on page 78
@WsiExportable Add this annotation on a Gosu class to indicate that it supports serialization
with web services. The annotation accepts an optional String argument that
specifies a namespace.
“Overview of web service publishing” on page 45
@WsiExposeEnumAsString Instead of exposing typelist types and enumerations as enumerations in the
WSDL, you can expose them as String values.
“Exposing typelists and enums as enumeration values and string values” on
page 79
@WsiInvocationHandler Perform advanced implementation of a web service that conforms to externally‐
defined standard WSDL. This is for unusual situations only. This approach limits
protection against some types of common errors.
“Using predefined XSD and WSDL” on page 65
@WsiParseOptions Add validation of incoming requests using additional schemas in addition to the
automatically generated schemas.
“Validate requests using additional schemas as parse options” on page 69
@WsiPermissions Set the required permissions for this service
“Specifying required permissions for a web service” on page 51
@WsiReduceDBConnections A database query triggers the retrieval of a database connection from the con‐
nection pool. The management of database connections is handled by the pool
The @WsiReduceDBConnections annotation configures the web service opera‐
tions to retrieve and re‐use a single database connection from the pool. With‐
out the annotation, a connection is retrieved from and returned to the pool for
each query.
In most scenarios, the @WsiReduceDBConnections annotation is not needed. It
can result in connections becoming effectively locked, reducing the efficiency of
the connection pool and slowing web service execution.
The annotation can be used in special situations only. An example is when a sin‐
gle web service performs a very large number of database queries, where re‐
trieving and returning a pool connection for each query would cause excessive
thrashing.
@WsiRequestTransform Add transformations of incoming or outgoing data as a byte stream. Typically
@WsiResponseTransform you would use this to add advanced layers of authentication or encryption. Con‐
trast to the annotations in the next row, which operate on XML elements.
“Data stream transformations” on page 73
@WsiRequestXmlTransform Add transformations of incoming or outgoing data as XML elements. Use this for
@WsiResponseXmlTransform transformations that do not require access to byte data. Contrast to the annota‐
tions in the previous row, which operate on a byte stream.
“Request or response XML structural transformations” on page 63
@WsiSchemaTransform Transform the generated schema that PolicyCenter publishes.
“Transforming a generated schema” on page 63
@WsiSerializationOptions Add serialization options for web service responses, for example supporting en‐
codings other than UTF‐8.
“Setting response serialization options, including encodings” on page 73

Publishing web services 49

Guidewire PolicyCenter 9.0.6 Integration Guide

Annotation Description
@WsiWebMethod The @WsiWebMethod annotation can perform two actions.
• Override the web service operation name to something other than the
default, which is the method name.
• Suppress a method from generating a web service operation even though
the method has public access.
“Overriding a web service method name or visibility” on page 51
@WsiWebService Declare a class as implementing a web service
“Publishing and configuring a web service” on page 50

Publishing and configuring a web service

To publish a web service, use the @WsiWebservice annotation on a class. Gosu publishes the class automatically
when the server runs. An example web service is implemented below.

package example
uses gw.xml.ws.annotation.WsiWebService

@WsiWebService
class HelloWorldAPI {

public function helloWorld() : String {

return "Hello!"
}
}

Choose your package declaration carefully. The package in which you put your web service implementation class
defines the package for the web service from the SOAP API client perspective.
Arguments and return values must be WS-I exportable. This includes simple types like String, as well as XSD
types and Gosu classes declared final and that have a special annotation. Arguments of array types are not
supported.

Declaring the namespace for a web service

Each web service is defined within a namespace, which is similar to a Gosu class or Java class within a package.
Specify the namespace as a URL in each web service declaration. The namespace is a String that looks like a
standard HTTP URL but represents a namespace for all objects in the service’s WSDL definition. The namespace is
not typically a URL for an actual downloadable resource. Instead it is an abstract identifier that disambiguates
objects in one service from objects in another service.
A typical namespace specifies your company and perhaps other meaningful disambiguating or grouping information
about the purpose of the service, possibly including a version number:
• "http://mycompany.com"
• "http://mycompany.com/xsds/messaging/v1"
You can specify the namespace for each web service by passing a namespace as a String argument to the
@WsiWebService annotation.

package example
uses gw.xml.ws.annotation.WsiWebService

@WsiWebService("http://mycompany.com")
class HelloWorldAPI {

public function helloWorld() : String {

return "Hello!"
}
}

You can omit the namespace declaration entirely and provide no arguments to the annotation. If you omit the
namespace declaration in the constructor, the default is "example.com".
50 chapter 3: Publishing web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

Most tools that create stub classes for web services use the namespace to generate a package namespace for related
types.

Specifying minimum run level for a web service

To set the minimum run level for the service, add the annotation @WsiAvailability and pass the run level at which
this web service is first usable. The choices include DAEMONS, MAINTENANCE, MULTIUSER, and STARTING. The default
is NODAEMONS.

package example

uses gw.xml.ws.annotation.WsiWebService
uses gw.xml.ws.annotation.

@WsiAvailability(MAINTENANCE)
@WsiWebService
class HelloWorldAPI {

public function helloWorld() : String {

return "Hello!"
}
}

Specifying required permissions for a web service

To add required permissions, add the annotation @WsiPermissions and pass an array of permission types
(SystemPermissionType[]). The default permission is SOAPADMIN. If you provide an explicit list of permissions,
you can choose to include SOAPADMIN explicitly or omit it. If you omit SOAPADMIN from the list of permissions, your
web service must not require SOAPADMIN permission. If you pass an empty list of permissions, your web service
must not require authentication at all. Web services for which authentication is not needed include ping-type
operations.
The only supported permission types are permissions that are role-based (static), rather than data-based (requires an
object). Use the Security Dictionary to make this determination. If the permission is role-based, you see the term
(static) after the permission name.
The following example uses no authentication for a simple service you might use for debugging.

package example

uses gw.xml.ws.annotation.WsiWebService
uses gw.xml.ws.annotation.WsiPermissions

@WsiPermissions({}) // A blank list means no authentication needed.

@WsiWebService

class HelloWorldAPI {

public function helloWorld() : String {

return "Hello!"
}
}

Overriding a web service method name or visibility

Web service method names must be unique. Duplicate method names, even with differing signatures, are not
supported.
You can override the names and visibility of individual web service methods in several ways.

Overriding web service method names

By default, the web service operation name for a method is the name of the method. You can override the name by
adding the @WsiWebMethod annotation immediately before the declaration for the method on the implementation
class. Pass a String value for the new name for the operation.
Publishing web services 51
Guidewire PolicyCenter 9.0.6 Integration Guide

@WsiWebMethod("newMethodName")
public function helloWorld() : String {
return "Hello!"
}

Hiding public web service methods

Gosu publishes one web service operation for each method marked as public. Public methods can be hidden by
specifying the @WsiWebMethod annotation and passing the value true. By default, public web service methods are
visible. The @WsiWebMethod annotation can hide a public method, but it cannot make a non-public method visible.

@WsiWebMethod(true)
public function helloWorld() : String {
return "Hello!"
}

Overriding method names and visibility with a single @WsiWebMethod annotation

You can combine both of these features of the @WsiWebMethod annotation by passing both arguments.

@WsiWebMethod("newMethodName", true)
public function helloWorld() : String {
return "Hello!"
}

Web service invocation context

In some cases your web service may need additional context for incoming or outgoing information. For example, to
get or set HTTP or SOAP headers. You can access this information in your implementation class by adding an
additional method argument to your class of type WsiInvocationContext. Make this new object the last argument
in the argument list.
Unlike typical method arguments on your implementation class, this method parameter does not become part of the
operation definition in the WSDL. Your web service code can use the WsiInvocationContext object to get or set
important information as needed.
The following table lists properties on WsiInvocationContext objects and whether each property is writable.

Property Description Reada‐ Writable

ble
Request Properties
HttpServletRequest A servlet request of type HttpServletRequest Yes No
MtomEnabled A boolean value that specifies whether to support sending MTOM at‐ Yes Yes
tachments to the web service client in any data returned from an API.
The W3C Message Transmission Optimization Mechanism (MTOM) is
a method of efficiently sending binary data to and from web services
as attachments outside the normal response body.
If MtomEnabled is true, PolicyCenter can send MTOM in results. Oth‐
erwise, MTOM is disabled. The default is false.
This property does not affect MTOM data sent to a published web
service. Incoming MTOM data is always supported.
This property does not affect MTOM support where Gosu is the client
to the web service request. See “MTOM attachments with Gosu as
web service client” on page 96.
RequestHttpHeaders Request headers of type HttpHeaders Yes No
RequestEnvelope Request envelope of type XmlElement Yes No
RequestSoapHeaders Request SOAP headers of type XmlElement Yes No

52 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

Property Description Reada‐ Writable

ble
Response Properties
ResponseHttpHeaders Response HTTP headers of type HttpHeaders Yes The property
value is read‐
only, but you
can modify the
object it refer‐
ences
ResponseSoapHeaders Response SOAP headers of type List<XmlElement> Yes The property
value is read‐
only, but you
can modify the
object it refer‐
ences
Output serialization
XmlSerializationOptions XML serialization options of type XmlSerializationOptions. Yes Yes

You can use these APIs to modify response headers from your web service and read request headers as needed.
For example, suppose you want to copy a specific request SOAP header XML object and copy to the response
SOAP header object. Create a private method to get a request SOAP header XML object.

private function getHeader(name : QName, context : WsiInvocationContext) : XmlElement {

for (h in context.RequestSoapHeaders.Children) {
if (h.QName.equals(name))
return h;
}
return null
}

From a web service operation method, declare the invocation context optional argument to your implementation
class. Then you can use code with the invocation context such as the following to get the incoming request header
and add it to the response headers.

function doWork(..., context : WsiInvocationContext) {

var rtnHeader = getHeader(TURNAROUND_HEADER_QNAME, context)
context.ResponseSoapHeaders.add(rtnHeader)

// do your main work of your web service operation

}

Web service class lifecycle and request local scoped variables

PolicyCenter does not instantiate the web service implementation class on server startup. PolicyCenter instantiates
the web service implementation class upon the first request from an external web service client for that specific
service. That one object instance is shared across all requests and sessions on that server for the lifetime of the
PolicyCenter application.
Because multiple threads may share this object, careful use of static and single-instance variables is required. To
ensure thread safety, use concurrency APIs at all times. For most Gosu coding, the standard Gosu concurrency
classes RequestVar and SessionVar in the gw.api.web package can be used. However, these classes do not work
in web service implementation classes.
Instead, for web service request-based data storage, use the concurrency class gw.xml.ws.WsiRequestLocal. If you
use this class to create a web service implementation class instance variable, only a single instance of the variable
will exist. The variable’s get and set methods manage access to the variable in a thread-safe way.

Publishing web services 53

Guidewire PolicyCenter 9.0.6 Integration Guide

If a web service encounters a concurrency issue, it returns a ConcurrentDataChangeException or

SoapRetryableException. The issue can usually be resolved by retrying the web service request.

Define a web request local scoped variable

Procedure
1. Decide what type of object you want to store in your request local variable. In your type declaration for the
variable, parameterize the WsiRequestLocal class with the type you want to store. For example, if you plan to
store a String object, declare your variable to have the type WsiRequestLocal<String>.
2. In your web service implementation class, define a private variable that uses the parameterized type.

private var _reqLocal = new WsiRequestLocal<String> ( )

3. In your implementation class, use the get and set methods to get or set the variable.

var loc = _reqLocal.get()

...
_reqLocal.set("the new value")

If you call get before calling set in the same web service request, the get method returns the value null.

Generating WSDL
Your web service definition in the WSDL defines a strict programmatic interface to external systems that use your
web service.
The WSDL encodes the structure of all parameters and return values. After moving code into production, be careful
not to change the WSDL. For example, do not modify data transfer objects (DTOs) after going into production or
widely distributing the WSDL in a user acceptance testing (UAT) environment.

Getting WSDL from a running server

Typically, you get the WSDL for a web service from a running server over the network. This approach encourages
all callers of the web services to use the most current WSDL. In contrast, generating the WSDL and copying the
files around risks callers of the web service using outdated WSDLs. You can get the most current WSDL for a web
service from any computer on your network that publishes the web service. In a production system, code that calls a
web service typically resides on computers that are separate from the computer that publishes the web service.
PolicyCenter publishes a web service WSDL at the following URL.

SERVER_URL/WEB_APP_NAME/ws/WEB_SERVICE_PACKAGE/WEB_SERVICE_CLASS_NAME?WSDL

A published WSDL may make references to schemas at the following URL.

SERVER_URL/WEB_APP_NAME/ws/SCHEMA_PACKAGE/SCHEMA_FILENAME

For example, PolicyCenter generates and publishes the WSDL for web service class
example.webservice.TestWsiService at the location on a server with web application name pc.

http://localhost:PORTNUM/pc/ws/example/webservice/TestWsiService?WSDL

WSDL and schema browser

If you publish web services from a Guidewire application, you can view the WSDL and a schema browser available
at the following URL.

SERVER_URL/WEB_APP_NAME/ws

54 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

For example:

http://localhost:8580/pc/ws

From there, you can browse for:

• Document/Literal Web Services
• Supporting Schemas
• Generated Schemas
• Supporting WSDL files

Example WSDL
The following example demonstrates how a simple Gosu web service translates to WSDL.This example uses the
following simple example web service.

package example

uses gw.xml.ws.annotation.WsiWebService

@WsiWebService
class HelloWorldAPI {

public function helloWorld() : String {

return "Hello!"
}
}

PolicyCenter publishes the WSDL for the HelloWorldAPI web service at this location.

http://localhost:PORTNUMBER/pc/ws/example/HelloWorldAPI?WSDL

PolicyCenter generates the following WSDL for the HelloWorldAPI web service.

<?xml version="1.0"?>
<!-- Generated WSDL for example.HelloWorldAPI web service -->
<wsdl:definitions targetNamespace="http://example.com/example/HelloWorldAPI"
name="HelloWorldAPI" xmlns="http://example.com/example/HelloWorldAPI"
xmlns:gw="http://guidewire.com/xsd" xmlns:soap11="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
<wsdl:types>
<xs:schema targetNamespace="http://example.com/example/HelloWorldAPI"
elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!-- helloWorld() : java.lang.String -->
<xs:element name="helloWorld">
<xs:complexType/>
</xs:element>
<xs:element name="helloWorldResponse">

<xs:complexType>
<xs:sequence>
<xs:element name="return" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</wsdl:types>
<wsdl:portType name="HelloWorldAPIPortType">

<wsdl:operation name="helloWorld">
<wsdl:input name="helloWorld" message="helloWorld"/>
<wsdl:output name="helloWorldResponse" message="helloWorldResponse"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="HelloWorldAPISoap12Binding" type="HelloWorldAPIPortType">
<soap12:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
<wsdl:operation name="helloWorld">
<soap12:operation style="document"/>

Publishing web services 55

Guidewire PolicyCenter 9.0.6 Integration Guide

<wsdl:input name="helloWorld">
<soap12:body use="literal"/>
</wsdl:input>
<wsdl:output name="helloWorldResponse">
<soap12:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:binding name="HelloWorldAPISoap11Binding" type="HelloWorldAPIPortType">

<soap11:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>

<wsdl:operation name="helloWorld">
<soap11:operation style="document"/>
<wsdl:input name="helloWorld">
<soap11:body use="literal"/>
</wsdl:input>
<wsdl:output name="helloWorldResponse">
<soap11:body use="literal"/>
</wsdl:output>

</wsdl:operation>
</wsdl:binding>
<wsdl:service name="HelloWorldAPI">
<wsdl:port name="HelloWorldAPISoap12Port" binding="HelloWorldAPISoap12Binding">
<soap12:address location="http://localhost:8180/pc/ws/example/HelloWorldAPI"/>
<gw:address location="${pc}/ws/example/HelloWorldAPI"/>
</wsdl:port>
<wsdl:port name="HelloWorldAPISoap11Port" binding="HelloWorldAPISoap11Binding">
<soap11:address location="http://localhost:8180/pc/ws/example/HelloWorldAPI"/>

<gw:address location="${pc}/ws/example/HelloWorldAPI"/>
</wsdl:port>
</wsdl:service>
<wsdl:message name="helloWorld">
<wsdl:part name="parameters" element="helloWorld"/>
</wsdl:message>
<wsdl:message name="helloWorldResponse">
<wsdl:part name="parameters" element="helloWorldResponse"/>
</wsdl:message>

</wsdl:definitions>

The preceding generated WSDL defines multiple ports for this web service. A port in the context of a web service is
unrelated to ports in the TCP/IP network transport protocol. Web service ports are alternative versions of a published
web service. The preceding WSDL defines a SOAP 1.1 version and a SOAP 1.2 version of the HellowWorldAPI
web service.

Calling a PolicyCenter web service from Java

For web services, there are no automatically generated libraries to generate stub classes for use in Java. You must
use your own procedures for converting WSDL for the web service into APIs in your preferred language. There are
several ways to create Java classes from the WSDL:
• The Java API for XML Web Services (JAX-WS) includes a tool called wsimport that generates Java-compatible
stubs from a WSDL file.
• The CXF open source tool.
• The Axis2 open source tool.

Calling web services using Java and wsimport

The Java API for XML Web Services (JAX-WS) includes a tool called wsimport that generates Java-compatible
stubs from a WSDL file. This documentation uses the wsimport tool and its output to demonstrate creating client
connections to the PolicyCenter web services.
The wsimport tool supports getting a WSDL file that is published over the Internet from a running application. The
following demonstrations use this method. The tool also supports using local WSDL files. Refer to the wsimport
documentation for details on that functionality.
56 chapter 3: Publishing web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

Generate Java classes that make SOAP client calls to a SOAP API
Procedure
1. Launch the server that publishes the web services.
2. On the computer from which you will run your SOAP client code, open a command prompt.
3. Change the working directory to a place on your local disk where you want to generate Java source files
and .class files.
4. Create the subdirectory of the current directory where you want to place the Java source files.
For example, you might choose the folder name src. Ensure that the subdirectory exists before you run the
wsimport tool in the next step. This topic calls this subdirectory SUBDIRECTORY_NAME.
5. Enter the following command:

wsimport WSDL_LOCATION_URL -s SUBDIRECTORY_NAME

If the SUBDIRECTORY_NAME directory does not already exist, the wsimport action fails with the error
directory not found.
For WSDL_LOCATION_URL, type the HTTP path to the WSDL. For example:

wsimport http://localhost:PORTNUMBER/pc/ws/example/HelloWorldAPI?WSDL -s src

6. The tool generates Java source files and compiled class files. Depending on what you are doing, you probably
need only the class files or the source files, but not both.
a. The .java files are in the SUBDIRECTORY_NAME subdirectory. To use them, add this directory to your Java
project’s class path, or copy the files to your Java project’s src folder.
The location of the files represents the hierarchical structure of the web service namespace in reverse
order, followed by the fully qualified name.
The namespace is a URL that each published web service specifies in its declaration. It represents a
namespace for all the objects in the WSDL. A typical namespace would specify your company domain
name and perhaps other meaningful disambiguating or grouping information about the purpose of the
service. For example, http://mycompany.com.
You can specify the namespace for each web service by passing a namespace as a String argument to the
@WsiWebService annotation. If you do not override the namespace when you declare the web service, the
default is http://example.com.
The path to the Java source file has the following structure.

CURRENT_DIRECTORY/SUBDIRECTORY_NAME/REVERSED_NAMESPACE/FULLY_QUALIFIED_NAME.java

For example, suppose your web service's fully qualified name is com.mycompany.HelloWorld and the
namespace is the default http://example.com. If you use the SUBDIRECTORY_NAME value src, the
wsimport tool generates the .java file at the following location:

CURRENT_DIRECTORY/src/com/example/com/mycompany/HelloWorld.java

b. To use the generated Java .class files, add the generated directory to your Java project’s class path, or
copy the files to your Java project’s src folder.
The compiled .class files are placed in a hierarchy by package name with the same basic naming
convention as the .java files but with no SUBDIRECTORY_NAME.

CURRENT_DIRECTORY/SUBDIRECTORY_NAME/REVERSED_NAMESPACE/FULLY_QUALIFIED_NAME

The wsimport tool generates the .class files at the following location:

CURRENT_DIRECTORY/com/example/com/mycompany/HelloWorld.class

Publishing web services 57

Guidewire PolicyCenter 9.0.6 Integration Guide

7. The next step depends on whether you want just the .class files to compile against, or whether you want to
use the generated Java files.
• To use the .java files, copy the SUBDIRECTORY_NAME subdirectory into your Java project’s src folder.
• To use the .class files, copy the files to your Java project’s src folder or add that directory to your
project’s class path.
8. Write Java SOAP API client code that compiles against these new generated classes.

Using the generated Java classes

To get a reference to the API itself, access the WSDL port (the service type) with the following syntax.

new API_INTERFACE_NAME().getAPI_INTERFACE_NAMESoap11Port();

For example, for the API interface name HelloWorldAPI, the Java code looks like the following statement.

HelloWorldAPIPortType port = new HelloWorldAPI().getHelloWorldAPISoap11Port();

Once you have that port reference, you can call your web service API methods directly on it.
You can publish a web service that does not require authentication by overriding the set of permissions necessary for
the web service. See “Specifying required permissions for a web service” on page 51. The following is a simple
example to show calling the web service without worrying about the authentication-specific code.

import com.example.example.helloworldapi.HelloWorldAPI;
import com.example.example.helloworldapi.HelloWorldAPIPortType;

public class WsiTestNoAuth {

public static void main(String[] args) throws Exception {

// Get a reference to the SOAP 1.1 port for this web service
HelloWorldAPIPortType port = new HelloWorldAPI().getHelloWorldAPISoap11Port();

// Call API methods on the web service

String res = port.helloWorld();

// Print result
System.out.println("Web service result = " + res);
}
}

Adding HTTP basic authentication in Java

In previous topics the examples showed how to connect to a service without authentication. The following code
shows how to add HTTP Basic authentication to your client request. HTTP Basic authentication is the easiest type of
authentication to code to connect to a PolicyCenter web service.

import com.example.example.helloworldapi.HelloWorldAPI;
import com.example.example.helloworldapi.HelloWorldAPIPortType;
import com.sun.xml.internal.ws.api.message.Headers;
import import javax.xml.ws.BindingProvider;
import org.w3c.dom.Document;
import org.w3c.dom.Element;

import javax.xml.namespace.QName;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.ws.BindingProvider;
import java.util.Map;

public class WsiTest02 {

public static void main(String[] args) throws Exception {

System.out.println("Starting the web service client test...");

// get a reference to the SOAP 1.1 port for this web service

58 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

HelloWorldAPIPortType port = new HelloWorldAPI().getHelloWorldAPISoap11Port();

// cast to BindingProvider so the following lines are easier to understand

BindingProvider bp = (BindingProvider) port;

// "HTTP Basic" authentication

Map<String, Object> requestContext = bp.getRequestContext();
requestContext.put(BindingProvider.USERNAME_PROPERTY, "su");
requestContext.put(BindingProvider.PASSWORD_PROPERTY, "gw");

System.out.println("Calling the service now...");

String res = port.helloWorld();
System.out.println("Web service result = " + res);
}
}

Adding SOAP header authentication in Java

Although HTTP authentication is the easiest to code for most integration programmers, PolicyCenter also supports
optionally authenticating web services using custom SOAP headers.
For Guidewire applications, the structure of the required SOAP header contains the following elements.
• An <authentication> element with the namespace http://guidewire.com/ws/soapheaders.
That element contains two elements.
• <username> – Contains the username text
• <password> – Contains the password text
This SOAP header authentication option is also known as Guidewire authentication.
The Guidewire authentication XML element looks like the following.

<?xml version="1.0" encoding="UTF-16"?>

<authentication xmlns="http://guidewire.com/ws/soapheaders"><username>su</username><password>gw
</password></authentication>

The following code shows how to use Java client code to access a web service with the fully-qualified name
example.helloworldapi.HelloWorld using a custom SOAP header.
After authenticating, the example calls the helloWorld SOAP API method.

import com.example.example.helloworldapi.HelloWorldAPI;
import com.example.example.helloworldapi.HelloWorldAPI;
import com.example.example.helloworldapi.HelloWorldAPIPortType;
import com.sun.org.apache.xml.internal.serialize.DOMSerializerImpl;
import com.sun.xml.internal.messaging.saaj.soap.ver1_1.Header1_1Impl;
import com.sun.xml.internal.messaging.saaj.soap.ver1_1.HeaderElement1_1Impl;
import com.sun.xml.internal.ws.developer.WSBindingProvider;
import com.sun.xml.internal.ws.api.message.Headers;
import org.w3c.dom.Document;
import org.w3c.dom.Element;

import javax.xml.namespace.QName;
import javax.xml.parsers.DocumentBuilderFactory;

public class WsiTest01 {

private static final QName AUTH = new QName("http://guidewire.com/ws/soapheaders",

"authentication");
private static final QName USERNAME = new QName("http://guidewire.com/ws/soapheaders", "username");
private static final QName PASSWORD = new QName("http://guidewire.com/ws/soapheaders", "password");

public static void main(String[] args) throws Exception {

System.out.println("Starting the web service client test...");

// Get a reference to the SOAP 1.1 port for this web service.
HelloWorldAPIPortType port = new HelloWorldAPI().getHelloWorldAPISoap11Port();

// cast to WSBindingProvider so the following lines are easier to understand

WSBindingProvider bp = (WSBindingProvider) port;

// Create XML for special SOAP headers for Guidewire authentication of a user & password.

Publishing web services 59

Guidewire PolicyCenter 9.0.6 Integration Guide

Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();

Element authElement = doc.createElementNS(AUTH.getNamespaceURI(), AUTH.getLocalPart());
Element usernameElement = doc.createElementNS(USERNAME.getNamespaceURI(),
USERNAME.getLocalPart());
Element passwordElement = doc.createElementNS(PASSWORD.getNamespaceURI(),
PASSWORD.getLocalPart());

// Set the username and password, which are content within the username and password elements.
usernameElement.setTextContent("su");
passwordElement.setTextContent("gw");

// Add the username and password elements to the "Authentication" element.

authElement.appendChild(usernameElement);
authElement.appendChild(passwordElement);

// Uncomment the following lines to see the XML for the authentication header.
DOMSerializerImpl ser = new DOMSerializerImpl();
System.out.println(ser.writeToString(authElement));

// Add our authentication element to the list of SOAP headers.

bp.setOutboundHeaders(Headers.create(authElement));

System.out.println("Calling the service now...");

String res = port.helloWorld();
System.out.println("Web service result = " + res);

}
}

Testing web services with local WSDL

For testing purposes only, you can call web services published from the same PolicyCenter server. To call a web
service on the same server, you must generate WSDL files into the class file hierarchy so Gosu can access the
service. This permits you to write unit tests that access the WSDL files over the SOAP protocol from Gosu.
Guidewire does not support calls to SOAP APIs published on the same server in a production system.

Generating WSDL for local web services

From the PolicyCenter installation directory, run the following command.

gwb genWsiLocal

PolicyCenter generates the WSDL in the wsi.local package, followed by the fully qualified name of the web
service.

wsi.local.FQNAME.wsdl

Using your class to test local web services

To use the class, prefix the text wsi.local. (with a final period) to the fully-qualified name of your API
implementation class.
For example, suppose the web service implementation class is:

mycompany.ws.v100.EchoAPI

The command gwb genWsiLocal generates the following WSDL file.

PolicyCenter/modules/configuration/gsrc/wsi/local/mycompany/ws/v100/EchoAPI.wsdl

Call this web service locally with the following line of code.

var api = new wsi.local.mycompany.ws.v100.EchoAPI()

60 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

If you change the code for the web service and the change potentially changes the WSDL, regenerate the WSDL.
PolicyCenter includes with WSDL for some local services in the default configuration. These WSDL files are in
Studio modules other than configuration. If PolicyCenter creates new local WSDL files from the
gwb genWsiLocal tool, it creates new files in the configuration module in the gsrc directory.
The wsi.local.* namespace exists only to call web services from GUnit unit tests. It is unsafe to write production
code that ever uses or calls wsi.local.* types.
To reduce the chance of accidental use of wsi.local.* types, Gosu prevents using these types in method signatures
of published web services.

Writing unit tests for your web service

It is good practice to design your web services to be testable. At the time you design your web service, think about
the kinds of data and commands your service handles. Consider your assumptions about the arguments to your web
service, what use cases your web service handles, and which use cases you want to test. Then, write a series of
GUnit tests that use the wsi.local.* namespace for your web service.
For example, you created the following web service.

package example

uses gw.xml.ws.annotation.WsiWebService

@WsiWebService("http://mycompany.com")
class HelloWorldAPI {

public function helloWorld() : String {

return "Hello!"
}
}

The following sample Gosu code is a GUnit test of the preceding HelloWorldAPI web service.

package example

uses gw.testharness.TestBase

class HelloWorldAPITest extends gw.testharness.TestBase {

construct() {

public function testMyAPI() {

var api = new wsi.local.example.helloworldapi.HelloWorldAPI()

api.Config.Guidewire.Authentication.Username = "su"
api.Config.Guidewire.Authentication.Password = "gw"
var res = api.helloWorld();

print("result is: " + res);

TestBase.assertEquals("Expected 'Hello!'", "Hello!", res)

print("we got to the end of the test without exceptions!")
}
}

For more thorough testing, test your web service from integration code on an external system. To ensure your web
service scales adequately, test your web service with as large a data set and as many objects as potentially exist in
your production system. To ensure the correctness of database transactions, test your web service to exercise all
bundle-related code.

Web services authentication plugin

To handle the name/password authentication for a user connecting to web services, PolicyCenter delegates the task
to the currently registered implementation of the WebservicesAuthenticationPlugin plugin interface. There must
Publishing web services 61
Guidewire PolicyCenter 9.0.6 Integration Guide

always be a registered version of this plugin, otherwise web services that require permissions cannot authenticate
successfully.
The WebservicesAuthenticationPlugin plugin interface supports web service connections only.

Web services authentication plugin implementation

To authenticate web service requests, a common practice is to create fictional PolicyCenter users whose express
purpose is to provide authentication. You can create fictional users by using the PolicyCenter user administration
feature. An external system making a web service request is authenticated by passing the fictional user’s name and
password in the service’s request headers.
The base configuration of PolicyCenter includes a registered implementation of the web service authentication
plugin. The class is called DefaultWebservicesAuthenticationPlugin. The class performs two main operations.
1. Scans HTTP request headers for authentication information.
2. Performs authentication against the local PolicyCenter users in the database. The class calls the registered
implementation of the AuthenticationServicePlugin plugin interface.
If you write your own implementation of the AuthenticationServicePlugin plugin interface, be aware of the
interaction with web service authentication. For example, you might want LDAP authentication for most users, but
for web service authentication, you would want to authenticate against the current PolicyCenter application
administrative data.
To authenticate only some user names to Guidewire application credentials, your AuthenticationServicePlugin
code must check the user name and compare it to a list of special web service user names. If the user name matches,
do not use LDAP, but instead authenticate with the local application administrative data. To do this authentication in
your AuthenticationServicePlugin implementation, use the following code.

_handler.verifyInternalCredentials(username, password)

See also
• “User authentication service plugin” on page 187

Writing an implementation of the web services authentication plugin

Most environments do not require writing a new implementation of the WebservicesAuthenticationPlugin
plugin interface. Typical changes to authentication logic are instead in your AuthenticationServicePlugin plugin
implementation.
You can change the default web services authentication behavior to get the credentials from different headers. You
can write your own WebservicesAuthenticationPlugin plugin implementation to implement custom logic.
The WebservicesAuthenticationPlugin interface has a single method that your implementation must implement
called authenticate. The authenticate method accepts a parameter of type
WebservicesAuthenticationContext. The object passed to the authenticate method contains authentication
information, such as the name and password.
The relevant properties in the WebservicesAuthenticationContext argument are listed below.
• HttpHeaders – HTTP headers of type gw.xml.ws.HttpHeaders. The argument includes a list of header names.
• RequestSOAPHeaders – The request SOAP headers as an XmlElement object.
If authentication succeeds, the authenticate method returns the relevant User object from the PolicyCenter
database. If authentication could not be attempted, such as if network problems existed, the method returns null.
Other causes of authentication failure throw a WsiAuthenticationException.

Login authentication confirmation

In typical cases, web service client code sets up authentication and calls desired web services, relying on catching
any exceptions if authentication fails. You do not need to call a specific web service as a precondition for login
authentication. In effect, authentication happens with each API call.
62 chapter 3: Publishing web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

However, if your web service client code wants to explicitly test specific authentication credentials, PolicyCenter
publishes the built-in Login web service. Call this web service’s login method, which takes a user name as a
String and a password as a String. If authentication fails, the API throws an exception.
If the authentication succeeds, that server creates a persistent server session for that user ID and returns the session
ID as a String. The session persists after the call completes. In contrast, a normal API call creates a server session
for that user ID but clears the session as soon as the API call completes.
If you call the login method, you must call the matching logout method to clear the session, passing the session ID
as an argument. If you were merely trying to confirm authentication, call logout immediately.
However, in some rare cases you might want to leave the session open for logging purposes to track the owner of
multiple API calls from one external system. After you complete your multiple API calls, finally call logout with
the original session ID.
If you fail to call logout, all application servers are configured to time out the session eventually.

Request or response XML structural transformations

For advanced layers of security, you probably want to use transformations that use the byte stream. However, there
are other situations where you might want to transform either the request or response XML data at the structural
level of manipulating XmlElement objects.
To transform the request envelope XML before processing, add the @WsiRequestXmlTransform annotation. To
transform the response envelope XML after generating it, add the @WsiResponseXmlTransform annotation.
Each annotation takes a single constructor argument which is a Gosu block. Pass a block that takes one argument,
which is the envelope. The block transforms the XML element in place using the Gosu XML APIs.
The envelope reference statically has the type XmlElement. However, at runtime the type is one of the following,
depending on whether SOAP 1.1 or SOAP 1.2 invoked the service.
• gw.xsd.w3c.soap11_envelope.Envelope
• gw.xsd.w3c.soap12_envelope.Envelop

See also
• “Data stream transformations” on page 73

Transforming a generated schema

PolicyCenter generates WSDL and XSDs for the web service based on the contents of your implementation class
and any of its configuration-related annotations. In typical cases, the generated files are appropriate for consuming
by any web service client code.
In rare cases, you might need to do some transformation. For example, if you want to specially mark certain fields as
required in the XSD itself, or to add other special comment or marker information.
You can do any arbitrary transformation on the schema by adding the @WsiSchemaTransform annotation. The one
argument to the annotation constructor is a block that does the transformation. The block takes two arguments.
• A reference to the entire WSDL XML. From Gosu, this object is an XmlElement object and strongly typed to
match the <definitions> element from the official WSDL XSD specification. From Gosu, this type is
gw.xsd.w3c.wsdl.Definitions.
• A reference to the main generated schema for the operations and its types. From Gosu this object is an
XmlElement object strongly typed to match the <schema> element from the official XSD metaschema. From,
Gosu this type is gw.xsd.w3c.xmlschema.Schema. There may be additional schemas in the WSDL that are
unrepresented by this parameter but are accessible through the WSDL parameter.
The following example modifies a schema to force a specific field to be required. In other words, it strictly prohibits
a null value. This example transformation finds a specific field and changes its XSD attribute MinOccurs to be 1
instead of 0.

@WsiSchemaTransform( \ wsdl, schema ->{

schema.Element.firstWhere( \ e ->e.Name == "myMethodSecondParameterIsRequired"

Publishing web services 63

Guidewire PolicyCenter 9.0.6 Integration Guide

).ComplexType.Sequence.Element[1].MinOccurs = 1
} )

You can also change the XML associated with the WSDL outside the schema element.

Converting a Gosu DTO to and from XML

When passing or returning a Gosu DTO in a web service, the object often needs to be converted to and from XML.
Converting a Gosu object to XML is referred to as marshalling. Conversely, converting XML back to a Gosu object
is called unmarshalling.

Convert a Gosu DTO to XML

The marshal method in the gw.xml.ws.WsiExportableUtil class converts a Gosu DTO to XML.

public static function marshal(element : XmlElement, obj : Object)

The method accepts two arguments.

• The element argument is used to store the generated XML.
• The obj argument is an instance of a Gosu class that meets the requirements of a DTO.
The method has no return value. The generated XML is stored in the element argument.
If a namespace was specified in the obj argument's @WsiExportable annotation then the same namespace is used to
contain the generated XML. Otherwise, a namespace is generated based on the object's package name.
For every public property with a non-null value in the obj argument, the conversion process defines an XML
element using the property's name. A public property with a null value is not converted and is not referenced in the
generated XML.
To convert the generated XML to a series of raw bytes, call the bytes method of the XmlElement object. To convert
the XML to a String, call the object's asUTFString method.
The following Gosu class definition meets the requirements of a DTO. Notice that a namespace is not specified in
the @WsiExportable annotation. The resulting XML will use a generated namespace based on the object's package
name.

package gw.examples

uses gw.xml.ws.annotation.WsiExportable

@WsiExportable
final class Car {
// Private fields defined with public Gosu property names in the recommended style
private var _color : String as Color
private var _model : String as Model

// Override toString() so it can be passed to the print() method for testing

override function toString() : String {
return "Car: Color=${_color} Model=${_model}"
}
}

The following code marshals an instance of the Gosu DTO class.

uses gw.xml.ws.WsiExportableUtil
uses gw.xml.XmlElement

// Instantiate a DTO object

var obj = new gw.examples.Car()
obj.Color = "Blue"
obj.Model = "234"

// Create an XML element

var xml = new XmlElement("root")

// Convert the DTO object to XML

64 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

WsiExportableUtil.marshal(xml, obj)

// Verify the resulting XML by converting it to a String

var xmlString = xml.asUTFString()
print(xmlString)

The example code prints the following output.

<?xml version="1.0"?>
<root xmlns:pogo="http://example.com/gw/examples">
<pogo:Color>Blue</pogo:Color>
<pogo:Model>234</pogo:Model>
</root>

The pogo: prefix is the short name for the namespace that was generated by the marshal method. If the
@WsiExportable annotation had specified an optional String namespace argument, that namespace would have
been used in the generated XML.

Convert XML to a Gosu DTO

The unmarshal method in the gw.xml.ws.WsiExportableUtil class converts XML back to a Gosu DTO object.

public static function unmarshal(element : XmlElement, IType : type) : Object

The method accepts two arguments.

• The element argument contains the XML to convert. The data must match the XML structure generated by the
marshal method for the specified Gosu object type.
• The type argument specifies the type of the Gosu object. The object must meet all the requirements of a DTO.
The method returns a base Object initialized using the converted XML values. The returned base object must be
downcast to the desired Gosu DTO type.
Alternatively, the desired Gosu DTO type can be specified when calling the unmarshal method by using Gosu
generics syntax. In this case, the method accepts only the element argument and returns a Gosu DTO object of the
desired type.
The following code converts XML to a Gosu DTO.

uses gw.xml.ws.WsiExportableUtil
uses gw.xml.XmlElement

// Initialize a new XmlElement by parsing XML specified in a String

var incomingXML : XmlElement
incomingXML = XmlElement.parse(xmlString)

// Convert the XmlElement into an instance of Gosu DTO class gw.examples.Car

// Use generics syntax to specify the desired Gosu DTO type
var car2 = unmarshal<gw.examples.Car>(incomingXML)

// Alternatively, specify the DTO type as an argument and downcast the return value
// var car2 = unmarshal(incomingXML, gw.examples.Car) as gw.examples.Car

// Verify the results by implicitly calling the object's toString() method

print(car2)

The example code prints the following output.

Car: Color=Blue Model=234

Using predefined XSD and WSDL

In typical PolicyCenter implementations, a web service is implemented by a Gosu class with each method
implementing one web service operation. PolicyCenter generates appropriate WSDL for all operations in the web
service. For any method arguments and return types, Gosu uses the class definition and the method signatures to
determine the structure of the WSDL.
Publishing web services 65
Guidewire PolicyCenter 9.0.6 Integration Guide

Some organizations require web service publishers to conform to predefined XML types defined in an XSD, or even
predefine WSDL. However, if you can use shared XSDs instead of a predefined WSDL, it is recommended to use
shared XSDs only.
You can write your web service to use a standard XSD to define individual types. For example, suppose a pre-
existing WSDL defines an XSD that defines 200 object types for method arguments and return types. You can add
the XSD to the source code tree in Studio and access all the XSD types directly from Gosu in a type-safe way. In
this case, the XSD types are acting as Data Transfer Objects (DTOs), a general term for a constrained data definition
specifically for web services. See the cross references at the end of this section.
If you are required to implement a preexisting service definition in a specific predefined WSDL, you can do so using
a feature called invocation handlers. By using a standardized WSDL, an organization can ensure that all related
systems conform to predefined specifications. The technical approach of invocation handlers can lead to more
complexity in your Gosu code, which can make it harder to catch problems at compile time.

Add an invocation handler for preexisting WSDL

Only use the @WsiInvocationHandler annotation if you need to write a web service that conforms to externally-
defined standard WSDL. Generally speaking, using this approach makes your code harder to read code and error
prone because mistakes are harder to catch at compile time. For example, it is harder to catch errors in return types
using this approach.
To implement preexisting WSDL, you define your web service very differently than for typical web service
implementation classes.
First, on your web service implementation class add the annotation @WsiInvocationHandler. As an argument to
this annotation, pass an invocation handler. An invocation handler has the following qualities.
• The invocation handler is an instance of a class that extends the type
gw.xml.ws.annotation.DefaultWsiInvocationHandler.
• Implement the invocation handler as an inner class inside your web service implementation class.
• The invocation handler class overrides the invoke method with the following signature.

override function invoke(requestElement : XmlElement, context : WsiInvocationContext) : XmlElement

• The invoke method does the actual dispatch work of the web service for all operations on the web service. Gosu
does not call any other methods on the web service implementation. Instead, the invocation handler handles all
operations that normally would be in various methods on a typical web service implementation class.
• Your invoke method can call its super implementation to trigger standard method calls for each operation based
on the name of the operation. Use this technique to run custom code before or after standard method invocation,
either for logging or special logic.
In the invoke method of your invocation handler, determine which operation to handle by checking the type of the
requestElement method parameter. For each operation, perform whatever logic makes sense for your web service.
Return an object of the appropriate type. Get the type of the return object from the XSD-based types created from
the WSDL.
Finally, for the WSDL for the service to generate successfully, add the preexisting WSDL to your web service using
the parse options annotation @WsiParseOptions. Pass the entire WSDL as the schema as described in that topic.

Example of an invocation handler for preexisting WSDL

In the following example, there is a WSDL file at the resource path in the source code tree at the path.

PolicyCenter/configuration/gsrc/ws/weather.wsdl

The schema for this file has the Gosu syntax: ws.weather.util.SchemaAccess. Its element types are available in
the Gosu type system as objects in the package ws.weather.elements.
The method signature of the invoke method returns an object of type XmlElement, the base class for all XML
elements. Be sure to carefully create the right subtype of XmlElement that appropriately corresponds to the return
type for every operation.
66 chapter 3: Publishing web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

The following example implements a web service that conforms to a preexisting WSDL and implements one of its
operations.

package gw.xml.ws

uses gw.xml.ws.annotation.WsiWebService
uses gw.xml.ws.annotation.WsiInvocationHandler
uses gw.xml.XmlElement
uses gw.xml.ws.annotation.WsiPermissions
uses gw.xml.ws.annotation.WsiAvailability
uses gw.xml.ws.annotation.WsiParseOptions
uses gw.xml.XmlParseOptions
uses java.lang.IllegalArgumentException

@WsiWebService("http://guidewire.com/px/ws/gw/xml/ws/WsiImplementExistingWsdlTestService")
@WsiPermissions({})
@WsiAvailability(NONE)
@WsiInvocationHandler(new WsiImplementExistingWsdlTestService.Handler())
@WsiParseOptions(new XmlParseOptions() { :AdditionalSchemas = { ws.weather.util.SchemaAccess } })

class WsiImplementExistingWsdlTestService {

// The following line declares an INNER CLASS within the outer class.
static class Handler extends DefaultWsiInvocationHandler {

// Here we implement the "weather" wsdl with our own GetCityForecastByZIP implementation.
override function invoke(requestElement : XmlElement, context : WsiInvocationContext)
: XmlElement {

// Check the operation name. If it is GetCityForecastByZIP, handle that operation.

if (requestElement typeis ws.weather.elements.GetCityForecastByZIP) {
var returnResult = new ws.weather.elements.GetCityForecastByZIPResponse() {

// The next line uses type inference to instantiate XML object of the correct type
// rather than specifying it explicitly.
:GetCityForecastByZIPResult = new() {
:Success = true,
:City = "Demo city name for ZIP ${requestElement.ZIP}"
}
return returnResult
}

// Check for additional requestElement values to handle additional operations.

if ...

else {
throw new IllegalArgumentException("Unrecognized element: " + requestElement)
}
}
}
}

First, the invoke method checks if the requested operation is the desired operation. An operation normally
corresponding to a method name on the web service, but in this approach one method handles all operations. In this
simple example, the invoke method handles only the operation in the WSDL called GetCityForecastByZip. If the
requested operation is GetCityForecastByZip, the code creates an instance of the
GetCityForecastByZIPResponse XML element.
Next, the example uses Gosu object creation initialization syntax to set properties on the element as appropriate.
Finally, the code returns that XML object to the caller as the result from the API call.
For additional context of the WSI request, use the context parameter to the invoke method. The context
parameter has type WsiInvocationContext, which contains properties such as servlet and request headers.

Invocation handler responsibilities

If you write an invocation handler for a web service, by default you are bypassing some important features.
• The application does not enabling profiling for method calls.
• The application does not check run levels even at the web service class level.
• The application does not check web service permissions, even at the web service class level.
Publishing web services 67
Guidewire PolicyCenter 9.0.6 Integration Guide

• The application does not check for duplicate external transaction IDs if present.
However, you can support all these things in your web service even when using an invocation handler, and in typical
cases it is best to do so.

Re‐enable bypassed features from an invocation handler

Procedure
1. In your web service implementation class, create separate methods for each web service operation. For each
method, for the one argument and the one return value, use an XmlElement object.

static function myMethod(req : XmlElement) : XmlElement

2. In your invocation handler's invoke method, determine which method to call based on the operation name.
3. Get a reference to the method info meta data for the method you want to call, using the # symbol to access
meta data of a feature (method or property).

var methodInfo = YourClassName#myMethod(XmlElement).MethodInfo

4. Before calling your method, get a reference to the WsiInvocationContext object that is a method argument
to invoke. Call its preExecute method, passing the requestElement and the method info metadata as
arguments. If you do not require checking method-specific annotations for run level or permissions, for the
method info metadata argument you can pass null.
The preExecute method does several things.
• Enables profiling for the method you are about to call if profiling is available and configured.
• Checks the SOAP headers looking for headers that set the locale. If found, sets the specified locale.
• Checks the SOAP headers for a unique transaction ID. This ID is intended to prevent duplicate requests. If
this transaction has already been processed successfully (a bundle was committed with the same ID),
preExecute throws an exception.
• If the method info argument is non-null, preExecute confirms the run level for this service, checking both
the class level @WsiAvailability annotation and any overrides for the method. As with standard
implementation classes, the method level annotation supersedes the class level annotation. If the run level is
not at the required level, preExecute throws an exception.
• If the method info argument is non-null, preExecute confirms user permissions for this service, checking
both the class level @WsiPermissions annotation and any overrides for the method. As with standard
implementation classes, the method level annotation supersedes the class level annotation. If the permissions
are not satisfied for the web service user, preExecute throws an exception.
5. Call your method from the invocation handler.

See also
• “Example of an invocation handler for preexisting WSDL” on page 66

Checking the method‐specific annotations for run level or permissions

To check the method-specific annotations for run level or permissions, one approach is to set up a map to store the
method information. The map key is the operation name. The map value is the method info metadata required by the
preExecute method.
The following example demonstrates this approach.

@WsiInvocationHandler( new WsiImplementExistingWsdlTestService.Handler())

class WsiImplementExistingWsdlTestService {

// The following line declares an INNER class within the outer class.
static class Handler extends DefaultWsiInvocationHandler {

var _map = { "myOperationName1" -> WsiImplementExistingWsdlTestService#methodA(XmlElement).MethodInfo,

"myOperationName2" -> WsiImplementExistingWsdlTestService#methodB(XmlElement).MethodInfo

68 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

override function invoke( requestElement : XmlElement, context : WsiInvocationContext )

: XmlElement {

// Get the operation name from the request element

var opName = requestElement.QName

// Get the local part (short name) from operation name, and get the method info for it
var method = _map.get(opName.LocalPart)

// Call preExecute to enable some features otherwise disabled in an invocation handler

context.preExecute(requestElement, method)

// Call your method using the method info and return its result
return method.CallHandler.handleCall(null, {requestElement}) as XmlElement
}
}

// After defining your invocation handler inner class, define the methods that do your work
// as separate static methods

// Example of overriding the default permissions

@WsiPermissions( { /* add a list of permissions here */} )
static function methodA(req : XmlElement) : XmlElement {
/* Do whatever you do, and return the result */
return null
}
static function methodB(req : XmlElement) : XmlElement {
/* do whatever you do, and return the result */
return null
}
}

This use is the only one supported for a WsiInvocationContext object’s preExecute method. Any use other than
calling it exactly once from within an invocation handler invoke method is unsupported.

Reference additional schemas in your published WSDL

If you need to expose additional schemas to the web service clients in the WSDL, you can use the
@WsiAdditionalSchemas annotation to do them. Use this to provide references to schemas that might be required
but are not automatically included.
For example, you might define an operation to take any object in a special situation, but actually accepts only one of
several different elements defined in other schemas. You might throw exceptions on any other types. By using this
annotation, the web service can add specific new schemas so web service client code can access them from the
WSDL for the service.
The annotation takes one argument of the type List<XmlSchemaAccess>, which means a list of schema access
objects. To get a reference to a schema access object, first put a XSD in your class hierarchy. Then from Gosu,
determine the fully-qualified name of the XSD based on where you put the XSD. Next, get the util property from
the schema, and on the result get the SchemaAccess property. To generate a list, surround one or more items with
curly braces and comma-separate the list.
For example, the following annotation adds the XSD that resides locally in the location
gw.xml.ws.wsimyschema.util:

@WsiAdditionalSchemas({ gw.xml.ws.wsimyschema.util.SchemaAccess })

Validate requests using additional schemas as parse options

You can validate incoming requests using additional schemas. To add an additional schema parse option, add the
@WsiParseOptions annotation to your web service implementation class.
Before proceeding, be sure you have a reference to the XSD-based schema. For an XSD or WSDL, get the
SchemaAccess property on the XSD type to get the schema reference. The argument for the annotation is an instance
Publishing web services 69
Guidewire PolicyCenter 9.0.6 Integration Guide

of type XmlParseOptions, which contains a property called AdditionalSchemas. That property must contain a list
of schemas.
To add a single schema, you can use the following compact syntax.

@WsiParseOptions(new XmlParseOptions() { :AdditionalSchemas = { YOUR_XSD_TYPE.util.SchemaAccess } })

For an XSD called WS.xsd in the source code file tree in the package com.abc, use the following syntax.

@WsiParseOptions(new XmlParseOptions() { :AdditionalSchemas = { com.abc.ws.util.SchemaAccess } })

To include an entire WSDL file as an XSD, use the same syntax. For example, if the file is WS.wsdl.

@WsiParseOptions(new XmlParseOptions() { :AdditionalSchemas = { com.abc.ws.util.SchemaAccess } })

Create an XML schema JAR file

After an integration project is finished and stable, the XML and XSD schema files that are created during WSDL
code generation will rarely change. Instead of having each build recreate these static files, the files can be created a
single time and stored in a Schema JAR file. The JAR file is then made available to all developers for general
access. Subsequent builds use the contents of the preprocessed JAR to reduce build times.
The Schema JAR file can contain the following types of resources.
• XML and XSD schema files created during WSDL code generation
• WSDL and XSD resources retrieved from remote servers by using Web Service Collections.
• Third-party XML and XSD schema files
The Schema JAR file cannot contain the XML and XSD schema files associated with a GX model.
The Schema JAR file can be created from the command line by running the gwb command with the genSchemaJar
task.

gwb genSchemaJar

Enable and configure the genSchemaJar task

By default, the genSchemaJar task is not enabled in the gwb command. Perform the following steps to enable the
task.
1. In the settings.gradle file located in the PolicyCenter installation directory, uncomment the line to include
the Schemas module.
2. In the build.gradle file located in the modules/configuration directory, uncomment the block of lines that
supports the Schema module.
3. In the gwxmlmodule.xml file located in the modules/configuration/res directory, uncomment the
dependency line that supports the genSchemaJar task.
The heap memory usage for the genSchemaJar task can be configured by setting the following values in the
gradle.properties file. The gradle.properties file is located in the PolicyCenter installation directory.
• custDistJavaCompileSchemaSourcesMinHeapSize – Minimum JVM heap size when performing the
genSchemaJar task. Default is eight gigabytes.
• custDistJavaCompileSchemaSourcesMaxHeapSize – Maximum JVM heap size when performing the
genSchemaJar task. Default is 16 gigabytes.

Create the schema JAR file

Perform the following steps to create the Schema JAR file.
1. Move the XML, XSD schema, and other resource files to include in the JAR file to a directory of your choice
in the modules/schemas/gsrc tree hierarchy.
70 chapter 3: Publishing web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

2. Create the Schema JAR file by running the gwb genSchemaJar task.

gwb genSchemaJar

The Schema JAR file is a dependency for building the Configuration module. The Configuration module is built by
running the gwb compile task.

gwb compile

Modify the schema JAR file contents

If any file stored in the Schema JAR file requires editing, the following workflow must be performed.
1. Before editing a file stored in the Schema JAR file, move the file back to its original location in the
Configuration module.
2. Recreate the Schema JAR file without the moved file.
3. Rebuild the Configuration module using the recreated Schema JAR file.
The file can now be edited.
When all changes are complete, the edited file can be restored to the JAR file by moving it back to the JAR
directory. Then rebuild the JAR file and Configuration module.

Unversioned schema JAR file usage

A possible scenario in which to use the Schema JAR file is to make it available in source control as an unversioned
file. In such a situation, integration developers who edit the JAR file’s contents also coordinate the JAR builds. They
check into source control the built JAR file and its individual component files. The non-integration developers never
build the JAR file themselves. Instead, they pull the latest JAR file from source control.

Versioned schema JAR file usage

In another scenario, the Schema JAR file is versioned and the version string is included in the JAR file name.
Integration developers are responsible for generating the JAR file and including the appropriate version ID in its
name. Non-integration developers retrieve the desired version of the JAR when they pull it from source control.
To add support in the build process for a versioned Schema JAR file, edit the following files.
• In the build.gradle file located in the PolicyCenter installation directory, append the following lines to the end
of the file.

ext {
xmlSchemaVersion = "1.0.0"
xmlSchemaJarFilename = "gw-xml-schemas-${xmlSchemaVersion}.jar".toString()
}

• In the build.gradle file located in the modules/schemas directory, append the following lines to the end of the
file.

afterEvaluate {
tasks.genSchemaJar.conventionMapping.archiveName = { xmlSchemaJarFilename }
}

• In the build.gradle file located in the modules/configuration directory, modify the genSchemaJar
dependencies block to reference the versioned filename, as shown below.

dependencies {
task (‘:modules:schemas:genSchemaJar’)
compile files(xmlSchemaJarFilename)
schemajars files(xmlSchemaJarFilename)
}

Whenever the JAR version changes, the Studio project must be regenerated to retrieve the new dependency for the
Configuration module. Regenerate the Studio project by running gwb idea on the command line. Alternatively,
regenerate the project in Studio by selecting Tools→Generate Project. Afterward, create the Schema JAR by running
Publishing web services 71
Guidewire PolicyCenter 9.0.6 Integration Guide

gwb genSchemaJar. Finally, build the application by either running gwb compile on the command line or selecting
Build→Rebuild Project in Studio.

Publish versioned schema JAR file to artifact repository

The Schema JAR file can be versioned and published to an artifact repository. Integration developers handle the
versioning and publishing operations. Non-integration developers retrieve from source control the latest files that
specify the required version. The next build pulls that version from the repository.
In the following example, support is added to the build process to create and publish a versioned Schema JAR file.
The version string is not included as part of the JAR file name. The JAR is published to a Maven repository.
• In the build.gradle file located in the PolicyCenter installation directory, append the following lines to the end
of the file.

ext {
xmlSchemaVersion = "1.0.0"
xmlSchemaGroupId = ‘com.myinsuranceco.cc’
xmlSchemaArtifactId = ‘schemas’
xmlSchemaJarFilename = ‘gw-xml-schemas.jar".toString()
}

• In the build.gradle file located in the modules/schemas directory, add the following line after the existing
apply plugin lines.

apply plugin: ‘maven-publish’

• In the same file, add the following lines after the closure of the tasks.compileSchemaSources.options.with
block. Replace the Maven repository url reference in the example with the URL of your own repository.

group = xmlSchemaGroupId
version = xmlSchemaVersion
artifacts {
archives genSchemaJar
}
publishing {
publications {
maven(MavenPublication) {
artifact genSchemaJar
}
}
repositories {
maven { url ‘http://nexus.myinsuranceco.com/content/repositories/releases’ }
}
}

• In the build.gradle file located in the modules/configuration directory, add the following lines after the
closure of the genSchemaJar dependencies block. Replace the Maven repository url reference in the example
with the URL of your own repository.

repositories {
maven { url ‘http://nexus.myinsuranceco.com/content/repositories/releases’ }
mavenLocal() // Used by integration developers only.
}

def xmlSchemasArtifact = "${xmlSchemaGroupId}:${xmlSchemaArtifactId}:${xmlSchemaVersion}".toString()

dependencies {
compile(xmlSchemasArtifact)
schemajars(xmlSchemasArtifact)
}

• If the referenced Maven url repository is not a local repository used for files under development, perform the
following step.
◦ Edit the gwb and gwb.bat files located in the PolicyCenter installation directory to remove all references to the
--offline argument.
To publish a new JAR version, perform the following steps.
72 chapter 3: Publishing web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

1. Regenerate the Studio project by running gwb idea.

2. Rebuild the Schema JAR file by running gwb genSchemaJar.
3. Publish the JAR to the local Maven repository by running gwb modules:schemas:publishToMavenLocal.
During development of the JAR, continue publishing it to this local repository.
4. Rebuild the application using the published JAR by running gwb compile.
5. When the Schema JAR is ready to be released, publish it to the main Maven repository by running
gwb modules:schemas:publish. Then check the build files into source control with the updated version
number.
Whenever a new JAR version is pulled from the repository, the Studio project must be regenerated to retrieve the
new dependency for the Configuration module. Regenerate the Studio project by running gwb idea on the command
line. Alternatively, regenerate the project in Studio by selecting Tools→Generate Project. Afterward, create the Schema
JAR by running gwb genSchemaJar. Finally, build the application by either running gwb compile on the command
line or selecting Build→Rebuild Project in Studio.

Setting response serialization options, including encodings

You can customize how PolicyCenter serializes the XML in the web service response to the client.
Incoming web service requests support any valid character encodings recognized by the Java Virtual Machine. The
web service client determines the encoding that it uses, not the server or its WSDL.
The most commonly customized serialization option is changing character encoding. Outgoing web service
responses by default use the UTF-8 character encoding. You might want to use another character encoding for your
service to improve Asian language support or other technical reasons.
To support additional serializations, add the @WsiSerializationOptions annotation to the web service
implementation class. As an argument to the annotation, pass a list of XmlSerializationOptions objects. The
XmlSerializationOptions class encapsulates various options for serializing XML, and that includes setting its
Encoding property to a character encoding of type java.nio.charset.Charset.
The easiest way to get the appropriate character set object is to use the Charset.forName(ENCODING_NAME) static
method. That method returns the desired static instance of the character set object.
For example, add the following the annotation immediately before the web service implementation class to specify
the Big5 Chinese character encoding.

@WsiSerializationOptions( new() { :Encoding = Charset.forName( "Big5" ) } )

Adding advanced security layers to a web service

For security options beyond simple HTTP authentication and Guidewire authentication, you can use an additional
set of APIs to implement additional layers of security. For example, you might want to add additional layers of
encryption, digital signatures, or other types of authentication or security. From the SOAP server side, you add
advanced security layers to outgoing requests by applying transformations to the data stream of the request.

Data stream transformations

Transformations on data streams
When calling a web service operation, the service's data stream can be transformed. For example, a request data
stream can be transformed to implement an encryption security layer.
A data stream can be transformed incrementally, a byte at a time, or all at once in its entirety. The type of
transformation can sometimes determine the manner in which a stream must be transformed. For example, a digital
signature authentication layer must transform an entire request data stream at one time.
Multiple types of transformations can be applied to a request data stream to add multiple security layers to a web
service. The order in which the transformations are performed can be important. For example, an encryption
Publishing web services 73
Guidewire PolicyCenter 9.0.6 Integration Guide

transformation followed by a digital signature transformation produces a different request data stream than if the
same transformations are performed in the opposite order.
The following example performs a simple search-and-replace operation on a request data stream. An encryption
operation could follow a similar process.

uses gw.util.StreamUtil

class sampleRequestTransform {

function transReplace_async() : String {

// Create "doubled" string "XX"
var async = API.async_doubleString("X")

// Define Gosu block to perform transformation on input stream

async.RequestTransform = \ inputStream -> {
var bytes = StreamUtil.getContent(inputStream)
var content = StreamUtil.toString(bytes)
print("Input stream was: " + content)

// Perform replace transformation (or encryption, as desired)

content = content.replace("X", "Y") // "XX -> "YY"
return StreamUtil.getStringInputStream(content)
}

// Call the transformation block and return the result

return async.get()
}
}

See also
• If the desired transformation operates more naturally on XML elements than on a byte stream, consider using the
APIs in “Request or response XML structural transformations” on page 63.

Accessing data streams

To access the data stream for a request, Gosu provides an annotation (WsiRequestTransform) to inspect or
transform an incoming request data stream. Gosu provides another annotation (WsiResponseTransform) to inspect
or transform an outgoing response data stream. Both annotations take a Gosu block that takes an input stream
(java.io.InputStream) and returns another input stream. Gosu calls the annotation block for every request or
response, depending on the type of annotation.

Example of data stream request and response transformations

The following example implements a request transform and a response transform to apply a simple encryption
security layer to a web service.
The example applies the same incremental transformation to the request and the response data streams. The
transformation processes the data streams byte by byte to change the bits in each byte from a 1 to a 0 or a 0 to a 1.
The example transformation code uses the Gosu bitwise exclusive OR (XOR) logical operator (^) to perform the
bitwise changes on each byte. The XOR logical operator is a symmetrical operation. If you apply the XOR operation to
a data stream and then apply the operation again to the transformed data stream, you obtain the original data stream.
Therefore, transforming the incoming request data stream by using the XOR operation encrypts the data. Conversely,
transforming the outgoing response data stream by using the XOR operation decrypts the data.

package gw.webservice.example

uses gw.util.StreamUtil
uses gw.xml.ws.annotation.WsiWebService
uses gw.xml.ws.annotation.WsiRequestTransform
uses gw.xml.ws.annotation.WsiResponseTransform
uses java.io.ByteArrayInputStream
uses java.io.InputStream

@WsiWebService

// Specify data stream transformations for web service requests and responses.

74 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

@WsiRequestTransform(WsiTransformTestService._xorTransform)
@WsiResponseTransform(WsiTransformTestService._xorTransform)

class WsiTransformTestService {

// Declare a static variable to hold a Gosu block that encrypts and decrypts data streams.
public static var _xorTransform(inputStream : InputStream) : InputStream = \ inputStream ->{

// Get the input stream, and store it in a byte array.

var bytes = StreamUtil.getContent(inputStream)

// Encrypt the bits in each byte.

for (b in bytes index idx) {
bytes[idx] = (b ^ 17) as byte // XOR encryption with "17" as the encryption mask
}

return new ByteArrayInputStream(bytes)

}

function add(a : int, b : int) : int {

return a + b
}
}

In the preceding example, the request transformation and the response transformation use the same Gosu block for
transformation logic because the block uses a symmetrical algorithm. In a typical production usage, the request
transformation and the response transformation use different Gosu blocks because their transformation logic differs.

See also
• “Using WSS4J for encryption, signatures, and other security headers” on page 75

Applying multiple security layers to a web service

Whenever you apply multiple layers of security to your web service, the order of substeps in your request and
response transformation blocks is critical. Typically, the order of substeps in your response block reverses the order
of substeps in your request block. For example, if you encrypt and then add a digital signature to the response data
stream, remove the digital signature before decrypting the request data stream. If you remove a security layers from
your web service, ensure the remaining layers preserve the correct order of substeps in the transformation blocks.

Using WSS4J for encryption, signatures, and other security headers

The following example uses the Java utility WSS4J to implement encryption, digital cryptographic signatures, and
other security elements (a timestamp). This example has three parts.

Part 1 of the example that uses WSS4J

The first part of the example is a utility class called demo.DemoCrypto that implements an input stream encryption
routine that adds a timestamp, then a digital signature, then encryption. To decrypt the input stream for a request, the
utility class knows how to decrypt the input stream and then validate the digital signature.
Early in the encryption (addCrypto) and decryption (removeCrypto) methods, the code parses, or inflates, the XML
request and response input streams into hierarchical DOM trees that represent the XML. The methods call the
internal class method parseDOM to parse input streams into DOM trees.
Parsing the input streams in DOM trees is an important step. Some of the encryption information, such as
timestamps and digital signatures, must be added in a particular place in the SOAP envelope. At the end of the
encryption and decryption methods, the code serializes, or flattens, the DOM trees back into XML request and
response input streams. The methods call the internal class method serializeDOM to serialize DOM trees back into
input streams.

package gw.webservice.example

uses gw.api.util.ConfigAccess
uses java.io.ByteArrayInputStream
uses java.io.ByteArrayOutputStream

Publishing web services 75

Guidewire PolicyCenter 9.0.6 Integration Guide

uses java.io.InputStream
uses java.util.Vector
uses java.util.Properties
uses java.lang.RuntimeException
uses javax.xml.parsers.DocumentBuilderFactory
uses javax.xml.transform.TransformerFactory
uses javax.xml.transform.dom.DOMSource
uses javax.xml.transform.stream.StreamResult
uses org.apache.ws.security.message.*
uses org.apache.ws.security.*
uses org.apache.ws.security.handler.*

// Demonstration input stream encryption and decryption functions.

// The layers of security are a timestamp, a digital signature, and encryption.
class DemoCrypto {

// Encrypt an input stream.

static function addCrypto(inputStream : InputStream) : InputStream {
var crypto = getCrypto()

// Parse the input stream into a DOM (Document Object Model) tree.
var domEnvironment = parseDOM(inputStream)

var securityHeader = new WSSecHeader()

securityHeader.insertSecurityHeader(domEnvironment);

var timeStamp = new WSSecTimestamp();

timeStamp.setTimeToLive(600)
domEnvironment = timeStamp.build(domEnvironment, securityHeader)

var signer = new WSSecSignature();

signer.setUserInfo("ws-client", "client-password")
var parts = new Vector()
parts.add(new WSEncryptionPart("Timestamp",
"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd",
"Element"))
parts.add(new WSEncryptionPart("Body",
gw.xsd.w3c.soap12_envelope.Body.$QNAME.NamespaceURI, "Element"));
signer.setParts(parts);
domEnvironment = signer.build(domEnvironment, crypto, securityHeader);

var encrypt = new WSSecEncrypt()

encrypt.setUserInfo("ws-client", "client-password")
// encryptionParts=
// {Element}{http://www.w3.org/2000/09/xmldsig#}Signature;{Content}
// {http://schemas.xmlsoap.org/soap/envelope/}Body
parts = new Vector()
parts.add(new WSEncryptionPart("Signature", "http://www.w3.org/2000/09/xmldsig#", "Element"))
parts.add(new WSEncryptionPart("Body", gw.xsd.w3c.soap12_envelope.Body.$QNAME.NamespaceURI,
"Content"));
encrypt.setParts(parts)
domEnvironment = encrypt.build(domEnvironment, crypto, securityHeader);

// Serialize the modifed DOM tree back into an input stream.

return new ByteArrayInputStream(serializeDOM(domEnvironment.DocumentElement))
}

// Decrypt an input stream.

static function removeCrypto(inputStream : InputStream) : InputStream {

// Parse the input stream into a DOM (Document Object Model) tree.
var envelope = parseDOM(inputStream)

var secEngine = WSSecurityEngine.getInstance();

var crypto = getCrypto()
var results = secEngine.processSecurityHeader(envelope, null, \ callbacks ->{
for (callback in callbacks) {
if (callback typeis WSPasswordCallback) {
callback.Password = "client-password"
} else {
throw new RuntimeException("Expected instance of WSPasswordCallback")
}
}
}, crypto);

for (result in results) {

var eResult = result as WSSecurityEngineResult
// Note: An encryption action does not have an associated principal.
// Only Signature and UsernameToken actions return a principal

76 chapter 3: Publishing web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

if (eResult.Action != WSConstants.ENCR) {
print(eResult.Principal.Name);
}
}

// Serialize the modifed DOM tree back into an input stream.

return new ByteArrayInputStream(serializeDOM(envelope.DocumentElement))
}

// Private function to create a map of WSS4J cryptographic properties.

private static function getCrypto() : org.apache.ws.security.components.crypto.Crypto {

var cryptoProps = new Properties()

cryptoProps.put("org.apache.ws.security.crypto.merlin.keystore.alias", "ws-client")
cryptoProps.put("org.apache.ws.security.crypto.merlin.keystore.password", "client-password")
cryptoProps.put("org.apache.ws.security.crypto.merlin.keystore.type", "jks")
cryptoProps.put("org.apache.ws.security.crypto.merlin.file", ConfigAccess.getConfigFile(
"config/etc/client-keystore.jks").CanonicalPath)
cryptoProps.put("org.apache.ws.security.crypto.provider",
"org.apache.ws.security.components.crypto.Merlin")

return org.apache.ws.security.components.crypto.CryptoFactory.getInstance(cryptoProps)
}

// Private function to parse an input stream into a hierarchical DOM tree.

private static function parseDOM(inputStream : InputStream) : org.w3c.dom.Document {

var factory = DocumentBuilderFactory.newInstance();

factory.setNamespaceAware(true);

return factory.newDocumentBuilder().parse(inputStream);
}

// Private function to serialize a hierarchical DOM tree into an input stream.

private static function serializeDOM(element : org.w3c.dom.Element) : byte[] {

var transformerFactory = TransformerFactory.newInstance();

var transformer = transformerFactory.newTransformer();
var baos = new ByteArrayOutputStream();
transformer.transform(new DOMSource(element), new StreamResult(baos));

return baos.toByteArray();
}
}

Part 2 of the example that uses WSS4J

The next part of this example is a web service implementation class written in Gosu. The following sample Gosu
code implements the web service in the class demo.DemoService.

package gw.webservice.example

uses gw.xml.ws.annotation.WsiWebService
uses gw.xml.ws.annotation.WsiRequestTransform
uses gw.xml.ws.annotation.WsiResponseTransform
uses gw.xml.ws.annotation.WsiPermissions
uses gw.xml.ws.annotation.WsiAvailability

@WsiWebService
@WsiAvailability(NONE)
@WsiPermissions({})
@WsiRequestTransform(\ inputStream ->DemoCrypto.removeCrypto(inputStream))
@WsiResponseTransform(\ inputStream ->DemoCrypto.addCrypto(inputStream))

// This web service computes the sum of two integers. The web service decrypts incoming SOAP
// requests and encrypts outgoing SOAP responses.
class DemoService {

// Compute the sum of two integers.

function add(a : int, b : int) : int {
return a + b
}
}

Publishing web services 77

Guidewire PolicyCenter 9.0.6 Integration Guide

Notice the following implementation details in this web service implementation class.
• The web service provides a method that adds two numbers, but the service itself has a request and response
transformation.
• The request transformation removes and confirms the cryptographic layer on the request, including the digital
signature and encryption, by calling DemoCrypto.removeCrypto(inputStream).
• The response transformation adds the cryptographic layer on the response by calling
DemoCrypto.addCrypto(inputStream).

Part 3 of the example that uses WSS4J

The third and final part of this example is code to test this web service.

var webService = new wsi.local.demo.demoservice.DemoService()

webService.Config.RequestTransform = \ inputStream ->demo.DemoCrypto.addCrypto(inputStream)
webService.Config.ResponseTransform = \ inputStream ->demo.DemoCrypto.removeCrypto(inputStream)
print(webService.add(3, 5))

Paste this code into the Gosu Scratchpad and run it.

Locale and language support

By default, web services use the default server locale and language. Web service clients can override this behavior
and set a locale and language to use while processing a web service request.
To set the locale, add a SOAP header element type <gwsoap:gw_locale> with the namespace "http://
guidewire.com/ws/soapheaders". The element text specifies the desired locale code.
To set the language, add the element type <gwsoap:gw_language> and specify the desired language code.
The following example SOAP envelope contains a SOAP header that sets the locale and language to fr_FR.

<soap12:Envelope xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Header>
<gwsoap:gw_locale xmlns:gwsoap="http://guidewire.com/ws/soapheaders">fr_FR</gwsoap:gw_locale>
<gwsoap:gw_language xmlns:gwsoap="http://guidewire.com/ws/soapheaders">fr_FR</gwsoap:gw_language>
</soap12:Header>
<soap12:Body>
...
</soap12:Body>
</soap12:Envelope>

See also
• “Setting locale or language in a Guidewire application” on page 93

Checking for duplicate external transaction IDs

To detect duplicate operations from external systems that change data, add the
@WsiCheckDuplicateExternalTransaction annotation to your web service implementation class. To apply this
feature for all operations on the service, add the annotation at the class level. To apply only to some operations,
declare the annotation at the method level for individual operations.
If you apply this feature to an operation or to the whole class, PolicyCenter checks for the SOAP header
<transaction_id> in namespace http://guidewire.com/ws/soapheaders. If the SOAP header
<transaction_id> is missing, PolicyCenter throws an exception.
PolicyCenter has some web services that include a transaction ID as a method parameter explicitly. These methods
do not use the @WsiCheckDuplicateExternalTransaction annotation or its built-in functionality.
If the header exists, the text data is the external transaction ID that uniquely identifies the transaction. The
recommended pattern for the transaction ID is to begin with an identifier for the external system, then a colon, then
an ID that is unique to that external system. The most important thing is that the transaction ID be unique across all
external systems.
78 chapter 3: Publishing web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

If the web service changes any database data, the application stores the transaction ID in an internal database table
for future reference. If in the future, some code calls the web service again with the same transaction ID, the
database commit fails and throws the following exception.

com.guidewire.pl.system.exception.DBAlreadyExecutedException

The caller of the web service can detect this exception to identify the request as a duplicate transaction.
Because this annotation relies on database transactions (bundles), if your web service does not change any database
data, this API has no effect.

See also
• If your client code is written in Gosu, to set the SOAP header see “Setting Guidewire transaction IDs on web
service requests” on page 91.

Exposing typelists and enums as enumeration values and string

values
For each typelist type or enumeration (Gosu or Java), the web service by default exposes this data as an enumeration
value in the WSDL. This applies to both requests and responses for the service.

<xs:simpleType name="HouseType">
<xs:restriction base="xs:string">
<xs:enumeration value="apartment"/>
<xs:enumeration value="house"/>
<xs:enumeration value="shack"/>
<xs:enumeration value="mobilehome"/>
</xs:restriction>
</xs:simpleType>

The published web service validates any incoming values against the set of choices and throws an exception for
unknown values. Depending on the client implementation, the web service client might check if responses contain
only allowed enumeration values during de-serialization. For typical cases, this approach is the desired behavior for
both server and client.
For example, suppose you add new codes to a typelist or enumeration for responses. If the service returns an
unexpected value in a response, it might be desirable that the client throws an exception. System integrators would
quickly detect this unexpected change. The client system can explicitly refresh the WSDL and carefully check how
the system explicitly handles any new codes.
However, in some cases you might want to expose enumerations as String values instead.
• The WSDL for a service that references typelist or enumeration types can grow in size significantly. This is true
especially if some typelists or enumerations contain a vast number of choices. The number of values for a Java
enumeration type cannot exceed 2000.
• Changing enumeration values even slightly can cause an incompatible WSDL. Forcing the web service client to
refresh the WSDL might exacerbate upgrade issues on some projects. Although the client can refresh the WSDL
from the updated service, sometimes this is an undesirable requirement. For example, perhaps new enumeration
values on the server are predictably irrelevant to an older external system.
• In some cases, your actual web service client code might be middleware that passes through String values from
another system. In such cases, you may not require explicit detection of enumeration changes in the web service
client code.
To expose typelist types and enumerations (from Gosu or Java) as a String type, add the
@WsiExposeEnumAsString annotation before the web service implementation class. In the annotation constructor,
pass the typelist or enumeration type as the argument. For example, to expose the HouseType enumeration as a
String, add the following line before the web service implementation class declaration:

@WsiExposeEnumAsString(HouseType)

Publishing web services 79

Guidewire PolicyCenter 9.0.6 Integration Guide

To expose multiple types as String values, repeat the annotation for each individual type on a separate
corresponding line. In this case, each separate line provides a different type as an argument. You can also add the
@WsiExposeEnumAsString value as a default.

Optional stateful session affinity using cookies

By default, web services do not ask the application server to generate and return session cookies. However,
PolicyCenter supports cookie-based load-balancing options for web services. This is sometimes referred to as
session affinity.
Guidewire discourages session affinity with WS-I web services. Similarly, Guidewire discourages storing any state
for a session in memory. Instead, read and write any state to the database for each request.
The web services layer can generate a cookie for a series of API calls. You can configure load balancing routers to
send consecutive SOAP calls in the same conversation to the same server in the cluster. This feature simplifies
things like portal integration. Repeated page requests by the same user, assuming successful reuse of the cookie, go
to the same node in the cluster.
By using session affinity, you can improve performance by ensuring that caches for that node in the cluster tend to
already contain recently used objects and any session-specific data.
To create cookies for the session, append the text "?stateful" (with no quotes) to the API URL.
From Gosu client code, you can use code similar to following to append text to the URL.

uses gw.xml.ws.WsdlConfig
uses java.net.URI
uses wsi.remote.gw.webservice.ab.ab900.abcontactapi.ABContactAPI

// Get a reference to an API object

var api = new ABContactAPI()

// Get URL and override URL to force creation of local cookies to save session for load balancing
api.Config.ServerOverrideUrl = new URI(ABContactAPI.ADDRESS + "?stateful")

// Call whatever API method you need as you normally would...

api.getReplacementAddress("12345")

The code might look very different depending on your choice of web service client programming language and
SOAP library.

80 chapter 3: Publishing web services

chapter 4

Calling web services from Gosu

Gosu code can import SOAP API web services from external systems and call these services as a SOAP client. The
Gosu language handles all aspects of object serialization, object deserialization, basic authentication, and SOAP
fault handling.

Overview of consuming web services

Gosu supports calling SOAP web services that are compliant with the WS-I Basic Profile specification. WS-I is an
open industry organization that promotes industry-wide best practices for web services interoperability among
diverse systems. The organization provides several different profiles and standards. The WS-I Basic Profile is the
baseline for interoperable web services and more consistent, reliable, and testable APIs.
Gosu offers native WS-I web service client code with the following features.
• Call web service methods with natural Gosu syntax for method calls.
• Call web services optionally asynchronously.
• Support one-way web service methods.
• Separately encrypt requests and responses.
• Process attachments that use the multi-step MTOM protocol.
• Sign incoming responses with digital signatures.
One of the big differences between WS-I and older styles of web services is how the client and server encodes API
parameters and return results. When you use the WS-I standards, you can use the encoding called Document Literal
encoding (document/literal). The document-literal-encoded SOAP message contains a complete XML document
for each method argument and return value. The schema for each of these documents is defined in a XSD file. The
WSDL that describes how to talk to the published WS-I service includes a complete XSD describing the format of
the embedded XML document. The outer message is very simple, and the inner XML document contains all of the
complexity. Anything that an XSD can define becomes a valid payload or return value.
The WS-I standard supports a mode called RPC Literal (RPC/literal) instead of Document Literal. Despite the
similarity in name, WS-I RPC Literal mode is not closely related to RPC encoding (RPCE). Gosu supports the WS-I
RPC Literal mode for Gosu web service client code. Gosu supports RPC Literal mode by automatically converting
WSDL in RPC Literal mode to equivalent WSDL in Document Literal mode.
An external web service that does not conform to the WS-I Basic Profile, such as an RPC/encoded web service or a
service that uses a non-conforming callback scenario, can still be called from Gosu. To communicate with such a
web service, customized code can be written using a web services engine framework, such as Apache Axis/Axis2.
The framework creates Java stubs for the web service, and the generated stubs can be called like a common class
method.
Calling web services from Gosu 81
Guidewire PolicyCenter 9.0.6 Integration Guide

Loading WSDL locally by using web service collections

The recommended way of consuming WS-I web services is to use a web service collection in Guidewire Studio™.
A web service collection encapsulates one or more web service endpoints and stores any WSDL or XSD files that
they reference. A web service collection file encapsulates the set of resources necessary to connect to a web service
on an external server. Collection files have a .wsc file extension.
You can refresh the WSDL or XSD files in a specific web service collection from the external servers that publish
web services. In Studio, navigate to a web service collection. Collections are stored within the
configuration→gsrc→wsi hierarchy. Open a collection file to show it in the Web Service editor. To fetch the
collection’s resources, click the Fetch icon in the editor toolbar.
To specify a particular web service environment, click the Setup Environment link in the editor toolbar. The Studio
Settings windows opens. Select Guidewire Studio from the left Sidebar. The Web Services section includes an
Environment field. Select the environment from the field’s drop-down list. The available environments are based on
the env attributes defined in the suite-config.xml suite configuration file. After the collection’s resources are
fetched, the application resources for the configured web service environment are retrieved.
You can also refresh web service collections from the command prompt by running the following command.

gwb genFromWsc

Note: You cannot specify local: as the protocol to load a web service's WSDL. You must use the
URL of the server or a variable that resolves to a valid URL, and you must ensure that the server is
running before loading its WSDL.
Note: While you can specify multiple environments in the Environment field, the PolicyCenter server
runs in only one environment. In the case of a server cluster, PolicyCenter requires that all servers in
the cluster to start in the same environment.
Additionally, it is invalid to specify multiple identical environment-server pairs in a configuration.
Such configuration elements are duplicates and result in runtime errors.

Loading WSDL directly into the file system for testing purposes
For testing, or in other unusual cases, you might want to load WSDL directly to the file system without using a web
service collection.
Guidewire strongly recommends that you create a web service collection for consuming external web services
instead of loading WSDL directly to the file system.
To consume an external web service, put the appropriate WSDL and XML schema files (XSDs) in the Gosu class
hierarchy on your local system. Place them in the directory that corresponds to the package in which you want new
types to appear. For example, place the WSDL and XSD files next to the Gosu class files that call the web service,
organized in package hierarchies just like class files.
The following sample Gosu code shows how to manually fetch web service WSDLs for test purposes or for
command-line use from a web service server.

uses gw.xml.ws.*
uses java.net.URL
uses java.io.File

// Set the web service endpoint URL for the web service WSDL
var urlStr = "http://www.aGreatWebService.com/GreatWebService?wsdl"

// Set the location in your file system for the web service WSDL
var loc = "/wsi/remote/GreatWebService"

// Load the web service WSDL into Gosu

Wsdl2Gosu.fetch(new URL(urlStr), new File(loc))

The urlStr variable stores the URL to the web service WSDL. The loc variable contains the path on your file
system where the fetched WSDL is stored. You can run your version of the preceding sample Gosu code in the Gosu
Scratchpad.
82 chapter 4: Calling web services from Gosu
 Guidewire PolicyCenter 9.0.6 Integration Guide

Security and authentication

The WS-I Basic Profile describes support for some types of security standards for web services, such as encryption
and digital signatures (cryptographically signed messages).

Types of client connections

From Gosu, there are three types of WS-I web service client connections.
• Standard round trip methods (synchronous request and response)
• Asynchronous round trip methods (send the request and immediately return to the caller, and check later to see if
the request finished).
• One-way methods, which indicate a method defined to have no SOAP response at all.

How does Gosu process WSDL?

Studio adds a WSDL file to the class hierarchy automatically for each registered Web Service Collection in the Web
Services editor in Studio. Gosu creates all the types for your web service in the namespace ws.web_service_name.
For this example, assume that the name of your web service is MyService. Gosu creates all the types for your web
service in the namespace gw.config.webservices.MyService.
Suppose you add a Web Service in Studio and you name the web service MyService. Gosu creates all the types for
your web service in the following namespace.

ws.myservice.*

Suppose you add a WSDL file directly to your class hierarchy called MyService.wsdl in the package
example.pl.gs.wsic. Gosu creates all the types for your web service in the following namespace.

example.pl.gs.wsic.myservice.*

The name of MyService becomes lowercase myservice in the package hierarchy for the XML objects because the
Gosu convention for package names is lowercase. There are other name transformations as Gosu imports types from
XSDs.
The structure of a WSDL comprises the following items.
• One or more services
• For each service, one or more ports
A port represents a protocol or other context that might change how the WSDL defines that service. For example,
methods might be defined differently for different versions of SOAP, or an additional method might be added for
some ports. WSDL might define one port for SOAP 1.1 clients, one port for SOAP 1.2 clients, one port for
HTTP non-SOAP access, and so on. See discussion later in this topic for what happens if multiple ports exist in
the WSDL.
• For each port, one or more methods
A method, also called an operation or action, performs a task and optionally returns a result. The WSDL includes
XML schemas (XSDs), or it imports other WSDL or XSD files. Their purposes are to describe the data for each
method argument type and each method return type.
Suppose the WSDL has the following hierarchy.

<wsdl>
<types>
<schema>
<import schemaLocation="yourschema.xsd"/>
<!-- Now define various operations (API methods) in the WSDL ... -->

The details of the web service APIs are omitted in this example WSDL. Assume the web service contains exactly
one service called SayHello, and that service contains one method called helloWorld. For this first example,
Calling web services from Gosu 83
Guidewire PolicyCenter 9.0.6 Integration Guide

assume that the method takes no arguments, returns no value, and is published with no authentication or security
requirements.
In Gosu, you can call the remote service represented by the WSDL.

// Get a reference to the web service API object in the namespace of the WSDL
// Warning: This object is not thread-safe. Do not save in a static variable or singleton intance var.
var service = new ws.myservice.SayHello()

// Call a method on the service

service.helloWorld()

Of course, real APIs need to transfer data also. In our example WSDL, notice that the WSDL refers to a secondary
schema called yourschema.xsd.
Studio adds any attached XSDs into the web_service_name.wsdl.resources subdirectory.
Let us suppose the contents of your yourschema.xsd file look like the following.

<schema>
<element name="Root" type="xsd:int"/>
</schema>

Note that the element name is "root" and it contains a simple type (int). This XSD represents the format of an
element for this web service. The web service could declare a <root> element as a method argument or return type.
Now let us suppose there is another method in the SayHello service called doAction and this method takes one
argument that is a <root> element.
In Gosu, you can call the remote service represented by the WSDL.

// Get a Gosu reference to the web service API object

// Warning: This object is not thread-safe. Do not save in a static variable or singleton intance var.
var service = new ws.myservice.SayHello()

// Create an XML document from the WSDL by using the Gosu XML API
var x = new ws.myservice.Root()

// Call a method that the web service defines

var ret = service.doAction( x )

The package names are different if you place your WSDL file in a different part of the package hierarchy.
If you use Guidewire Studio, you do not need to manipulate the WSDL file manually. Studio automates getting the
WSDL and saving it when you add a Web Service in the user interface.
For each web service API call, Gosu first evaluates the method parameters. Gosu serializes the root XmlElement
instance and its child elements into XML raw data using the associated XSD data from the WSDL. Next, Gosu
sends the resulting XML document to the web service. In the SOAP response, the main data is an XML document,
whose schema is contained in (or referenced by) the WSDL.

Web service API objects are not thread safe

To create a WS-I API object, use a new expression to instantiate the appropriate fully-qualified type.

var service = new ws.myservice.SayHello()

Be warned that the WS-I API object is not thread-safe in all cases. It is dangerous to modify any configuration when
another thread might have a connection open. Also, some APIs may directly or indirectly modify the state on the
API object itself.
For example, the initializeExternalTransactionIdForNextUse method saves information that is specific to one
request, and then resets the transaction ID after one use.

84 chapter 4: Calling web services from Gosu

 Guidewire PolicyCenter 9.0.6 Integration Guide

It is safest to follow the following rules.

• Instantiate the WS-I API object each time it is needed. This careful approach allows you to modify the
configuration and use API without concerns for thread-safety.
• Do not save API objects in static variables.
• Do not save API objects in instance variables of classes that are singletons, such as plugin implementations. Each
member field of the plugin instance becomes a singleton and needs to be shared across multiple threads.

Learning Gosu XML APIs

All WS-I method argument types and return types are defined from schemas (the XSD embedded in the WSDL).
From Gosu, all these objects are instances of subclasses of XmlElement, with the specific subclass defined by the
schemas in the WSDL. From Gosu, working with WS-I web service data requires that you understand Gosu XML
APIs.
In many cases, Gosu hides much of the complexity of XML so you do not need to worry about it. For example, for
XSD-types, in Gosu you do not have to directly manipulate XML as bytes or text. Gosu handles common types like
number, date, or Base64 binary data. You can directly get or set values (such as a Date object rather than a serialized
xsd:date object). The XmlElement class, which represents an XML element hide much of the complexity.
The following items describe notable tips to working with XML in Gosu.
• When using a schema (an XSD, or a WSDL that references an XSD), Gosu exposes shortcuts for referring to
child elements using the name of the element.
• When setting properties in an XML document, Gosu creates intermediate XML element nodes in the graph
automatically. Use this feature to significantly improve the readability of your XML-related Gosu code.
• For properties that represent child elements that can appear more than once, Gosu exposes that property as a list.
For list-based types like this, there is a special shortcut to be aware of. If you assign to the list index equal to the
size of the list, then Gosu treats the index assignment as an insertion. This is also true if the size of the list is zero:
use the [0] array/list index notation and set the property. This inserts the value into the list, which is equivalent
to adding an element to the list. However, you do not have to worry about whether the list exists yet. If you are
creating XML objects in Gosu, by default the lists do not yet exist.
In other words, use the following syntax.

element.PropertyName[0] = childElement

If the list does not exist yet for a list property at all, Gosu creates the list upon the first insertion. In other words,
suppose an element contains child elements that represent an address and the child element has the name
Address. If the XSD declares the element could exist more than once, the element.Address property is a list of
addresses. The following code creates a new Address:

element.Address[0] = new my.package.xsdname.elements.Address()

What Gosu creates from your WSDL

Within the namespace of the package of the WSDL, Gosu creates some new types.
For each service in the web service, Gosu creates a service by name. For example, if the external service has a
service called GeocodeService and the WSDL is in the package examples.gosu.wsi, then the service has the fully-
qualified type examples.gosu.wsi.GeocodeService. Create a new instance of this type, and you then you can call
methods on it for each method.
For each operation in the web service, generally speaking Gosu creates two local methods.
• One method with the method name in its natural form, for example, suppose a method is called doAction.
• One method with the method name with the async_ prefix, for example, async_doAction. This version of the
method handles asynchronous API calls.
Calling web services from Gosu 85
Guidewire PolicyCenter 9.0.6 Integration Guide

Special behavior for multiple ports

Gosu automatically processes ports from the WSDL identified as either SOAP 1.1 or SOAP 1.2. If both are available
for any service, Gosu ignores the SOAP 1.1 ports. In some cases, the WSDL might define more than one available
port (such as two SOAP 1.2 ports with different names).
For example, suppose you add a WSDL file to your class hierarchy called MyService.wsdl in the package
example.pl.gs.wsic. Gosu chooses a default port to use and creates types for the web service at the following
path.

ROOT_PACKAGE.WSDL_NAME_NORMALIZED.NORMALIZED_SERVICE_NAME

The NORMALIZED_SERVICE_NAME name of the package is the name of the service as defined by the WSDL, with
capitalization and conflict resolution as necessary. For example, if there are two services in the WSDL named
Report and Echo, then the API types are in the following location.

example.pl.gs.wsic.myservice.Report
example.pl.gs.wsic.myservice.Echo

Gosu chooses a default port for each service. If there is a SOAP 1.2 version, Gosu prefers that version.
Additionally, Gosu provides the ability to explicitly choose a port. For example, if there is a SOAP 1.1 port and a
SOAP 1.2 port, you could explicitly reference one of those choices. Gosu creates all the types for your web service
ports within the ports subpackage, with types based on the name of each port in the WSDL.

ROOT_PACKAGE.WSDL_NAME_NORMALIZED.ports.SERVICE_AND_PORT_NAME

The SERVICE_AND_PORT_NAME is the service name, followed by an underscore, followed by the port name.
For example, suppose the ports are called p1 and p2 and the service is called Report. Gosu creates types within the
following packages.

example.pl.gs.wsic.myservice.ports.Report_p1
example.pl.gs.wsic.myservice.ports.Report_p2

Additionally, if the port name happens to begin with the service name, Gosu removes the duplicate service name
before constructing the Gosu type. For example, if the ports are called ReportP1, and helloP2, Gosu creates types
within the following packages.

example.pl.gs.wsic.myservice.ports.Report_P1 // NOTE: it is not Report_ReportP1

example.pl.gs.wsic.myservice.ports.Report_helloP2 // not a duplicate, so Gosu does not remove "Hello"

Each one of those hierarchies would include method names for that port for that service.

Request XML complexity affects appearance of method arguments

A WS-I operation defines a request element. If the request element is simply a sequence of elements, Gosu converts
these elements into multiple method arguments for the operation. For example, if the request XML has a sequence
of five elements, Gosu exposes this operation as a method with five arguments.
If the request XML definition uses complex XML features into the operation definition itself, Gosu does not extract
individual arguments. Instead Gosu treats the entire request XML as a single XML element based on an XSD-based
type.
For example, if the WSDL defines the operation request XML with restrictions or extensions, Gosu exposes that
operation in Gosu as a method with a single argument. That argument contains one XML element with a type
defined from the XSD.
Use the regular Gosu XML APIs to navigate that XML document from the XSD types in the WSDL.
86 chapter 4: Calling web services from Gosu
 Guidewire PolicyCenter 9.0.6 Integration Guide

Adding configuration options to a web service

If a web service does not require encryption, authentication, or digital signatures, instantiate the service object and
call methods on it.

// Get a reference to the service in the package namespace of the WSDL

var api = new example.gosu.wsi.myservice.SayHello()

// Call a method on the service

api.helloWorld()

If a web service requires encryption, authentication, or digital signatures, there are two approaches available.
• Configuration objects on the service instance
Set the configuration options directly on the configuration object for the service instance. The service instance is
the newly-instantiated object that represents the service. In the previous example, the api variable holds a
reference for the service instance. That object has a Config property that contains the configuration object of
type WsdlConfig.
• Configuration providers in Studio
Add one or more WS-I web service configuration providers in the Studio Web Service Collection editor Settings
tab.

Directly modifying the WSDL configuration object for a service

To add authentication or security settings to a web service you can do so by modifying the options on the service
object. To access the options from the API object (in the previous example, the object in the variable called api), use
the syntax api.Config. That property contains the API options object, which has the type gw.xml.ws.WsdlConfig.
The WSDL configuration object has properties that add or change authentication and security settings. The
WsdlConfig object itself is not an XML object (it is not based on XmlElement), but some of its subobjects are
defined as XML objects. Fortunately, in typical code you do not need to really think about that difference. Instead,
use a straightforward syntax to set authentication and security parameters.
For XSD-generated types, if you set a property several levels down in the hierarchy, Gosu adds any intermediate
XML elements if they did not already exist. This makes your XML-related code look concise.

Centralizing your WSDL configuration by adding configuration provider classes

You can add one or more WS-I web service configuration providers in the Studio Web Service Collection editor
Settings tab. A web service configuration provider centralizes and encapsulates the steps required to add encryption,
authentication, or digital signatures to your web service client code. You can also define different settings based on
environment or server settings at run time.
For example, instead of adding encryption and authentication in your code each time that you call out to a single
service, you can centralize that code. Using a configuration provider has the side effect of making your web service
client code look cleaner. This approach separates the code that requests the web service call from the transport-layer
authentication and security configuration.
A configuration provider is a class that implements the interface
gw.xml.ws.IWsiWebserviceConfigurationProvider. This interface defines a single method.

function configure( serviceName : QName, portName : QName, config : WsdlConfig )

The arguments are as follows.

• The service name, as a QName. This is the service as defined in the WSDL for this service.
• The port name, as a QName. Note that this is not a TCP/IP port. This is a port in the sense of the WSDL
specification.
• A WSDL configuration object, which is the WsdlConfig object that an API service object contains each time you
instantiate the service.
Calling web services from Gosu 87
Guidewire PolicyCenter 9.0.6 Integration Guide

You can write zero, one, or more than one configuration providers and attach them to a web service collection. This
means that for each new connection to one of those services, each configuration provider has an opportunity to
(optionally) add configuration options to the WsdlConfig object.
For example, you could write one configuration provider that adds all configuration options for web services in the
collection, or write multiple configuration providers that configure different kinds of options. For an example of
multiple configuration providers, you could implement the following solution.
• Add one configuration provider that knows how to add authentication.
• Add a second configuration provider that knows how to add digital signatures.
• Add a third configuration provider that knows how to add an encryption layer.
Separating out these different types of configuration could be advantageous if you have some web services that
share some configuration options but not others. For example, perhaps all your web service collections use digital
signatures and encryption, but the authentication configuration provider class might be different for different web
service collections.
The list of configuration provider classes in the Studio editor is an ordered list. For typical systems, the order is very
important. For example, performing encryption and then a digital signature results in different output then adding a
digital signature and then adding encryption. You can change the order in the list by clicking a row and clicking
Move Up or Move Down. You can configure these settings by environment (Env) or server (Server). For default items, set
them first in the list and leave the Env or Server fields blank to indicate it as a default. For example, if you have a
default configuration provider, set that item to a blank Env setting and move it first in the list. Later items that might
specify a non-blank Env setting will override that default value. Follow a similar approach for any defaults for any
default settings using the Server settings.
The list of configuration providers in the Studio editor is an ordered list. If you use more than one configuration
provider, carefully consider the order you want to specify them. For any defaults, such as those with blank Env or
Server fields, put those at the top (beginning) of the list.
The following is an example of a configuration provider.

package wsi.remote.gw.webservice.ab

uses javax.xml.namespace.QName
uses gw.xml.ws.WsdlConfig
uses gw.xml.ws.IWsiWebserviceConfigurationProvider

class ABConfigurationProvider implements IWsiWebserviceConfigurationProvider {

override function configure(serviceName : QName, portName : QName, config : WsdlConfig) {

config.Guidewire.Authentication.Username = "su"
config.Guidewire.Authentication.Password = "gw"
}
}

In this example, the configuration provider adds Guidewire authentication to every connection that uses that
configuration provider. Any web service client code for that web service collection does not need to add these
options with each use of the service.

Authentication schemes for consuming WS‐I web services from Gosu

When consuming web services from Gosu, there are several built-in authentication schemes. Set an authentication
scheme by setting special properties on the WsdlConfig object that you can get from the Config property on the API
instance.

// create an API service instance

var apiService = new example.gosu.wsi.myservice.SayHelloAPI()

// get the WsdlConfig object for that service

var c = apiService.Config

// set authentication properties on the WsdlConfig "c" object...

The built-in authentication schemes are HTTP basic authentication, HTTP digest authentication, and Guidewire
authentication.
88 chapter 4: Calling web services from Gosu
 Guidewire PolicyCenter 9.0.6 Integration Guide

When you call a method on the WS-I API service object, authentication happens as follows.
1. Gosu reviews properties on the WsdlConfig object in the Config property on the API instance.
2. The server looks for properties for Guidewire authentication. If they exist, Gosu attempts to authenticate using
Guidewire authentication.
3. The server looks for properties for HTTP basic authentication. If they exist, Gosu attempts to authenticate
using HTTP basic authentication.
4. The server looks for properties for HTTP digest authentication. If they exist, Gosu attempts to authenticate
using HTTP basic authentication.
5. The server attempts to connect to the service without authentication.

HTTP basic authentication

HTTP basic authentication is the most common type of authentication for consuming a web service that is not
published by a Guidewire application. HTTP authentication requests that the web server authenticate the request. If
you are connecting to a Guidewire application, instead use Guidewire authentication, which authenticates against the
user database.
User names and passwords are sent unencrypted in HTTP Basic authentication and Guidewire authentication
schemes. If you use HTTP basic or Guidewire authentication across an insecure network, it is critical that you wrap
the web service requests with HTTPS/SSL connections to protect security credentials. In contrast, the HTTP digest
authentication uses a more secure hashing scheme that does not send the password unencrypted. However, even with
HTTP digest authentication, the request and response are unencrypted. Therefore using HTTPS/SSL connections is
still valuable for overall data security over insecure networks.
To add HTTP basic authentication to an API request, use the HTTP basic authentication object at the path as
follows. Suppose api is a reference to a SOAP API that you have already instantiated with the new operator. The
properties on which to set the name and password are on the object.

api.Config.Http.Authentication.Basic

That object has a Username property for the user name and a Password property for the password. Set those two
values with the desired user name and password.

// Get a reference to the service in the package namespace of the WSDL.

var service = new example.gosu.wsi.myservice.SayHelloAPI()

service.Config.Http.Authentication.Basic.Username = "jms"
service.Config.Http.Authentication.Basic.Password = "b5"

// Call a method on the service.

service.helloWorld()

HTTP digest authentication

User names and passwords are sent unencrypted in HTTP digest authentication and Guidewire authentication
schemes. In contrast, the HTTP digest authentication uses a more secure hashing scheme that does not send the
password unencrypted.
Even with HTTP digest authentication, the request and response are unencrypted. Using HTTPS/SSL connections is
still valuable for overall data security over insecure networks.
To add HTTP digest authentication to an API request, use the HTTP digest authentication object at the path as
follows. Suppose api is a reference to a SOAP API that you have already instantiated with the new operator. The
properties on which to set the name and password are on the object:

api.Config.Http.Authentication.Digest

That object has a Username property for the user name and a Password property for the password. Set those two
values with the desired user name and password.
Calling web services from Gosu 89
Guidewire PolicyCenter 9.0.6 Integration Guide

// Get a reference to the service in the package namespace of the WSDL.

var service = new example.gosu.wsi.myservice.SayHelloAPI()

service.Config.Http.Authentication.Digest.Username = "jms"
service.Config.Http.Authentication.Digest.Password = "b5"

// Call a method on the service.

service.helloWorld()

Guidewire authentication
If you are connecting to a Guidewire application, use Guidewire authentication, which authenticates against the user
database. To consume a web service that is not published by a Guidewire application, use Guidewire authentication.
User names and passwords are sent unencrypted in HTTP basic authentication and Guidewire authentication
schemes. If you use HTTP basic or Guidewire authentication across an insecure network, it is critical that you wrap
the web service requests with HTTPS/SSL connections to protect security credentials. In contrast, the HTTP digest
authentication uses a more secure hashing scheme that does not send the password unencrypted. However, even with
HTTP digest authentication, the request and response are unencrypted. Therefore using HTTPS/SSL connections is
still valuable for overall data security over insecure networks.
To add Guidewire application authentication to API request, use the Guidewire authentication object at the path as
follows. In this example, api is a reference to a SOAP API that you have already instantiated with the new operator:

api.Config.Guidewire.Authentication

That object has a Username property for the user name and a Password property for the password. Set those two
values with the desired user name and password.

// Get a reference to the service in the package namespace of the WSDL.

var service = new example.gosu.wsi.myservice.SayHello()

service.Config.Guidewire.Authentication.Username = "jms"
service.Config.Guidewire.Authentication.Password = "b5"

// Call a method on the service.

service.helloWorld()

Guidewire suite configuration file

PolicyCenter uses a single suite configuration file called suite-config.xml to configure web service URLs for
other Guidewire InsuranceSuite applications. The suite configuration file specifies the other InsuranceSuite
applications, their URLs, port numbers, and an optional environment setting, such as production or development.
For InsuranceSuite integrations that use WS-I web services, always use the suite configuration file to configure
InsuranceSuite web services.
To read the suite configuration file in Guidewire Studio™, go to configuration→config→suite, and click suite-
config.xml. Alternatively, press Shift+Ctrl+N, and then enter the configuration file name.
In the base suite configuration file, all <product> elements are commented out. If multiple Guidewire products are
on a single server for testing, the file contents might look like the following:

<suite-config xmlns="http://guidewire.com/config/suite/suite-config">
<product name="cc" url="http://localhost:8080/cc"/>
<product name="pc" url="http://localhost:8180/pc"/>
<product name="ab" url="http://localhost:8280/ab"/>
<product name="bc" url="http://localhost:8580/bc"/>
</suite-config>

In production, the applications would be on separate physical servers with different domain names for each
application.
The optional env attribute can be specified in a <product> element to define an environment setting for the product.
A single product can have multiple configurations differentiated by their environments. For example, separate
ContactManager configurations can be defined for production and development environments.
90 chapter 4: Calling web services from Gosu
 Guidewire PolicyCenter 9.0.6 Integration Guide

<suite-config xmlns="http://guidewire.com/config/suite/suite-config">
<product name="ab" url="http://localhost:8080/cc"/>
<product name="ab" url="http://localhost:8080/cc" env="development"/>
<product name="ab" url="http://ProductionClaimCenterServer:8080/cc" env="production"/>
</suite-config>

The env attribute is optional. A maximum of one configuration for a particular product can exclude the env attribute.
A product configuration without an env attribute is interpreted as the default configuration to use whenever an
explicit system environment for PolicyCenter is not specified.
When importing WS-I WSDL, PolicyCenter does the following.
1. Checks to see whether there is a WSDL port of element type <gwwsdl:address>. If this is found,
PolicyCenter ignores any other ports on the WSDL for this service.
2. If so, it looks for shortcuts of the syntax ${productNameShortcut}. For example: ${pc}
3. If that product name shortcut is in the suite-config.xml file, PolicyCenter substitutes the URL from the
XML file to replace the text ${productNameShortcut}. If the product name shortcut is not found, Gosu
throws an exception during WSDL parsing.
For web services that Guidewire applications publish, all WSDL documents have the <gwwsdl:address> port in
the WSDL. The Guidewire application automatically specifies the application that published it using the standard
two-letter application shortcut. For example, for PolicyCenter the abbreviation is pc.

<wsdl:port name="TestServiceSoap11Port" binding="TestServiceSoap11Binding">

<soap11:address location="http://172.24.11.41:8480/pc/ws/gw/test/TestService/soap11" />
<gwwsdl:address location="${pc}/ws/gw/test/TestService/soap11" />
</wsdl:port>

Accessing the suite configuration file by using the API

PolicyCenter exposes the suite configuration file as APIs that you can access from Gosu. The
gw.api.suite.GuidewireSuiteUtil class can look up entries in the file by the product code. This class has a static
method called getProductInfo that takes a String that represents the product. Pass the String that is the
<product> element’s name attribute. The method returns the associated URL from the suite-config.xml file.

uses gw.api.suite.GuidewireSuiteUtil
var x = GuidewireSuiteUtil.getProductInfo("cc")
print(x.Url)

For the earlier suite-config.xml example file, this code prints the following output.

http://localhost:8080/cc

Setting Guidewire transaction IDs on web service requests

If the web service you are calling is hosted by a Guidewire application, there is an optional feature to detect
duplicate operations from external systems that change data. The service must add the
@WsiCheckDuplicateExternalTransaction annotation.
If this feature is enabled for an operation, PolicyCenter checks for the SOAP header <transaction_id> in
namespace http://guidewire.com/ws/soapheaders.
To set this SOAP header, call the initializeExternalTransactionIdForNextUse method on the API object and
pass the transaction ID as a String value.
PolicyCenter sends the transaction ID with the next method call and applies only to that one method call. If you
require subsequent method calls with a transaction ID, call initializeExternalTransactionIdForNextUse again
before each external API that requires a transaction ID. If your next call to an web service external operation does
not require a transaction ID, there is no need for you to call the initializeExternalTransactionIdForNextUse
method.

uses gw.xsd.guidewire.soapheaders.TransactionId
uses gw.xml.ws.WsdlConfig

Calling web services from Gosu 91

Guidewire PolicyCenter 9.0.6 Integration Guide

uses java.util.Date
uses wsi.local.gw.services.wsidbupdateservice.faults.DBAlreadyExecutedException

function callMyWebService {

// Get a reference to the service in the package namespace of the WSDL.

var service = new example.gosu.wsi.myservice.SayHello()

service.Config.Guidewire.Authentication.Username = "su"
service.Config.Guidewire.Authentication.Password = "gw"

// Create a transaction ID that has an external system prefix and then a guaranteed unique ID.
// If you are using Guidewire messaging, you may want to use the Message.ID property in your ID.
transactionIDString = "MyExtSys1:" + getUniqueTransactionID() // Create your own unique ID.

// Set the transaction ID for the next method call and only the next method call to this service.
service.initializeExternalTransactionIdForNextUse(transactionIDString)

// Call a method on the service -- A transaction ID is set only for the next operation.
service.helloWorld()

// Call a method on the service -- NO transaction ID is set for this operation!

service.helloWorldMethod2()

transactionIDString = "MyExtSys1:" + getUniqueTransactionID() // Create your own unique ID.

// Call a method on the service -- A transaction ID is set only for the next operation.
service.helloWorldMethod3()
}

Setting a timeout on a web service

To set the timeout period in milliseconds, set the CallTimeout property on the WsdlConfig object for that API
reference.

// Get a reference to the service in the package namespace of the WSDL

var service = new example.gosu.wsi.myservice.SayHello()

service.Config.CallTimeout = 30000 // 30 seconds

// Call a method on the service

service.helloWorld()

Custom SOAP headers

SOAP HTTP headers are essentially XML elements attached to the SOAP envelope for the web service request or
its response. Your code might need to send additional SOAP headers to the external system, such as custom headers
for authentication or digital signatures. You also might want to read additional SOAP headers on the response from
the external system.
To add SOAP HTTP headers to a request that you initiate, first construct an XML element using the Gosu XML
APIs (XmlElement). Next, add that XmlElement object to the list in the location api.Config.RequestSoapHeaders.
That property contains a list of XmlElement objects, which in generics notation is the interface type
java.util.List<XmlElement>.
To read (get) SOAP HTTP headers from a response, it only works if you use the asynchronous SOAP request APIs.
There is no equivalent API to get just the SOAP headers on the response, but you can get the response envelope, and
access the headers through that. You can access the response envelope from the result of the asynchronous API call.
This is an gw.xml.ws.AsyncResponse object. On this object, get the ResponseEnvelope property. For SOAP 1.2
envelopes, the type of that response is type gw.xsd.w3c.soap12_envelope.Envelope. For SOAP 1.1, the type is
the same except with "soap11" instead of "soap12" in the name.
From that object, get the headers in the Header property. That property contains a list of XML objects that represent
all the headers.

See also
• “Asynchronous method calls to web services” on page 95
92 chapter 4: Calling web services from Gosu
 Guidewire PolicyCenter 9.0.6 Integration Guide

Server override URL

To override the server URL, for example for a test-only configuration, set the ServerOverrideUrl property on the
WsdlConfig object for your API reference. This property takes a java.net.URI object for the URL.

// Get a reference to the service in the package namespace of the WSDL

var service = new example.gosu.wsi.myservice.SayHello()

service.Config.ServerOverrideUrl = new URI("http://testingserver/xx")

// Call a method on the service

service.helloWorld()

Setting XML serialization options

To send a SOAP request to the SOAP server, PolicyCenter takes an internal representation of XML and serializes
the data to actual XML data as bytes. For typical use, the default XML serialization settings are sufficient. If you
need to customize these settings, you can do so.
The most common serialization option to set is changing the character encoding to something other than the default,
which is UTF-8.
You can change serialization settings by getting the XmlSerializationOptions property on the WsdlConfig object,
which has type gw.xml.XmlSerializationOptions. Modify properties on that object to set various serialization
settings.
The easiest way to get the appropriate character set object for the encoding is to use the
Charset.forName(ENCODING_NAME) static method. That method returns the desired static instance of the character
set object.
The following code sample changes the encoding to the Chinese encoding Big5.

uses java.nio.charset.Charset

// get a reference to the service in the package namespace of the WSDL

var service = new example.gosu.wsi.myservice.SayHello()

service.Config.XmlSerializationOptions.Encoding = Charset.forName("Big5")

// call a method on the service

service.helloWorld()

This API sets the encoding on the outgoing request only. The SOAP server is not obligated to return the response
XML in the same character encoding.
If the web service is published from a Guidewire product, you can configure the character encoding for the response.

Setting locale or language in a Guidewire application

By default, a web service uses the locale and language configured on the server. A web service client can override
these attributes and set a locale and language to use while processing a request.

// Get a reference to the web service in the package namespace of the WSDL
var service = new example.gosu.wsi.myservice.SayBonjour()

service.Config.Guidewire.GwLocale = "fr_FR" // Set locale region to France

service.Config.Guidewire.GwLanguage = "fr_FR" // Set language to French

// Call a method on the service

service.BonjourToutLeMonde()

Implementing advanced web service security with WSS4J

For security options beyond HTTP Basic authentication and optional SOAP header authentication, you can use an
additional set of APIs to implement whatever additional security layers.
Calling web services from Gosu 93
Guidewire PolicyCenter 9.0.6 Integration Guide

For example, you might want to add additional layers of encryption, digital signatures, or other types of
authentication or security.
From the SOAP client side, the way to add advanced security layers to outgoing requests is to apply transformations
of the stream of data for the request. You can transform the data stream incrementally as you process bytes in the
stream. For example, you might implement encryption this way. Alternatively, some transformations might require
getting all the bytes in the stream before you can begin to output any transformed bytes. Digital signatures would be
an example of this approach. You may you use multiple types of transformations. Remember that the order of them
is important. For example, an encryption layer followed by a digital signature is a different output stream of bytes
than applying the digital signature and then the encryption.
Similarly, getting a response from a SOAP client request might require transformations to understand the response.
If the external system added a digital signature and then encrypted the XML response, you need to first decrypt the
response, and then validate the digital signature with your keystore.
The standard approach for implementing these additional security layers is the Java utility WSS4J, but you can use
other utilities as needed. The WSS4J utility includes support for the WSS security standard.

Outbound security for a web service request

To add a transformation to your outgoing request, set the RequestTransform property on the WsdlConfig object for
your API reference. The value of this property is a Gosu block that takes an input stream (InputStream) as an
argument and returns another input stream. Your block can do anything it needs to do to transform the data.
Similarly, to transform the response, set the ResponseTransform property on the WsdlConfig object for your API
reference.
The following simple example shows you could implement a transform of the byte stream. The transform is in both
outgoing request and the incoming response. In this example, the transform is an XOR (exclusive OR)
transformation on each byte. In this simple example, simply running the transformation again decodes the request.
The following code implements a service that applies the transform to any input stream. The code that actually
implements the transform is as follows. This is a web service that you can use to test this request.
The class defines a static variable that contains a field called _xorTransform that does the transformation.

package gw.xml.ws

uses gw.xml.ws.annotation.WsiWebService
uses gw.xml.ws.annotation.WsiRequestTransform
uses java.io.ByteArrayInputStream
uses gw.util.StreamUtil
uses gw.xml.ws.annotation.WsiResponseTransform
uses gw.xml.ws.annotation.WsiAvailability
uses gw.xml.ws.annotation.WsiPermissions
uses java.io.InputStream

@WsiWebService
@WsiAvailability( NONE )
@WsiPermissions( {} )
@WsiRequestTransform( WsiTransformTestService._xorTransform )
@WsiResponseTransform( WsiTransformTestService._xorTransform )
class WsiTransformTestService {

// The following method declares a Gosu block that implements the transform
public static var _xorTransform( is : InputStream ) : InputStream = \ is ->{
var bytes = StreamUtil.getContent( is )
for ( b in bytes index idx ) {
bytes[ idx ] = ( b ^ 17 ) as byte // xor encryption
}
return new ByteArrayInputStream( bytes )
}

function add( a : int, b : int ) : int {

return a + b
}
}

The following code connects to the web service and applies this transform on outgoing requests and the reply.

package gw.xml.ws

94 chapter 4: Calling web services from Gosu

 Guidewire PolicyCenter 9.0.6 Integration Guide

uses gw.testharness.TestBase
uses gw.testharness.RunLevel
uses org.xml.sax.SAXParseException

@RunLevel( NONE )
class WsiTransformTest extends TestBase {

function testTransform() {
var ws = new wsi.local.gw.xml.ws.wsitransformtestservice.WsiTransformTestService()
ws.Config.RequestTransform = WsiTransformTestService._xorTransform
ws.Config.ResponseTransform = WsiTransformTestService._xorTransform
ws.add( 3, 5 )
}
}

One‐way methods
A typical WS-I method invocation has two parts: the SOAP request, and the SOAP response. Additionally, WS-I
supports a concept called one-way methods. A one-way method is a method defined in the WSDL to provide no
SOAP response at all. The transport layer (HTTP) may send a response back to the client, however, but it contains
no SOAP response.
Gosu fully supports calling one-way methods. Your web service client code does not have to do anything special to
handle one-way methods. Gosu handles them automatically if the WSDL specifies a method this way.
Be careful not to confuse one-way methods with asynchronous methods.

Asynchronous method calls to web services

Gosu supports optional asynchronous calls to web services. Gosu exposes alternate web service methods signatures
on the service with the async_ prefix. Gosu does not generate the additional method signature if the method is a
one-way method. The asynchronous method variants return an AsyncResponse object. Use that object with a polling
design pattern by checking regularly whether it is done, then get results later, synchronously in relation to the calling
code.
The AsyncResponse object contains the following properties and methods.
start
This method initiates the web service request but does not wait for the response.
get method
This method gets the results of the web service, waiting (blocking) until complete if necessary.
RequestEnvelope
A read-only property that contains the request XML.
ResponseEnvelope
A read-only property that contains the response XML, if the web service responded.
RequestTransform
A block (an in-line function) that Gosu calls to transform the request into another form. For example, this
block might add encryption and then add a digital signature.
ResponseTransform
A block (an in-line function) that Gosu calls to transform the response into another form. For example, this
block might validate a digital signature and then decrypt the data.
The following code is an example of calling the asynchronous version of a method in contrast to calling the
asynchronous variant.

var ws = new ws.weather.Weather()

// Call the REGULAR version of the method.

var r = ws.GetCityWeatherByZIP("94114")
print( "The weather is " + r.Description )

// Call the **asynchronous** version of the same method

// -- Note the "async_" prefix to the method
var a = ws.async_GetCityWeatherByZIP("94114")

Calling web services from Gosu 95

Guidewire PolicyCenter 9.0.6 Integration Guide

// By default, the async request does NOT start automatically.

// You must start it with the start() method.
a.start()

print("The XML of the request for debugging... " + a.RequestEnvelope)

print("")
print ("In a real program, you would check the result possibly MUCH later...")

// Get the result data of this asynchronous call, waiting if necessary.

var laterResult = a.get()
print("asynchronous reply to our earlier request = " + laterResult.Description)
print("response XML = " + a.ResponseEnvelope.asUTFString())

MTOM attachments with Gosu as web service client

The W3C Message Transmission Optimization Mechanism (MTOM) is a method of efficiently sending binary data
to and from web services as attachments outside the normal response body.
The main response contains placeholder references for the attachments. The entire SOAP message envelope for
MTOM contains multiple parts. The raw binary data is in other parts of the request than the normal SOAP request or
response. Other parts can have different MIME encoding. For example, it could use the MIME encoding for the
separate binary data. This allows more efficient transfer of large binary data.
When Gosu is the web service client, MTOM is not supported in the initial request. However, if an external web
service uses MTOM in its response, Gosu automatically receives the attachment data. There is no additional step
that you need to perform to support MTOM attachments.

96 chapter 4: Calling web services from Gosu

chapter 5

General web services

This topic describes general-purpose web services, such as mapping typecodes general system tools.

Importing administrative data

PolicyCenter provides tools for exporting and importing administrative data in XML format. The easiest way to
export data suitable for import is to use the Export Data screen in the application. Then, you can use the Import Tools
web service (ImportToolsAPI) to import the exported data to a different application instance.

Prepare exported administrative data for import

To prepare exported data for XML import, use the generated XML Schema Definition (XSD) files that define the
XML data formats.

PolicyCenter/build/xsd/pc_import.xsd
PolicyCenter/build/xsd/pc_entities.xsd
PolicyCenter/build/xsd/pc_typelists.xsd

Regenerate the XSD files by running the build tool with the following option.

gwb genImportAdminDataXsd

Importing prepared administrative data

Administrative database tables can be imported from an XML file by calling the importXmlData method of the
ImportToolsAPI web service. The importXmlData method does not perform extensive data validation tests on the
imported data. Accordingly, the method must not be used to import data other than administrative data. The
imported objects do not generate events during the import operation. PolicyCenter does not throw concurrent data
change exceptions if the imported records overwrite existing records in the database.

importXmlData(xmlData : String) : ImportResults

The xmlData argument contains the XML data to import. The argument cannot be null or contain an empty string.
The method returns an ImportResults object that contains information about the import operation, such as the
number of entities imported grouped by type. If an error occurred during import, the object’s isOk method returns
false. Descriptions of the errors can be retrieved by calling the object’s getErrorLog method which returns an
array of String objects.
General web services 97
Guidewire PolicyCenter 9.0.6 Integration Guide

The performance of the import operation can be improved by wrapping the XML data in CDATA tags.

<pre>
<![CDATA[
<SampleElement>Sample data</SampleElement>
]]>
</pre>

CSV import and conversion

There are several other methods in the ImportToolsAPI web service to import and convert CSV (comma-separated
value) data. For example, import data from simple sample data files and convert them to a format suitable for XML
import, or import them directly. See the Javadoc in the implementation file for more information about the CSV
methods.
• importCsvData – import CSV data
• csvToXml – convert CSV data to XML data
• xmlToCsv – convert XML data to CSV data

Advanced import or export

If you must import data in other formats or export administrative data programmatically, write a new web service to
export administrative information one record at a time. For both import and export, if you write your own web
service, be careful never to pass too much data across the network in any API call. If you send too much data,
memory errors can occur. Do not try to import or export all administrative data in a dataset at once.

Maintenance tools web service

The MaintenanceToolsAPI web service provides a set of tools that are available if the system is at the maintenance
run level or higher.

Running batch processes by using web services

Use the startBatchProcess method of the MaintenanceToolsAPI web service to run a batch process or a writer
for a work queue. The API notifies the caller that the request is received. The caller must poll the server later to see
if the process failed or completed successfully. For server clusters, batch process runs only servers with the batch
server role. However, you can make the API request to any of the servers in the cluster. If the receiving server does
not have the batch server role, the request automatically forwards to an appropriate server.
The following code statement runs a batch process and receives its process ID.

processID = maintenanceToolsAPI.startBatchProcess("memorymonitor");

The following code statement runs a batch process and passes arguments to it.

processID = maintenanceToolsAPI.startBatchProcessWithArguments("myCustomBatchProcess", args)

The following code statements check the status of a batch process.

maintenanceToolsAPI.batchProcessStatusByName("memorymonitor")
maintenanceToolsAPI.batchProcessStatusByID(processID)

The following code statements terminate a batch process.

maintenanceToolsAPI.requestTerminationOfBatchProcessByName("memorymonitor")
maintenanceToolsAPI.requestTerminationOfBatchProcessByID(processID)

98 chapter 5: General web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

For work queues, the status methods returns the status only of the writer thread. The status methods do not check the
work queue table for remaining work items. The status of a writer reports as completed after the writer finishes
adding work items for a batch to the work queue. Meanwhile, many work items in the batch may remain
unprocessed.
For the batch process methods of the maintenance tools API, the batch processes apply only to PolicyCenter, not
additional Guidewire applications that you integrated with it.
Whenever you use the MaintenanceToolsAPI web service to run a batch process provided in the base configuration,
identify the batch process by its code as listed in the documentation. To run a custom batch process, identify the
process by the BatchProcessType typecode that you added for it. The typecode must include the APIRunnable
category to start your custom batch process with the MaintenanceToolsAPI web service.

Manipulating work queues by using web services

A work queue represents a pool of work items that can be processed in a distributed way across multiple threads or
even multiple servers. Several web service APIs query or modify the existing work queue configuration. For
example, APIs can get the number of worker threads configured for this server (instances) and the configured
delay between processing each work item (throttleInterval).
The following code example wakes up all workers for the specified work queue across the entire cluster.

import gw.webservice.pc.pc900.MaintenanceToolsAPI;
import gw.api.webservice.maintenanceTools.WorkQueueConfig;

MaintenanceToolsAPI maintenanceTools = new MaintenanceToolsAPI();

//Wakes up the workers for the work queue, ActivityEsc.

maintenanceTools.notifyQueueWorkers("ActivityEsc");

The following code statement gets the work queue names for this instance of PolicyCenter.

String[] stringArray = maintenanceTools.getWorkQueueNames();

The following code statements get the number of instances and the throttle interval for the specified work queue.

//Obtains the work queue, ActivityEsc, and assigns the object to a temporary work queue configuration
//object, wqConfig.
WorkQueueConfig wqConfig = maintenanceTools.getWorkQueueConfig("ActivityEsc");

//Obtains the number of instances and the throttle interval for wqConfig.
Integer numInstances = wqConfig.getInstances();
Long throttleInterval = wqConfig.getThrottleInterval();

The following code block sets the number of instances, the throttle interval, the batch size, and the maximum poll
interval before calling setWorkQueueConfig. Note that you must set all fields on a temporary work queue
configuration object before setting the configuration for the work queue.

//Sets all fields on the temporary work queue configuration object, wqConfig, before setting the
//configuration for the work queue.
wqConfig.setInstances(1);
wqConfig.setThrottleInterval(999);
wqConfig.setBatchSize(20);
wqConfig.setMaxPollInterval(60000);

//Sets the configuration values of the work queue, ActivityEsq, to the values established for the temporary
//work queue configuration object. This method invocation only sets the work queue configuration for the
//server that accepts the method call.
maintenanceTools.setWorkQueueConfig("ActivityEsc", wqConfig);

Worker instances that are running stop after they complete their current work item. Then, the server creates and
starts new worker instances as specified by the configuration object that you pass to the method.
The changes made using the batch process web service API are temporary. If the server starts or restarts at a later
time, the server rereads the values from work-queue.xml to define how to create and start workers.
General web services 99
Guidewire PolicyCenter 9.0.6 Integration Guide

For these APIs, the terms product and cluster apply to the current Guidewire product only as determined by the
SOAP API server requested.

Stopping startable plugins using web services

A startable plugin is a special type of code that runs without human intervention in the application server as a
background process. A startable plugin begins executing at server startup. A startable plugin can be stopped and
started again by calling methods of the MaintenanceToolsAPI web service.
To stop a startable plugin, call the stopPlugin method. To restart a startable plugin, call the startPlugin method.
These methods take the plugin name in String format as their only argument. Plugin names are defined in the
Plugin Registry in Studio.
In general, startable plugins run only on servers with the batch server role, but you can develop startable plugins
that run distributed on all servers. Before you use the MaintenanceToolsAPI web service to stop or restart a
distributed startable plugin, be certain you understand the implications for state management across all servers.

Mapping typecodes and external system codes

In the simplest case, the typecodes used by PolicyCenter typelists and the equivalent codes used by an external
system match exactly. When the typecodes between the two systems match, there is no need to map one to the other.
However, this situation is rarely possible. In most cases, the codes used in one system must be mapped to the
equivalent codes in the other system.
Typecode mappings are defined in an XML file called typecodemapping.xml. This file is located in the
PolicyCenter/modules/configuration/config/typelists/mapping directory. This file defines mappings for
one or more external systems. Each external system is identified by a unique namespace. The example mapping file
shown below maps a single PolicyCenter typelist typecode of LossType.PR to its equivalent code in two external
systems, ExtSys123 and ExtSysABC.

<?xml version="1.0"?>
<typecodemapping>
<namespacelist>
<namespace name="ExtSys123"/>
<namespace name="ExtSysABC"/>
</namespacelist>

<typelist name="LossType">
<mapping typecode="PR" namespace="ExtSys123" alias="Prop"/>
<mapping typecode="PR" namespace="ExtSysABC" alias="CPL"/>
</typelist>
</typecodemapping>

As the example file demonstrates, each external system is assigned a unique namespace name. The name is
subsequently used to map a PolicyCenter typecode to the relevant external system code. The mapped PolicyCenter
typecode is specified in the typecode attribute, and the external system code is specified in the alias attribute.
The typecodemapping.xml file can define multiple typelist elements. The value of each name attribute must be
unique and cannot be an empty string.
A single PolicyCenter typecode can be mapped to multiple external system aliases. Conversely, a single external
alias can be mapped to multiple typecodes. To determine the appropriate mapped typecode or alias in a particular
situation, an external system can call the TypelistToolsAPI web service to retrieve an array of mapped typecodes
or aliases and select the desired item from the array. PolicyCenter configuration code can resolve the issue in a
similar manner by using the static TypecodeMapper object.

The TypelistToolsAPI web service

The TypelistToolsAPI web service enables an external system to translate the mappings between its codes and
PolicyCenter typecodes.
100 chapter 5: General web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

The getTypelistValues method

The getTypelistValues method returns an array of the typekeys for a specified typelist.

getTypelistValues(typelist : String) : TypeKeyData[]

The typelist argument specifies a PolicyCenter typelist. If the typelist does not exist, the method throws an
IllegalArgumentException. The method returns an array of TypeKeyData objects that contain the typekeys
defined by the typelist. The typecode for a particular TypeKeyData object can be retrieved by calling its getCode
method.

The getTypeKeyByAlias and getTypeKeysByAlias methods

The getTypeKeyByAlias and getTypeKeysByAlias methods are used when an external system is exporting data to
PolicyCenter. The methods enable the external system to translate one of its own codes to a mapped PolicyCenter
typecode.

getTypeKeyByAlias(typelist : String, namespace : String, alias : String ) : TypeKeyData

getTypeKeysByAlias(typelist : String, namespace : String, alias : String) : TypeKeyData[]

Each argument references an attribute value assigned in the typecodemapping.xml file. The typelist argument
references a PolicyCenter typelist by specifying the value of the name attribute of the typelist element. The
namespace argument identifies the external system by specifying its unique name attribute value assigned in its
namespace element. The alias argument references the external system's code by specifying the alias attribute
value of the mapping element. None of the arguments can be null.
The methods return either a single TypeKeyData object or an array of TypeKeyData objects that are mapped to the
specified external system alias. The typecode for a particular TypeKeyData object can be retrieved by calling its
getCode method.
If getTypeKeyByAlias finds more than one typecode mapped to the specified code, it throws an
IllegalArgumentException.

The getAliasByInternalCode and getAliasesByInternalCode methods

The getAliasByInternalCode and getAliasesByInternalCode methods are used when an external system is
importing data from PolicyCenter. The term "Alias" in the method names refers to an external system's code, and
"InternalCode" refers to a PolicyCenter typelist and typecode combination. The methods enable the external system
to translate a PolicyCenter typelist/typecode to a mapped code in the external system.

getAliasByInternalCode(typelist : String, namespace : String, code : String) : String

getAliasesByInternalCode(typelist : String, namespace : String, code : String) : String[]

Each argument references an attribute value assigned in the typecodemapping.xml file. The typelist argument
references a PolicyCenter typelist by specifying the value of the name attribute of the typelist element. The code
argument references the typelist's typecode by specifying the typecode attribute value of the mapping element. The
namespace argument identifies the external system by specifying its unique name attribute value assigned in its
namespace element. None of the arguments can be null.
The methods return either a single external system code or an array of codes that are mapped to the specified
typelist and code.
If getAliasByInternalCode finds more than one code mapped to the specified typelist/typecode, it throws an
IllegalArgumentException.

The TypecodeMapper class

The TypecodeMapper class enables configuration code to translate the mappings between PolicyCenter typecodes
and the codes used by an external system.
General web services 101
Guidewire PolicyCenter 9.0.6 Integration Guide

The getTypecodeMapper method

The getTypecodeMapper method retrieves the static TypecodeMapper object which is used to translate the
mappings of typecodes and external system codes. The method is implemented in the
gw.api.util.TypecodeMapperUtil class.

gw.api.util.TypecodeMapperUtil.getTypecodeMapper() : TypecodeMapper

The method accepts no arguments. It returns a TypecodeMapper object which implements the remaining methods
described in this section.

The containsMappingFor method

The containsMappingFor method determines whether a specified typelist has any mappings to external system
codes.

containsMappingFor(typelist : String) : boolean

The typelist argument references a PolicyCenter typelist by specifying the value of the name attribute of the
typelist element defined in the typecodemapping.xml file. The specified typelist must exist in PolicyCenter or
the method throws an InvalidMappingFileException.
The method returns true if any mappings are defined for the specified typelist.

The getAliasByInternalCode and getAliasesByInternalCode methods

The getAliasByInternalCode and getAliasesByInternalCode methods are called when PolicyCenter is
exporting data to an external system. The term "Alias" in the method names refers to an external system's code, and
"InternalCode" refers to a PolicyCenter typelist and typecode combination. The methods enable the configuration
code to translate a PolicyCenter typelist/typecode to a mapped code in the external system.

getAliasByInternalCode(typelist : String, namespace : String, code : String) : String

getAliasesByInternalCode(typelist : String, namespace : String, code : String) : String

Each argument references an attribute value assigned in the typecodemapping.xml file. The typelist argument
references a PolicyCenter typelist by specifying the value of the name attribute of the typelist element. The code
argument references the typelist's typecode by specifying the typecode attribute value of the mapping element. The
namespace argument identifies the external system by specifying its unique name attribute value assigned in its
namespace element. None of the arguments can be null.
The methods return either a single external system code or an array of codes that are mapped to the specified
typelist and code. If no mapped code is found, getAliasByInternalCode returns null and
getAliasesByInternalCode returns an empty array.
If getAliasByInternalCode finds more than one code mapped to the specified typelist/typecode, it throws a
NonUniqueAliasException.

The getInternalCodeByAlias and getInternalCodesByAlias methods

The getInternalCodeByAlias and getInternalCodesByAlias methods are called when PolicyCenter is importing
data from an external system. The methods enable PolicyCenter to translate an external system's code to a mapped
typecode.

getInternalCodeByAlias(typelist : String, namespace : String, alias : String) : String

getInternalCodesByAlias(typelist : String, namespace : String, alias : String) : String[]

Each argument references an attribute value assigned in the typecodemapping.xml file. The typelist argument
references a PolicyCenter typelist by specifying the value of the name attribute of the typelist element. The
namespace argument identifies the external system by specifying its unique name attribute value assigned in its
namespace element. The alias argument references the external system's code by specifying the alias attribute
value of the mapping element. None of the arguments can be null.
102 chapter 5: General web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

The methods return either a single typecode or an array of typecodes that are mapped to the specified external
system alias. If no mapped typecode is found, getInternalCodeByAlias returns null and
getInternalCodesByAlias returns an empty array.
If getInternalCodeByAlias finds more than one typecode mapped to the specified external system code, it throws
a NonUniqueTypecodeException.

Profiling web service

The ProfilerAPI web service enables or disables the PolicyCenter profiler system for various components, such as
batch processes or web services. The ProfilerAPI is located in the gw.wsi.pl package.

Batch process and work queue profiling

The setEnableProfilerForBatchProcess method enables or disables the profiling of a type of batch process.

setEnableProfilerForBatchProcess(enable : boolean,
type : String,
hiResTime : boolean,
enableStackTracing : boolean,
enableQueryOptimizerTracing : boolean,
enableExtendedQueryTracing : boolean,
dbmsCounterThresholdMs : int,
diffDbmsCounters : boolean)

The method accepts the following arguments.

• enable - Boolean value specifying whether to enable (true) or disable (false) the profiler
• type - The type of batch process to profile. The argument value must be a String representation of a typecode
from the BatchProcessType typekey.
• hiResTime - Boolean value specifying whether to use the high-resolution clock for the profiler timing. The high-
resolution clock is available only on Windows-based systems.
• enableStackTracing - Boolean value specifying whether to allow stack tracing. Enabling stack tracing can
significantly slow the execution of the batch process. The argument's value is ignored if the enable argument is
false.
• enableQueryOptimizerTracing - Boolean value specifying whether to allow query optimizer tracing. Enabling
query optimizer tracing can significantly slow the execution of the batch process. The argument's value is ignored
if the enable argument is false.
• enableExtendedQueryTracing - Boolean value specifying whether to allow query tracing. Enabling query
tracing can significantly slow the execution of the batch process. The argument's value is ignored if the enable
argument is false.
• dbmsCounterThresholdMs - The maximum number of milliseconds a database operation can take before
generating a report using DBMS counters. To disable reporting, specify a value of zero.
• diffDbmsCounters - Boolean value specifying whether to diff DBMS counters. The argument's value is ignored
if the enable argument is false or the dbmsCounterThresholdMs argument is zero.
The method enables or disables the profiler for the specified type of batch process. If profiling is enabled, the
operation is configured according to the specified argument values.
The method has no return value.
The setEnableProfilerForWorkQueue method enables or disables the profiling of work queues associated with a
specified type of batch process.

setEnableProfilerForWorkQueue(enable : boolean,
type : String,
hiResTime : boolean,
enableStackTracing : boolean,
enableQueryOptimizerTracing : boolean,
enableExtendedQueryTracing : boolean,
dbmsCounterThresholdMs : int,
diffDbmsCounters : boolean)

General web services 103

Guidewire PolicyCenter 9.0.6 Integration Guide

The method accepts the same arguments as the setEnableProfilerForBatchProcess method.

The method has no return value.
The setEnableProfilerForBatchProcessAndWorkQueue method enables or disables the profiling of both a type of
batch process and the work queues associated with it.

setEnableProfilerForBatchProcessAndWorkQueue(enable : boolean,
type : String,
hiResTime : boolean,
enableStackTracing : boolean,
enableQueryOptimizerTracing : boolean,
enableExtendedQueryTracing : boolean,
dbmsCounterThresholdMs : int,
diffDbmsCounters : boolean)

The method accepts the same arguments as the setEnableProfilerForBatchProcess method.

The method has no return value.

Message destination profiling

The setEnableProfilerForMessageDestination method enables or disables the profiling of a messaging
destination.

setEnableProfilerForMessageDestination(enable : boolean,
destinationID : int,
hiResTime : boolean,
enableStackTracing : boolean,
enableQueryOptimizerTracing : boolean,
enableExtendedQueryTracing : boolean,
dbmsCounterThresholdMs : int,
diffDbmsCounters : boolean)

The method accepts the same arguments as the setEnableProfilerForBatchProcess method, except for the
destinationID argument, which replaces the type argument. The destinationID argument specifies the unique
numeric ID of the message destination to enable or disable profiling for.
The method has no return value.

Startable plugin profiling

The setEnableProfilerForStartablePlugin method enables or disables the profiling of a startable plugin.

setEnableProfilerForStartablePlugin(enable : boolean,
pluginName : String,
hiResTime : boolean,
enableStackTracing : boolean,
enableQueryOptimizerTracing : boolean,
enableExtendedQueryTracing : boolean,
dbmsCounterThresholdMs : int,
diffDbmsCounters : boolean)

The method accepts the same arguments as the setEnableProfilerForBatchProcess method, except for the
pluginName argument, which replaces the type argument. The pluginName argument specifies the unique String
name of the startable plugin to enable or disable profiling for.
The method has no return value.

Web service profiling

The setEnableProfilerForWebService method enables or disables the profiling of a web service.

setEnableProfilerForWebService(enable : boolean,
serviceName : String,
operationName : String,
hiResTime : boolean,
enableStackTracing : boolean,
enableQueryOptimizerTracing : boolean,

104 chapter 5: General web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

enableExtendedQueryTracing : boolean,
dbmsCounterThresholdMs : int,
diffDbmsCounters : boolean)

The method accepts the same arguments as the setEnableProfilerForBatchProcess method, except for the
replacement of the type argument with the following arguments to specify a web service.
• serviceName - Specifies the web service name
• operationName - Specifies the web service operation
The method has no return value.

Web session profiling

The setEnableProfilerForSubsequentWebSessions method enables or disables the profiling of web sessions.

setEnableProfilerForSubsequentWebSessions(name : String,
enable : boolean,
hiResTime : boolean,
enableStackTracing : boolean,
enableQueryOptimizerTracing : boolean,
enableExtendedQueryTracing : boolean,
dbmsCounterThresholdMs : int,
diffDbmsCounters : boolean)

The method accepts the same arguments as the setEnableProfilerForBatchProcess method, except for the
replacement of the type argument with the name argument. The name argument specifies the String text to use to
identify the profiler. Any text can be used. Unlike the other methods in the ProfilerAPI web service, the name
argument precedes the enable argument.
The profiling of web sessions is intended for development environments and is not recommended for production
environments.
The method has no return value.

System tools web service

The SystemToolsAPI interface provides a set of tools that are always available, even if the server is set to
maintenance run level. For servers in clusters, system tools API methods execute only on the server that receives
the request. For the complete set of methods in the system tools API, refer to the Gosu implementation class in
Guidewire Studio™.

Getting and setting the run level

The following code statement uses the SystemToolsAPI interface to retrieve the server run level.

runlevelString = systemTools.getRunLevel().getValue();

The following code statement sets the server run level.

systemTools.setRunLevel(SystemRunlevel.GW_MAINTENANCE);

Sometimes you want a more lightweight way than SOAP APIs to determine the run level of the server. During
development, you can check the run level by using your web browser.
To check the run level, call the ping URL on a PolicyCenter server using the following syntax.

http://server:port/pc/ping

An example command line is shown below.

http://PolicyCenter.mycompany.com:8180/pc/ping

General web services 105

Guidewire PolicyCenter 9.0.6 Integration Guide

If the server is running, the browser returns a short HTML result with a single ASCII character to indicate the run
level. If you are checking whether the server is running, any return value from the ping URL proves the server is
running. If the browser returns an HTTP or browser error, the server is not running.
To determine the current run level, examine the contents of the HTTP result for an ASCII character.

ASCII character in ping URL result Run level

No response to the HTTP request Server not running
ASCII character 30, the Record Separator character DB_MAINTENANCE

ASCII character 40, the character "(" MAINTENANCE

ASCII character 50, the character "2" MULTIUSER

ASCII character 0. A null character result might not be returnable for some combinations of HTTP servers GW_STARTING
and clients.

Getting server and schema versions

You can use the SystemToolsAPI web service method getVersion to get the current server and schema versions.
The method returns a structure that contains the following properties.
• AppVersion – application version as a String
• PlatformVersion – platform version as a String
• SchemaVersion – schema version as a String
• CustomerVersion – customer version as a String

Clustering tools
There are several related SystemToolsAPI web service methods for managing clusters of servers. Call these
methods from an external system to get information about the cluster and manage failure conditions.

Get cluster state

To get a list of all nodes in the cluster, their roles, and what distributed components they run, call the
SystemToolsAPI web service method getClusterState.
It takes no arguments and returns an object of type ClusterState, which encapsulates the following properties.
• Members – Cluster members, as a list of ClusterMemberState objects. Each ClusterMemberState as the
following properties.
◦ ServerId – Server unique ID
◦ InCluster – Boolean value that indicates if the server is successfully in the cluster
◦ RunLevel – Run level
◦ Roles – List of roles. Each role is a String value
◦ ServerStarted – Boolean value that indicates if the server is started
◦ LastUpdatedTime – Last time when the server updated its status, as a Date object
◦ PlannedShutdownInitiated – Date start of an initiated shutdown, or null if none
◦ PlannedShutdownTime – Date of a planned shutdown, or null if none
◦ BgTasksStopped – Date value that indicates when background tasks stopped, of null if they have not stopped
◦ UserSessions – user sessions
◦ Components – Resources used by this server member. This is a list of ComponentInfo objects, each one of
which represents a lease on a resource, such as a messaging destination. The ComponentInfo.Type property
indicates the type of reserved resource, as a value from the ComponentType enumeration: WORK_QUEUE, SYSTEM,
106 chapter 5: General web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

BATCH_PROCESS, STARTABLE_PLUGIN, or MESSAGE_DESTINATION. For other fields on ComponentInfo, view the

class in Studio. The ComponentInfo.UniqueId property contains the unique ID for this component.
• UnassignedComponents – Unassigned resources as a list of ComponentInfo objects.

Clean and release resources after node failure

To clean and release resources, such as batch processes, plugins, message destinations, that are reserved by a
specified node, call the SystemToolsAPI web service method nodeFailed. Be aware, however, that if the node is
still running, this method can have a dangerous impact to data integrity and proper application behavior.
The method takes the following arguments.
• A String server ID
• A boolean argument called evenIfInCluster, which specifies whether to consider the node as failed if it is still
in the cluster.
You must ensure that the server referenced by the server ID is actually stopped if you set the evenIfInCluster
option to true. PolicyCenter does not prevent you from using this option if the server is still running. However, the
option overrides an important safety check on the server. It can produce unexpected and possibly negative results if
the server is running. Use the evenIfInCluster option only if both of the following are true: (1) The server in
question is no longer running and (2) the standard operation of the nodeFailed method failed due to the server
retaining its cluster membership.
The method has no return value.

Complete component failure

To complete a failed failover for a reservable resource, such as a messaging destination, call the SystemToolsAPI
web service method completeFailedFailover.

completeFailedFailover(componentType : ComponentType, componentId : String)

The componentType argument references a ComponentType enumeration value. Supported values are WORK_QUEUE,
SYSTEM, BATCH_PROCESS, STARTABLE_PLUGIN, MESSAGE_DESTINATION, and MESSAGE_PREPROCESSOR.
The componentId argument specifies the component's unique String ID.
The method has no return value.

Table import web service

The TableImportAPI web service provides tools for importing non-administrative data from staging tables into
operational tables in the PolicyCenter database. The table_import command-line tool wraps this API to provide a
straightforward way to use the web service. To import data from external sources, you first write a conversion tool to
populate the staging tables. Next, you use methods from this web service to check the integrity of those tables. You
cannot load data until these methods report no errors. Then, use one of the load methods to load data from the
staging tables into operational tables. PolicyCenter uses bulk data import commands to perform the load.
Most of the methods for this web service require the server to be at the MAINTENANCE run level. Before you use those
methods, start the server at the MAINTENANCE run level. Alternatively, use the SystemToolsAPI web service
setRunLevel method to set the server run level to MAINTENANCE. After the table import command completes, you
can set the server run level to MULTIUSER.
Some tasks are available as batch operations. Methods for batch operations return a process ID that you can check
for completion of the task. Use these methods to avoid holding a web transaction open for an indefinite period of
time. To check for completion of the batch process, you use the MaintenanceToolsAPI web service

General web services 107

Guidewire PolicyCenter 9.0.6 Integration Guide

batchProcessStatusByID method. The method returns a ProcessStatus object. To check the progress of the batch
process, use the following boolean properties.
• Starting – The batch process is initializing.
• Executing – The batch process is running.
• Complete – The batch process has finished.
• Success – The batch process completed successfully.
The ProcessStatus object also provides more detailed information about the batch process. For example, the
following code checks the status of an integrity check batch process.

var tiApi = new TableImportAPI()

var mtApi = new MaintenanceToolsAPI()
// Authenticate the APIs here
...
var tiBatchProcess = tiApi.integrityCheckStagingTableContentsAsBatchProcess(false, false,false,1)
...
try {
// Check the status
var status = mtApi.batchProcessStatusByID(new () { :Pid = tiBatchProcess.Pid })
if (status.StartingOrExecuting) {
...
} else {
print("Started at ${status.StartDate}, completed at ${status.DateCompleted}")
if (status.Success) {
print("Ran to completion, completing ${status.OpsCompleted} operation(s) with " +
"${status.FailedOps} failure(s)");
} else {
print("Failed to run to completion: ${status.FailureReason}. " +
"Completed ${status.OpsCompleted} operation(s) " +
"with ${status.FailedOps} failure(s) before terminating")
}
...
}
} catch (e) {
print("Failed to find process status: ${e.getClass()} " + e.Message)
}

For staging table actions that you can request from remote systems, refer to the following table.

Action TableImportAPI method and Description

Clear data from clearStagingTables

staging tables in Before using a conversion tool to load new data from an external source to staging tables in the database,
the database you typically clear the existing data from the staging tables. This synchronous method returns nothing.
Clear data from clearErrorTable
the error table Before running integrity checks on data in the staging tables, you typically clear existing load errors from the
in the database database. This synchronous method returns nothing.

Clear data from clearExclusionTable

the exclu‐ Before running integrity checks on data in the staging tables, you typically clear existing records from the
sion table in the exclusion table. This synchronous method returns nothing.
database
Perform checks integrityCheckStagingTableContentsAsBatchProcess
on the staging Before you load staging table data into operational tables, your staging table data must pass the integrity
tables to ensure checks that this method performs for PolicyCenter. This method creates entries in the error table for errors
that the data that it detects. This method returns a process ID that you can check for completion of the action.
will load into
operational ta‐
bles
Prepare to re‐ populateExclusionTableAsBatchProcess
move staging You can choose to remove the rows from staging tables that cause integrity checks to fail if you do not want
tables rows that to correct the errors. Populating the exclusion table marks these rows for removal. This method returns a
cause integrity process ID that you can check for completion of the action.
checks to fail

108 chapter 5: General web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

Action TableImportAPI method and Description

Delete da‐ deleteExcludedRowsFromStagingTablesAsBatchProcess

ta specified by Before rerunning integrity checks on data in the staging tables, you can remove records that contain errors
the exclu‐ from the staging tables. This method returns a process ID that you can check for completion of the action.
sion table from
the staging ta‐
bles
Encrypt data in encryptDataOnStagingTablesAsBatchProcess
the staging ta‐ If you have database columns that are encrypted, you must encrypt the data values in the staging tables
bles before before you load the data into operational tables. This method returns a process ID that you can check for
loading the da‐ completion of the action.
ta into opera‐
tional tables
Update data‐ updateStatisticsOnStagingTablesAsBatchProcess
base statistics To ensure the database performs the load operations effectively, update the statistics on the staging tables
on staging ta‐ before loading the data into operational tables. For an Oracle databas, this method also updates the indexes
bles on the staging tables. This method returns a process ID that you can check for completion of the action.
Load data from integrityCheckStagingTableContentsAndLoadSourceTablesAsBatchProcess
staging tables Prior to loading the data from the staging tables to operational tables, this method reruns integrity checks. If
into operational the checks pass, this method loads all staging table data into operational tables. This process performs any
tables after per‐ required data conversions. For example, placeholder values for foreign keys are converted to actual key val‐
forming checks ues. If this process encounters an unrecoverable error, it reverts the entire data load. If the load process
on the staging succeeds, it clears all data from the staging tables. This method returns a process ID that you can check for
tables completion of the action.
Load zone data integrityCheckZoneStagingTableContentsAndLoadZoneSourceTables
from staging ta‐ This method performs the same action as integrityCheckStagingTableContentsAndLoadSourceTables,
bles into opera‐ but loads only zone data. This synchronous method returns the result of the load operation.
tional tables af‐
ter performing
checks on the
staging tables
Get information getLoadHistoryReportsInfo
about complet‐ This synchronous method returns a String array containing summary information about the most recent
ed staging table calls to the TableImportAPI web service. The array members are in reverse chronological order. The number
operations of operations is specified by the argument to this method. An argument of 0 returns all available history.

Template web service

The TemplateToolsAPI web service enables an external system to list and validate document, email, and note
templates. The service also enables fields in a template descriptor file to be imported from CSV (comma-separated
value) text files.

List templates
The following web service methods retrieve a list of templates on the server. The list can be used to sanity-check the
arguments to the web service's validation methods.

listDocumentTemplates() : String
listEmailTemplates() : String
listNoteTemplates() : String

Each method returns a human-readable string that describes the templates available on the server.

Validate templates
The following methods validate either a single or all templates. Each method processes a specific type of template.
General web services 109
Guidewire PolicyCenter 9.0.6 Integration Guide

validateDocumentTemplate(templateID : String) : String

validateAllDocumentTemplates(): String

validateEmailTemplate(templateFileName : String, beanNamesAndTypes : NameTypePair[]) : String

validateAllEmailTemplates(beanNamesAndTypes : NameTypePair[]) : String

validateNoteTemplate(templateFileName : String, beanNamesAndTypes : NameTypePair[]) : String

validateAllNoteTemplates(beanNamesAndTypes : NameTypePair[]) : String

Each method accepts a String file name that specifies the template to validate, such as ReservationRights.doc.
The email and note methods also accept an array of NameTypePair objects. Each NameTypePair object contains a
parameter name and its type. Each property is specified as a String. The two properties are used to validate the
template placeholder.
Each method returns a human-readable string that describes the operations performed, plus any errors, if they
occurred.
The following validation tests are performed.
• Checks all Gosu ContextObject and FormField expressions in the descriptor. ContextObject expressions must
be defined in terms of the available objects. FormField expressions must be defined in terms of either available
objects or ContextObjects.
• Checks that the permissionRequired attribute is valid, if specified.
• Checks that the default-security-type attribute is valid, if specified.
• Checks that the type attribute is a valid type code, if specified.
• Checks that the section attribute is a valid section type code, if specified.
Each validation method has a counterpart that accepts a locale.

validateDocumentTemplateInLocale(templateID : String, locale : String) : String

validateAllDocumentTemplatesInLocale(locale : String) : String

validateEmailTemplateInLocale(templateFileName : String, beanNamesAndTypes : NameTypePair[], locale : String) : String

validateAllEmailTemplatesInLocale(beanNamesAndTypes : NameTypePair[], locale : String) : String

validateNoteTemplateInLocale(templateFileName : String, beanNamesAndTypes : NameTypePair[], locale : String) : String

validateAllNoteTemplatesInLocale(beanNamesAndTypes : NameTypePair[], locale : String) : String

Import form fields

The importFormFields method imports context objects, field groups, and fields from a CSV (comma-separated
values) text file into a specified template descriptor file.

importFormFields(contextObjectFileContents : String,
fieldGroupFileContents: String,
fieldFileContents : String,
descriptorFileContents : String) : TemplateImportResults

The method accepts the following arguments.

• contextObjectFileContents - The contents of a CSV file that specifies the context objects to import
• fieldGroupFileContents - The contents of a CSV file that specifies the field groups to import
• fieldFileContents - The contents of a CSV file that specifies the fields to import
• descriptorFileContents - The contents of the descriptor file
The method returns a TemplateImportResults object with fields for the newly-imported contents of the descriptor
file. The object also contains a human-readable string that describes the operations performed, plus any errors, if
they occurred.

Workflow web service

The WorkflowAPI web service enables PolicyCenter workflows to be controlled remotely. The built-in
workflow_tools command-line tool also uses the web service to provide local control of workflows.
110 chapter 5: General web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

Workflow basics
You can invoke a workflow trigger remotely from an external system using the invokeTrigger method.
Any time the application detects a workflow error, the workflow sets itself to the state TC_ERROR. When this occurs,
you can remotely resume the workflow using these APIs.
Refer to the following table for workflow actions that you can request from remote systems.

Action WorkflowAPI method and Description

Invoke a work‐ invokeTrigger

flow trigger Invokes a trigger key on the current step of the specified workflow, causing the workflow to advance to
the next step. This method takes a workflow public ID and a String value that represents the workflow
trigger key from the WorkflowTriggerKey typelist. To check whether you can call this workflow trigger,
use the isTriggerAvailable method in this interface (see later in this table). This method returns noth‐
ing.
Check wheth‐ isTriggerAvailable
er a trigger is avail‐ Check if a trigger is available in the workflow. If a trigger is available, it means that it is acceptable to
able pass the trigger ID to the invokeTrigger method in this web services interface. This method takes a
workflow public ID and a String value that represents the workflow trigger key from the
WorkflowTriggerKey typelist. It returns true or false.

Resume a sin‐ resumeWorkflow

gle workflow Restarts one workflow specified by its public ID. This method sets the state of the workflow to
TC_ACTIVE. This method returns nothing.

Resume all work‐ resumeAllWorkflows

flows Restarts all workflows that are in the error state. It is important to understand that this only affects work‐
flows currently in the error state TC_ERROR or TC_SUSPENDED. The workflow engine subsequently at‐
tempts to advance these workflows to their next steps and set their state to TC_ACTIVE. For each one, if
an error occurs again, the application logs the error sets the workflow state back to TC_ERROR. This
method takes no arguments and returns nothing.
Suspend a work‐ suspend
flow Sets the state of the workflow to TC_SUSPENDED. If you must restart this workflow later, use the
resumeWorkflow method or the resumeAllWorkflows method.

Complete a work‐ complete

flow Sets the state of a workflow specified by its public ID to TC_COMPLETED. This method returns nothing.

Zone data import web service

The ZoneImportAPI web service provides tools for importing zone data from comma-separated values (CSV) files
into database staging tables in the PolicyCenter database. The zone_import command-line tool wraps the API to
provide a straightforward way to use the web service. Guidewire recommends that you use the zone_import tool.
After importing the data into staging tables, you use the table import (TableImportAPI) web service to load the
staging table data into the operational tables in the database. PolicyCenter uses bulk data import commands to
perform the data load.
For zone data actions that you can request from remote systems, refer to the following table.

Action ZoneImportAPI method and Description

Clear zone data from clearProductionTables
operational tables in Before loading new zone data from staging tables to the operational tables in the database, you
the database clear the existing zone data from the operational tables. The method takes an optional two‐letter
country code. Provide this value if you plan to load zone data for a subset of zones. The method
returns nothing.

General web services 111

Guidewire PolicyCenter 9.0.6 Integration Guide

Action ZoneImportAPI method and Description

Clear zone data from clearStagingTables
staging tables in the da‐ Before loading new zone data from comma‐separated values (CSV) files to staging tables in the data‐
tabase base, you clear the existing zone data from the staging tables. The method takes an optional two‐
letter country code. Provide this value if you plan to load zone data for a subset of zones. The meth‐
od returns nothing.
Import zone data from importToStaging
CSV files to staging ta‐ Use this method to load new zone data from a CSV file to staging tables in the database. The method
bles in the database takes two String parameters: a two‐letter country code and a path to the CSV file. A boolean flag
parameter specifies whether to clear data for this country from the staging tables. The method re‐
turns the number of rows that the method loaded into staging tables.

112 chapter 5: General web services

chapter 6

Account and policy web services

PolicyCenter provides web services that enable you to accept changes to accounts and policies from external
systems.

Date‐ and time‐related DTOs

Several Gosu types related to date and time are based on XSD schemas. Examples include XSDDate and
XSDDateTime. These XSD-based types can be used as web service DTOs. To represent a valid date or time,
however, the relevant time zone must be specified in the web service call. Failure to specify a time zone results in an
IllegalStateException.
The Gosu XSD-based types that require a time zone when used as a DTO are listed below.
• XSDDate
• XSDDateTime
• XSDGDay
• XSDGMonth
• XSDGMonthDay
• XSDGYear
• XSDGYearMonth
• XSDTime
The Gosu XSD-based types can be constructed from a java.lang.String object that conforms to the XML Schema
date/time formats specified in the W3C XML Schema specification.

construct(s : String)

To convert an XSD-based type to a String, use the object's toString method.

An XSD-based date/time object can also be constructed from a java.util.Calendar object.

construct(cal : Calendar, useTimeZone : boolean)

If the constructor's useTimeZone argument is true, the constructed object inherits the time zone specified in the
Calendar object.
Conversely, a Gosu XSD-based date/time object can be converted to a java.util.Calendar object by calling the
object's toCalendar method. Calendar fields that are not included in the XSD-based object are set to default
values. Two method signatures are supported.
Account and policy web services 113
Guidewire PolicyCenter 9.0.6 Integration Guide

toCalendar() : Calendar
toCalendar(tzDefault : TimeZone) : Calendar

If the Gosu object does not specify a time zone value, calling the toCalendar method signature with no arguments
results in an IllegalStateException.

Account web services

Use the AccountAPI web service to add documents to accounts, add notes to accounts, and find account public IDs.

Add documents to an account

Use the addDocumentToAccount method to add a document to an account. The method is relatively straightforward,
taking an account’s public ID and a Document object and adds the document to the account. PolicyCenter returns the
public ID of the newly added document.

Add notes to an account

Use the addNoteToAccount method to add a note to an account. The method is relatively straightforward, taking an
account’s public ID and a Note object and adds the document to the account. PolicyCenter returns the public ID of
the newly added note.

Find accounts
There are two ways to find accounts, either by account number or by complex criteria.
Use the findAccountPublicIdByAccountNumber method to find an account’s public ID given its account number.
It returns the public ID of the account, or null if there is no such account.

accountPublicID = accountAPI.findAccountPublicIdByAccountNumber("ABC-00001");

In contrast, the findAccounts method is more robust and allows you to search for multiple accounts that fit certain
criteria. For example, you could find accounts that match a certain account status or from a certain city. To use it,
create a new AccountSearchCriteria object, fill in properties that match what you want to search for, and pass it
to findAccounts.

AccountSearchCriteria acs = new AccountSearchCriteria();

acs.setCity("San Francisco");
accounts = accountAPI.findAccounts(acs);

// get first result in the array...

accountPublicID = accounts[0];

Assign activities
You can remotely add and assign an activity for an account by using the addAndAutoAssignActivityForAccount
method. PolicyCenter generates an activity based on the activity type and the activity pattern code and then auto-
assigns the activity.
It takes a String account public ID, an ActivityType object, a String activity pattern code, a String activity
pattern code, and an array of activity properties of type ActivityField. The method has no return value.

Add contacts to an account

You can remotely add a contact to an account by using the addContactToAccount method. It takes a String
account public ID and an account contact of type AccountContact.
The method adds the given account contact to the account, and returns the public ID of the new AccountContact.
114 chapter 6: Account and policy web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

Add location to an account

You can remotely add a location to an account by using the addLocationToAccount method. It takes a String
account public ID, an AccountLocation object, and returns the String public ID of the new AccountLocation
entity.

Retrieve account numbers

You can remotely get the location to an account by using the getAccountNumber method. It accepts a String
account public ID and returns the associated String account number.

Check for active policies

You can remotely check for active policies for the account by using the hasActivePolicies method. A policy is
considered active if it has any PolicyPeriod entities that are issued and are effective at the current date and time.
The method accepts a String account public ID. The method returns true if the account has active policies,
otherwise, false.

Insert accounts
You can remotely insert an account by using the insertAccount method. The method accepts an ExternalAccount
entity, which is a parallel to the Account entity. The ExternalAccount entity contains a subset of the properties on
the internal non-SOAP Account entity due to the necessity to simplify the entity for serialization across the SOAP
protocol.
After importing the external account into PolicyCenter as an Account entity, PolicyCenter returns the resulting
String public ID of the new Account entity.

Merge accounts
You can remotely merge two accounts by using the mergeAccounts method. This task is available from this web
service but is not provided in the PolicyCenter reference implementation in the user interface. You must decide
which account is the merged account and which account to discard after the merge is complete.
The method takes two String account public IDs. The first public ID represents the source account to be copied
then discarded afterward. The second public ID represents the destination account to have the source destination
account merged with it. The method returns nothing.

See also
• To customize the operations that are performed after merging accounts, see “Account plugin details” on page
151.

Transfer policies
You can remotely transfer policies from one account to another by using the transferPolicies method. Provide an
array of String policy public IDs, the public ID of the source account, and the public ID of the destination account.

See also
• To customize the operations that are performed after transferring accounts, see “Account plugin details” on page
151.

Update account contacts

You can remotely update the contact information for account contacts by using the updateAccountContact method.
You provide a String account public ID, a String contact display name, and account contact information
encapsulated in an AccountContactInfo entity. Notice that this argument is the AccountContactInfo entity and
Account and policy web services 115
Guidewire PolicyCenter 9.0.6 Integration Guide

not the AccountContact entity. AccountContactInfo simply encapsulates an Address entity in its
PrimaryAddress property. Populate an Address entity with the new information and set the PrimaryAddress
property on the AccountContactInfo entity.
PolicyCenter looks at the specified account and finds the contact with the provided display name. PolicyCenter then
updates the contact with the information in the AccountContactInfo.

Job web services

Use the JobAPI web service to add activities to jobs or to withdraw preempted jobs.
The primary methods of this web service add new activities to jobs. They differ in how groups and users are
assignment new activities.
• addActivityFromPatternAndAssignToUser
• addActivityFromPatternAndAssignToQueue
• addActivityFromPatternAndAutoAssign
Specify the activities that you add using activity patterns. Users define activity patterns in the administrative data of
your PolicyCenter instance. An activity pattern is a template that sets default values for new activities.

Common parameters in the job APIs

The common parameters for the primary methods are listed below.
• Public ID of the job. To get the public ID, use the helper method findJobPublicIdByJobNumber.
• Public ID of the activity pattern. To get the public ID, use the method
ActivityPattern.finder.getActivityPatternByCode("pattern-code").
• Activity fields, as a gw.webservice.pc.pc900.gxmodel.activitymodel.types.complex.Activity object.
Use an instance of the XML type Activity to initialize activity fields that activity patterns do not cover.
Note the following characteristics about the parameters to the Job APIs.
• Activity patterns must not be designated “automated only.”
• Activity patterns must be available for the type of jobs to which you try to add the activities. Otherwise,
Guidewire throws the exception EntityStateException.
• Users of the web services user must have the permissions VIEW_JOB and CREATE_ACTIVITY. Otherwise,
Guidewire throws the exception PermissionException.
• Parameters, such job IDs, activity pattern IDs, user IDs, queue IDs, and group IDs, must refer to existing entity
instances. Otherwise, Guidewire throws the exception DataConversionException.

Helper methods of the job APIs

The JobAPI web service provides the following helper methods.
• findJobPublicIdByJobNumber – Given a job number, returns the public ID of the job. Use the public ID as a
parameter to other methods of the Job APIs.
• withdrawJob – Withdraws preempted jobs.

Policy cancellation and reinstatement web services

Use the CancellationAPI and the ReinstatementAPI web services to start policy cancellation and policy
reinstatement jobs. These web services are WS-I compliant.
PolicyCenter starts some types of cancellations.
• Cancellation as part of a rewrite request
• Cancellation at the insured’s reques
• Cancellation because the insured provided false information in their application or violated the contract
• Cancellation because the insured chooses not to take a renewal and the renewal might already be bound
116 chapter 6: Account and policy web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

There are other types of cancellations that the billing system or other integration systems initiate. For example,
cancellation for non-payment. If the billing system detects overdue invoices, the billing system starts a delinquency
process and tells PolicyCenter to cancel the policy.
There are two ways the billing system can tell PolicyCenter to cancel a policy.
• Cancel the policy as of a certain date – PolicyCenter sets the policy to pending cancellation within PolicyCenter
and cancels automatically on the given date unless the application receives a rescind command before that date.
• Cancel the policy as soon as possible – This is similar to the previous approach described but PolicyCenter uses
internal notification lead time logic to determine the actual cancellation date.
PolicyCenter supports both approaches based on the cancellation date you pass to the API.

See also
• For more information about circumstances in which PolicyCenter might trigger cancellation or reinstatement,
refer to “Policy period management” on page 502.

Begin a cancellation
An external system can begin a cancellation in PolicyCenter with the beginCancellation method on
CancellationAPI.

beginCancellation(String policyNumber, Calendar cancellationDate, boolean recalculateEffDate,

CancellationSource cancellationSource, ReasonCode reasonCode, CalculationMethod refundCalcMethod,
String description, String transactionId)

To begin cancellation, you must specify a reason in a ReasonCode enumeration to indicate fraud, eligibility issues,
and so on. Instead of passing the reason code directly, a CancellationSetup entity encapsulates this enumeration.
The method returns the public ID of the cancellation job.
The parameters are described below.
• Policy number, as a String
• Cancellation date, as a Calendar object
• Recalculate effective date (recalculateEffDate), as a boolean
• Cancellation source typecode, carrier (insurer initiated cancel) or insured (the insured initiated cancel)
• Reason code typecode, as a ReasonCode value
• Refund calculation method, as a CalculationMethod
• Description (notes) associated with this cancellation, as a String
• Transaction ID to associate with this change
If you set recalculateEffDate to false, starts a Cancellation job effective on the cancellation date. or the given
policy in PolicyCenter (this date will also be the effective date of the new cancellation policy period). In this case,
the caller must check for any legal requirements for the cancellation date. If recalculateEffDate is set to true,
PolicyCenter calculates the earliest date for the cancellation to meet all legal requirements. PolicyCenter uses that
date if it is after the cancellation date. In this case, the caller can set the cancellationDate to today to get the
policy period cancelled as soon as possible.
The following Java example cancels a policy.

String jobNumber = cancellationAPI.beginCancellation( "ABC:123",

cancellationDate.toCalendar(), true, CancellationSource.TC_CARRIER,
ReasonCode.TC_NONPAYMENT, CalculationMethod.TC_PRORATA, "Some Description", "External1235")

Rescind a cancellation
Rescind a cancellation with the rescindCancellation method.
The method has two versions.
• One version rescinds a policy cancellation with a reason as a ReasonCode typecode and a cancellation source as a
CancellationSource typecode. The reason typecode indicates a payment-related reinstatement with the value
Account and policy web services 117
Guidewire PolicyCenter 9.0.6 Integration Guide

payment or another reason with the value other. The cancellation source typecode indicates that the insurer
initiated the cancellation with the value carrier or the insured initiated the cancellation with the value insured.

void rescindCancellation(java.lang.String policyNumber,

java.util.Calendar effectiveDate, CancellationSource cancellationSource, ReasonCode reasonCode)

For example, the following sample code rescinds a cancellation with a reason code.

cancellationAPI.rescindCancellation("ABC:123", new Date(),

CancellationSource.TC_CARRIER, ReasonCode.TC_NONPAYMENT)

• The other version rescinds an in-progress policy cancellation with the job number of a cancellation. For example,
the following sample code rescinds a cancellation with a job number only.

void rescindCancellation("ABC:123")

Find a cancellation
In some cases, an external system wants to rescind a cancellation but does not have the job number for the
cancellation. In these cases, use the findCancellations method on the CancellationAPI web service to get the
job number. The method returns a list of job numbers for matching cancellations. You can use these results to decide
which cancellation you want to rescind. Next, call the separate rescindCancellation method and pass it the job
number of the cancellation job to rescind.
The findCancellations method takes the following arguments in the following order.
• Policy number, as a String
• Cancellation date, as a java.util.Calendar object. PolicyCenter finds cancellations effective on that date or
after that date.
• Cancellation source, as a CancellationSource typecode
◦ carrier – Cancellation initiated by insurer
◦ insured - Cancellation initiated by insured
• Reason code, as a ReasonCode typecode
◦ nonpayment – Payment not received
◦ fraud – Fraud
◦ flatrewrite – Policy rewritten or replaced (flat cancel)
◦ midtermrewrite – Policy rewritten (mid-term)
• Calculation method, as a CalculationMethod typecode
◦ flat – Flat
◦ prorata – Pro rata
◦ shortrate – Short rate
The following example code demonstrates how to call this method from Java.

Calendar cancellationDate = Calendar.getInstance();

String jobNumber;
String myPolicyNumber = "abc:123";
var foundJobNumbers = cancellationAPI.findCancellations(myPolicyNumber, cancellationDate,
CancellationSource.TC_carrier, ReasonCode.TC_nonpayment, CalculationMethod.TC_prorata);

Reinstate a policy
Use the ReinstatementAPI web service to start a reinstatement job for a policy that is canceled and that you want to
put it back in-force. The reinstatement effective date is always the cancellation date. To create a gap in coverage, a
user must start a policy rewrite job manually through the PolicyCenter interface.
118 chapter 6: Account and policy web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

The ReinstatementAPI web service has a single method called beginReinstatement. The method accepts the
following arguments.
• Policy number as a String
• Reinstatement code as a ReinstateCode typecode
The method returns a job number for the new reinstatement job.
The following example code demonstrates how to call this from Java.

reinstatementAPI.beginReinstatement( "ABC:1234", ReinstateCode.TC_payment );

Submission web services

Use the SubmissionAPI web service to start draft and quote submissions for policy renewals from external systems.

Passing in external policy period data for submissions

To start submission jobs in PolicyCenter, the SubmissionAPI web service accepts data that populates PolicyCenter
policy periods, which submission jobs use. The entire set of external data comes in the policyPeriodData
parameter, defined as a String. You can use any text-based format in your implementation that you can parse, for
example XML format.
To parse the policyPeriodData parameter, the methods on the SubmissionAPI web service parse the String data
as XML by using the Guidewire XML model (GX model) definition. The GX Model is available at the location
gw.webservice.pc.pc900.gxmodel.policyperiodmodel. Then the code calls the populatePolicyPeriod
enhancement method on the XML object. The enhancement method is implemented in
gw.webservice.pc.pc900.gxmodel.PolicyPeriodModelEnhancement.
If you want to add line-specific populating or validation code, modify the populatePolicyPeriod enhancement
method. If you need to use a different XSD or GX model, modify the SubmissionAPI web service implementation
class directly.

Start a submission
The startDraftSubmission method create a submission and leaves it in a draft state.

function startDraftSubmission(accountNumber : String, productCode : String, producerCodeId : String,

policyPeriodData : String, parseOptions : String) : String

The method accepts the following arguments.

• Account number as a String
• Product code as a String
• Producer code public ID as a String
• XML representation of policy period data from the external system as a String
• Set of parse options as a String that controls how your implementation parses the policy period data
The method returns a String that contains the job number of the submission.

Start a submission and generate a quote

The quoteSubmission method creates a submission and attempts to generate a quote.

function quoteSubmission(accountNumber : String, productCode : String, producerCodeId : String,

policyPeriodData : String, parseOptions : String) : String

Account and policy web services 119

Guidewire PolicyCenter 9.0.6 Integration Guide

The method accepts the following arguments.

• Account number as a String
• Product code as a String
• Producer code public ID as a String
• XML representation of policy period data from the external system as a String
• Set of parse options as a String that controls how your implementation parses the policy period data
The method returns a String that contains the job number of the submission.

Producer web services

The ProducerAPI web service manages producer codes, agencies, and branches. Agencies are a type of
organization. Branches are a type of group. Branch objects are distinguished from regular group objects by having a
non-null value for the BranchCode attribute.
Refer to the WS-I implementation class in Studio for details of the methods on this web service.

gw.webservice.pc.pcVERSION.community.ProducerAPI

Remember the following characteristics about producer hierarchies.

• Note that each Organization in turn may have an associated tree of Group entities. For a Group, ancestors
means the group’s ancestors in its Group tree. Groups and producer codes can be arranged hierarchically, but
organizations, including agencies, are not arranged hierarchically. For this web service, uses of the PolicyCenter
Organization entity use an instance of OrganizationDTO, which is a Gosu class in package
gw.webservice.pc.pcVERSION.community.datamodel.
• Every ProducerCode is associated with a single Branch, and there is a many-to-many correspondence between
producer codes and agencies and their associated groups.
• The Agency-ProducerCode constraint limits the associations between agencies and producer codes.

Product model web services

You can use the PolicyCenter product model web service ProductModelAPI to do several things.
• Update the PolicyCenter product model on a running development server from the local file system XML
representation of the product model. The product model lists all the insurance products that an insurance
company sells. Typically, you would manage the product model using the Product Designer application.
• Update system tables on a running development server based on local file system representation of the system
tables.
• Query the server for product model information. Generally speaking, it is best to identify product model objects
using the property CodeIdentifier, not PublicID. ProductModelAPI web service primarily identifies product
model objects using the property PublicID. From an external system, you can get the PublicId for a product
model object by calling the ProductModelAPI web service method getPublicIdForCodeIdentifier. If you
develop your own web services that manipulate product model types, Guidewire recommends using the property
CodeIdentifier for arguments and return values.

Synchronize product model in database with file system XML

The most important method in the ProductModelAPI web service is the synchronizeProductModel method. Use
the synchronizeProductModel method to update the PolicyCenter product model in memory from the local file
system XML representation of the product model.
The Product Designer application uses this API to reload the PolicyCenter server in-memory product model after
modifying the local XML files.
Suppose you plan to introduce a new insurance product such as a new type of auto insurance coverage. You may
want to change the PolicyCenter product model in multiple ways. However, never push product model changes
directly to the production server.
120 chapter 6: Account and policy web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

Instead, test changes on different instances of the development server. Ensure your product model changes are
correct before deploying to the production server.
To maintain business data integrity, PolicyCenter forbids some types of changes to product model entity properties
on production servers. Some product model changes are impossible to undo after you deploy the changes to a
production server. For example, a coverage term with the value 100 cannot change to the value 200 on a production
server. That would fundamentally change the meaning of any policies that used that coverage term. This is a
difference between working with a development server which has no customer data and a production server where
customer data is bound by legal and customer service implications.
The development server must have an identical PolicyCenter configuration as the production server, except for the
following configuration settings.
• On the production server, set the server environment property env to prod (production).
• On the development server, set the server environment property env to a value other than prod.
Fully test product model changes on a development server. PolicyCenter protects the business and legal integrity of
customer data in a special way for production servers. Deploying unacceptable property changes to existing product
model entities prevents PolicyCenter from starting in production environment.
If you call the ProductModelAPI web service on a server whose system environment variable env is set to the value
prod, the web service throws an exception.
Use this API in the following cases.
• If you need to revert the product model to the product model XML files stored on the server instead of the data
persisted in the database.
• If you change a development server’s local file resources in some other way during development due to source
control changes or hand-editing of files.
Use this API if you change a development server’s local file resources in some other way during development due to
source control changes or hand-editing of files.
Do not use this API if the file did not change since server startup.

Synchronize system tables

Another ProductModelAPI web service method is synchronizeSystemTables. Use the
synchronizeSystemTables method to modify the PolicyCenter database’s system tables from the local file system
XML representation of system tables. This method takes no arguments, and returns nothing.
The Product Designer application uses this API to reload the database system tables into PolicyCenter after
modifying the local XML files.
If you call this API on a server whose system environment variable env is set to the value prod, the web service
throws an exception.
Use this API if you change a development server’s local file resources in some other way during development due to
source control changes or hand-editing of files.
Do not use this API if the files did not change since server startup.

Query the database for product model information

On a running PolicyCenter server, you can query the database for product model information.
There are multiple types of queries you can perform.
• To return the list of available questions for a specified policy period, call the ProductModelAPI web service
method getAvailableQuestions. The return type is a list of question sets, as the type List<QuestionSet>.
• To return the list of available clauses (such as coverages, conditions, and exclusions) for a specified policy
period, call the ProductModelAPI web service method getAvailableClausePatterns. The return type is a list
of clause patterns, as the type List<ClausePattern>.
Account and policy web services 121
Guidewire PolicyCenter 9.0.6 Integration Guide

The arguments are the same for both methods.

• lookupRoot – the information about the entity to search for availability, as a LookupRootImpl object. The
LookupRootImpl object encapsulates the search criteria and contains the following properties:
◦ LookupTypeName – the String lookup type name
◦ PolicyLinePatternCode – the String policy line pattern code
◦ CovTermPatternCode – the String coverage term pattern code
◦ ProductCode – the String product code
◦ JobType – the job type as a Job typekey
◦ Jurisdiction – a jurisdiction as a Jurisdiction object
◦ PolicyType – a policy type as a BAPolicyType object
◦ UWCompanyCode – an underwriter company code as a UWCompanyCode object
◦ IndustryCode – a String industry code
◦ VehicleType – a vehicle type as a VehicleType object
• offeringCode – a String offering code
• lookupDate – the date to look up as a standard Date object
Exceptions that the methods may throw are listed below.
• SOAPException – If communication fails
• RequiredFieldException – If any required field is null
• BadIdentifierException – If the API cannot find an instance with specified ID

Policy web services

To control policy period referral reasons and activities from an external system, use the PolicyAPI web service.

Add a referral reason

The PolicyAPI method addReferralReasonToPolicyPeriod adds a period referral reason to the policy period. For
example, if a claim management system notices a lot of claims on a policy, it could notify PolicyCenter of the issue.
PolicyCenter could associate the issue with the appropriate policy period. The renewal workflow could set risk-
related properties on the policy period before authorizing renewal of that policy.

function addReferralReason(policyId : String, issueTypeCode : String, issueKey : String,

shortDescription : String, longDescription : String, value : String) : String

The method accepts the following arguments.

• Policy ID (String)
• Issue type code (String)
• Issue key (String)
• Short description (String)
• Long description (String)
• Referral reason, which must be valid for the comparator of the UWIssueType.
The method returns the public ID of the new or existing referral reason. PolicyCenter sets the status of the new
referral reason to Open.

Close a referral reason

The closeReferralReason method closes a referral reason.

function closeReferralReason(policyId : String, issueTypeCode : String, issueKey : String)

122 chapter 6: Account and policy web services

 Guidewire PolicyCenter 9.0.6 Integration Guide

The method accepts the following arguments.

• Policy period public ID
• Code that matches the UWIssueType.Code of the referral reason to close
• Issue key identifier for the referral reason
The method has no return value.

Add activity from pattern

There are several methods for adding activities from patterns and assigning them.

Add activity and auto‐assign

To add an activity using an activity pattern from an external system and auto-assign the activity, call the IPolicyAPI
web service method addActivityFromPatternAndAutoAssign.

function addActivityFromPatternAndAutoAssign(policyId : String, activityType : ActivityType,

activityPatternCode : String, activityFields : Activity) : String {

The activityfields argument contains an Activity object, which is not the Guidewire entity. Instead, it is a XML
type defined using the Guidewire XML (GX) modeler.
Set the important properties for a new activity, such as the Subject and the Description properties. PolicyCenter
copies over non-null fields form the activityfields argument to the new activity.
The addActivityFromPatternAndAutoAssign method performs the following operations.
1. Try to generate an activity from the specified activity pattern.
2. Initialize the activity with the following fields from the activity pattern: Pattern, Type, Subject,
Description, Mandatory, Priority, Recurring, and Command.
3. Calculate the target date using the following properties from the pattern: TargetStartPoint, TargetDays,
TargetHours, and TargetIncludeDays.
4. Calculate the escalation date using the following properties from the pattern EscalationStartPt,
EscalationDays, EscalationHours, and EscalationInclDays. If the activity does not use those properties,
PolicyCenter does not set the target and/or escalation date. If the target date after the escalation date, then
PolicyCenter sets the target date to the escalation date.
5. PolicyCenter sets the activity policy ID to the specified policy ID. The previous user ID for the activity (the
previousUserId property) is set to the current user.
6. PolicyCenter assigns the newly created activity to a group and/or user using the Assignment Engine.
This step is the auto-assignment step.
7. PolicyCenter saves the activity in the database.
8. The method returns the ID of the newly created activity.

Add activity and assign to user

If you want to assign the new activity to a specific group and user, call the
addActivityFromPatternAndAssignToUser method.

function addActivityFromPatternAndAssignToUser(policyId : String, userId : String, groupId : String,

activityType : ActivityType, activityPatternCode : String, activityFields : Activity) : String {

The method performs the same operations as the related addActivityFromPatternAndAutoAssign method, except
that it assigns the activity to the specified group and user.

Add activity and assign to queue

If you want to assign the new activity to a specific group and user, call the
addActivityFromPatternAndAssignToQueue method.
Account and policy web services 123
Guidewire PolicyCenter 9.0.6 Integration Guide

function addActivityFromPatternAndAssignToQueue(policyId : String, queueId : String,

activityType : ActivityType, activityPatternCode : String, activityFields : Activity) : String {

The method performs the same operations as the related addActivityFromPatternAndAutoAssign method, except
that it assigns the activity to the specified queue.

Policy period web services

To add notes to policies and policy periods and to add documents to policy periods, use the PolicyPeriodAPI web
service.
The methods of the PolicyPeriodAPI web service all accept the public IDs of policies and policy periods as String
parameters. In addition, they accept instances of GX models for notes or documents as String parameters. A GX
model contains an entity’s property data in XML format.

Add notes to policies and policy periods

Use the addNoteToPolicy method to add a note to a policy. It takes the public ID of a policy, as a String, and a GX
model of a Note.
Use the addNoteToPolicyPeriod method to add a note to a policy period. It takes the public ID of a policy period,
as a String, and a GX model of a Note.

Add documents to policy periods

To add a document to a policy period, call the PolicyPeriodAPI web service method
addDocumentToPolicyPeriod. The method accepts the following arguments.
• Public ID of a policy period
• GX model of a Document.
The method returns the public ID of the new Document entity instance.

Policy earned premium web services

To calculate earned premiums from an external system, use the web service PolicyEarnedPremiumAPI. It has a
single method called calcEarnedPremiumByPolicyNumber, which calculates the earned premium for a given policy
number. The method accepts the following arguments.
• A String Policy number
• A Date object on which the policy to find is in effect. If the policy has multiple terms, the date determines which
policy term to use. The method selects the most recent version of the policy for the given term.
• The date as of which to calculate earned premium amounts
• A Boolean value (includeEBUR) that specifies whether to include data that is earned but not reported (EBUR).
The method returns a list of PolicyEarnedPremiumInfo objects, one for each line of business on the policy. Each
PolicyEarnedPremiumInfo contains two properties.
• LOB – the line of business code as a String value
• EarnedPremium – the earned premium as a BigDecimal value
For EBUR data, it is standard practice for premium reporting policies to use actual reported premium rather than a
pro rata estimate of estimated premium as the basis for earning. However, suppose PolicyCenter received monthly
premium reports through the end of May (received June 15) and now wants to do June month-end earning accruals
as of July 5. There is no report for premiums earned in June, because it is not expected until July 15). If you include
EBUR data, PolicyCenter estimates how much of the policy premiums are earned during this period of elapsed
coverage but with no actual premium report. After the last report is received or a final audit is complete, no portion
of the period remains unreported.
124 chapter 6: Account and policy web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

The includeEBUR parameter interacts in a special way with the status of the policy as a reporting policy.
• If includeEBUR is true and the policy is not a reporting policy, the calcEarnedPremiumByPolicyNumber
method returns an error.
• If the policy is a reporting policy but final audit is complete, PolicyCenter treats the includeEBUR parameter as if
it were false even if you passed true.

Import policy web services

To import policies from XML data from an external system, use the PolicyChangeAPI web service.
There is one method called quoteSubmission, which you can call to quote a submission in PolicyCenter.
The quoteSubmission method accepts the following arguments.
• An account number
• The product code, such as PersonalAuto or WorkersComp
• A producer code public ID
• A policy period data object, which is XML data
• Parse options to pass to XML parser
Within PolicyCenter, the format of the XML must conform to the structure defined by the GX model in the
following file.

gw.webservice.pc.pcVERSION.gxmodel.policyperiodmodel

The method returns an object of type QuoteResponse, which is a Gosu class that contains the following properties.
• JobNumber – Job number of the new job
• Errors – Any errors as an array of String objects

Policy change web services

To start policy change jobs from an external system, use the PolicyChangeAPI web service.
Policy change jobs modify in-force policies. Policy changes range from simple location changes to complex
coverage changes. Policy change jobs often require new quotes and bindings of policy periods.
The PolicyChangeAPI web service has two methods. Both take the following parameters:
• Policy number as a String
• Effective date as a Date
Both methods return the JobNumber property of the new job. The methods differ in whether the policy change is
quoted and bound automatically by the web service or manually by a user.

See also

• Application Guide

Starting an automatic policy change job

Use the startAutomaticPolicyChange method to start a policy change job that attempts to quote the change and
bind the policy automatically. If errors occur, users complete the policy changes manually through the PolicyCenter
interface.
You can modify the default behavior by changing the implementation of PolicyChangeProcess.startAutomatic.
An actual workflow can be started with this method to control the job’s progress.
Account and policy web services 125
Guidewire PolicyCenter 9.0.6 Integration Guide

Starting a manual policy change job

Use the startManualPolicyChange method to start a policy change job that waits in draft mode for a user to quote
and finish it manually. The method does not attempt to quote and bind the change automatically.

Specifying what policy data to change

In the default configuration, the methods of the PolicyChangeAPI web service do not change any policy data. You
must add your own methods to change policy data.
PolicyCenter updates policy contacts from account contacts automatically after a job starts. You can use this API to
trigger a policy change job. The API pulls in the latest version of each PolicyContact object from its associated
AccountContact object.

Policy renewal web services

The PolicyRenewalAPI handles policy renewal requests received from external systems. The service is located in
the package gw.webservice.pc.VERSION.job.

Start renewals on existing policies

The startRenewals method of the PolicyRenewalAPI web service starts renewals on one or more existing
PolicyCenter policies.

startRenewals(policyNumbers : String[])

The policyNumbers argument is an array of policy numbers that reference existing policies in PolicyCenter. If a
referenced policy does not exist in PolicyCenter, a BadIdentifierException is thrown and any subsequent policies
in the array are not processed.
The method has no return value.
The method starts a renewal job for each referenced policy. The entries in policyNumbers are processed in
sequence. When a successful renewal is created, it is committed to the database. No gap in coverage exists between
the original policy period and its renewal.

Import a policy for renewal

The startConversionRenewal method of the PolicyRenewalAPI web service starts a renewal for a single policy.
The policy does not yet exist in PolicyCenter, but is imported from an external system as part of the method's
renewal process.

startConversionRenewal(accountNumber : String,
productCode : String,
producerCodeId : String,
policyNumber : String,
policyPeriodData : String,
changesToApply : String,
parseOptions : String,
basedOnEffectiveDate : String,
basedOnExpirationDate : String) : String

The method accepts the following arguments.

• accountNumber - Reference to an existing PolicyCenter account. If the account does not exist in PolicyCenter, a
BadIdentifierException is thrown.
• productCode - Reference to an existing PolicyCenter product code, such as PersonalAuto or WorkersComp. If
the product does not exist, a BadIdentifierException is thrown.
• producerCodeId - Reference to an existing PolicyCenter producer code. If the producer code does not exist, a
BadIdentifierException is thrown.
126 chapter 6: Account and policy web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

• policyNumber - The unique ID number to assign to the imported policy. If the argument is null or references an
existing PolicyCenter policy, the method generates a new and unique policy ID number.
• policyPeriodData - The policy period data to import. The String contents are parsed as XML that conforms to
the PolicyCenter PolicyPeriodModel GX model. Load the GX model in Studio to view its structure.
• changesToApply - Not used in the base configuration. Custom implementations can use the argument to
reference settings in the renewal policy period that differ from the legacy imported period.
• parseOptions - Not used in the base configuration. Custom implementations can use the argument for their own
purposes.
• basedOnEffectiveDate - The effective date of the legacy imported policy period.
• basedOnExpirationDate - The expiration date of the legacy imported policy period. This date is also used as the
effective date for the new imported renewal policy period. There is no gap in coverage between the legacy
imported policy period and the renewal period.
If the accountNumber, productCode, or producerCodeId do not exist in PolicyCenter, the policy is not imported.
The imported policyPeriodData does not support attaching Note or Document objects to the renewal policy period.
Note and Document objects can be attached to the renewal policy period after it has completed the renewal process.
The basedOnEffectiveDate value is passed to the Effective Time plugin's getConversionRenewalEffectiveTime
method for processing.
The basedOnExpirationDate value is passed to the Effective Time plugin's
getConversionRenewalExpirationTime method for processing.
The method creates a new policy on the specified account. Also, a new policy period is created and associated with
the new policy. Finally, a renewal job is started for the new policy period. The renewal is in draft mode and is not
bound. If the operation fails, the method throws a DataConversionException.
The method returns the renewal job's ID number as a String.

Policy renewal methods for billing systems

Billing systems use the PolicyRenewalAPI web service to send confirmation of renewals to PolicyCenter. Renewals
can be configured to operate with or without renewal confirmation.

See also
• “Billing implications of renewals or rewrites” on page 489

Confirm a policy term

A billing system can notify PolicyCenter that an insured has confirmed a renewal. Confirmation usually takes the
form of the insured submitting a payment for the renewal.
The confirmTerm method of the PolicyRenewalAPI web service confirms a policy term.

confirmTerm(policyNumber : String, termNumber : int, transactionId : String)

The method accepts the following arguments.

• policyNumber - Specifies the number of the confirmed policy
• termNumber - Specifies the number of the confirmed term
• transactionId - Unique transaction ID to use for the bundle
The policyNumber and termNumber arguments cannot be null. They must reference a bound and unarchived policy
term.
The method has no return value.
The method calls the IBillingSystemPlugin method updatePolicyPeriodConfirmed. In the base configuration,
the plugin method sets the specified policy term's TermConfirmed field to true.
Account and policy web services 127
Guidewire PolicyCenter 9.0.6 Integration Guide

Notify PolicyCenter of receipt of payment for renewal

The notifyPaymentReceivedForRenewalOffer method of the PolicyRenewalAPI web service notifies
PolicyCenter that the billing system has received payment for a renewal offer.

notifyPaymentReceivedForRenewalOffer(offerID : String,
selectedPaymentPlanCode : String,
paymentAmount : MonetaryAmount,
transactionId : String) : String

The method accepts the following arguments.

• offerID - Unique ID of the renewal offer. Cannot be null. The relevant policy period term must not be archived.
• selectedPaymentPlanCode - Billing payment plan code
• paymentAmount - Self explanatory
• transactionId - Unique transaction ID to use for the bundle
If the relevant policy period term is already bound, the method returns the period's policy number.
The method creates an activity and returns null if any of the following conditions occur.
• The policy is not in the correct state to accept the payment
• An applicable payment plan as specified by the selectedPaymentPlanCode and paymentAmount arguments
could not be found
Otherwise, the method invokes the active workflow trigger FinishIssueRenewal and returns the period's policy
number.

Archiving web services

To manipulate archiving from external systems, call the ArchiveAPI web service.

See also
• “Archiving integration” on page 573

Check if a policy term is archived

To check whether a policy term is archived, call the ArchiveAPI method isArchived. It takes a String policy
number and an effective date. The method first determines which policy term is effective at the given date. The
method returns true if the term is archived, otherwise false.
A term is considered archived if one or more of its policy periods is archived, even if not all are archived.

Restore a policy term

To request PolicyCenter restore a policy term, call the ArchiveAPI method requestRestore. The restore does not
happen synchronously. In other words, the caller cannot assume the restore is complete when the API returns control
to the caller. Instead, PolicyCenter simply adds this policy term to the set of policy terms to restore. Eventually, a
batch process restores the policy term.
The requestRestore method accepts a String policy number and an effective date. The method first determines
which policy term is effective at the given date. Next, it marks that policy term as a term to restore.

Suspend and resume archiving for a policy

PolicyCenter includes a feature to mark a policy as ineligible for additional archiving. This feature sometimes is
known as suspending archiving. There are three methods on the ArchiveAPI web service that relate to the
128 chapter 6: Account and policy web services
 Guidewire PolicyCenter 9.0.6 Integration Guide

suspension of archiving. All three methods take a single argument, which is the policy number of the policy in
question. The methods implement the following operations.
• Suspend archiving – From an external system, call the ArchiveAPI method setDoNotArchive.
• Resume archiving – From an external system, call the ArchiveAPI method unsetDoNotArchive. If there are
terms that are already archived, resuming archiving does not restore any already-archived terms.
• Check a policy for suspended from archiving – From an external system, call the ArchiveAPI method
isDoNotArchive. The method returns true if the policy is currently suspended from archiving, false otherwise.
The return result does not indicate whether the policy has any archived terms, only whether the policy is
currently suspended from consideration of archiving.

Quote purging web services

To manipulate quote purging from external systems, call the PurgeAPI web service. The service provides methods
for flagging whether to purge a policy or policy period.

See also
• Application Guide

Do not purge flag on a policy period

The PurgeAPI web service has methods related to the DoNotDestroy flag on a policy period. The methods accept
the PublicID of the policy period. They perform the following operations.
• Check whether a policy period is excluded from purge – From an external system, call the
isDoNotDestroyPolicyPeriod method to check the DoNotDestroy flag on a policy period.
• Flag a policy period as excluded from purge – From an external system, call the
setDoNotDestroyPolicyPeriod method to set the DoNotDestroyFlag on a policy period to true.
• Flag a policy period as not excluded from purge – From an external system, call the
unsetDoNotDestroyPolicyPeriod method to set the DoNotDestroyFlag on a policy period to false.

Account and policy web services 129

Guidewire PolicyCenter 9.0.6 Integration Guide

130 chapter 6: Account and policy web services

part 3

Plugins
Guidewire PolicyCenter 9.0.6 Integration Guide
chapter 7

Overview of plugins

PolicyCenter plugins are software modules that PolicyCenter calls to perform an action or calculate a result.
PolicyCenter defines a set of plugin interfaces. You can write your own implementations of plugins in Gosu or Java.

Overview of PolicyCenter plugins

PolicyCenter plugins are classes that PolicyCenter invokes to perform an action or calculate a result at a specific
time in its business logic. PolicyCenter defines plugin interfaces for various purposes.
• Perform calculations.
• Provide configuration points for your own business logic at clearly defined places in application operation, such
as validation or assignment.
• Generate new data for other application logic, such as generating a new claim number.
• Define how the application interacts with other Guidewire InsuranceSuite applications for important actions
relating to claims, policies, billing, and contacts.
• Define how the application interacts with other third-party external systems such as a document management
system, third-party claim systems, third-party policy systems, or third-party billing systems.
• Define how PolicyCenter sends messages to external systems.
You can implement a plugin in the programming languages Gosu or Java. In many cases, it is easiest to implement a
plugin with a Gosu class. If you use Java, you must use a separate IDE other than Studio, and you must regenerate
Java API libraries after any data model changes.
If you implement a plugin in Java, optionally you can write your code as an OSGi bundle. The OSGi framework is a
Java module system and service platform that helps cleanly isolate code modules and any necessary Java API
libraries. Guidewire recommends OSGi for all new Java plugin development.
From a technical perspective, PolicyCenter defines a plugin as an interface, which is a set of functions (also known
as methods) that are necessary for a specific task. Each plugin interface is a strict contract of interaction and
expectation between the application and the plugin implementation. Some other set of code that implements the
interface must perform the task and return any appropriate result values.
Conceptually, there are two main steps to implement a plugin.
1. Write a Gosu or Java class that implements a plugin interface.
2. Register the plugin implementation class.
For most plugin interfaces, you can only register a single plugin implementation for that interface. However, some
plugin interfaces support multiple implementations for the same interface, such as messaging plugins and startable
plugins.
Overview of plugins 133
Guidewire PolicyCenter 9.0.6 Integration Guide

The plugin itself might do most of the work or it might consult with other external systems. Many plugins typically
run while users wait for responses from the application user interface. Guidewire strongly recommends that you
carefully consider response time, including network response time, as you write your plugin implementations.

Implementing plugin interfaces

Choose a plugin implementation type
There are several ways to implement a PolicyCenter plugin interface.
• Implement a Gosu class. In many cases it is easiest to implement a plugin interface as a Gosu class because you
write and debug the plugin code in PolicyCenter Studio. The Gosu language has powerful features that simplify
the creation of a plugin class, including type inference and easy access to web services and XML.
• Implement a Java class. A Java plugin class must be implemented in an IDE other than Studio. Any Java IDE can
be used. You can choose to use the included application called IntelliJ IDEA with OSGi Editor for your Java
plugin development even if you do not choose to use OSGi. Also, if you write your plugin in Java, you must
regularly regenerate the Java API libraries after changes to data model configuration.
• Implement a Java class encapsulated in an OSGi bundle. The OSGi framework is a Java module system and
service platform that helps cleanly isolate code modules and any necessary Java API libraries. Guidewire
recommends OSGi for all new Java plugin development. To simplify OSGi configuration, PolicyCenter includes
an application called IntelliJ IDEA with OSGi Editor.
The following table compares the types of plugin implementations.

Features of each plugin implementation type Gosu plugin Java plugin OSGi plugin
(no OSGi) (Java with OSGi)
Choice of development environment
You can use PolicyCenter Studio to write and debug code. •
You can use the included application IntelliJ IDEA with OSGi editor to write code. • •
Usability
Native access to Gosu blocks, collection enhancements, Gosu classes. •
Entity and typecode APIs are the same as for Rules code and PCF code. •
Requires regenerating Java API libraries after data model changes. • •
Third‐party Java libraries
Your plugin code can use third‐party Java libraries. • • •
You can embed third‐party Java libraries within a OSGi bundle to reduce conflicts •
with other plugin code or PolicyCenter itself.
Dependencies on specific third‐party packages and classes are explicit in mani‐ •
fest files and validated at startup time.

Writing a plugin implementation class

Store plugin classes in a package located in your own hierarchy, such as mycompany.plugins. Never store a class in
the internal gw.* or com.guidewire.* package hierarchies.
Create a class that implements the plugin's interface.

public class SamplePluginClass implements sampleInterface

134 chapter 7: Overview of plugins

 Guidewire PolicyCenter 9.0.6 Integration Guide

Implement all public methods of the interface. PolicyCenter Studio and most professional Java IDEs can detect
when required methods are missing from a class. Studio provides a tool that can create stub versions of
unimplemented methods.
The @PluginParameter annotation
Plugin classes can describe their parameters with the @PluginParameter annotation. The annotation can specify
various properties of the parameter, such as its type and whether it is required.

@PluginParameter Description

helptext Debug message information. Default is "".

name Parameter name. To enable the name to be accessible to external tools without loading the class file,
make the property value a string literal or regular expression.
required Boolean value specifying whether the parameter is required. Default is false.
type Type of parameter. Type validation is performed on the parameter. Supported parameter types are
listed below. Default is String.
• Boolean
• Date
• EmailAddress
• File
• Integer
• String
• StringArray
• URL

The following Gosu code segment demonstrates how to use the @PluginParameter annotation.

@PluginParameter(:name="identifier", :type=Integer, :required=true)

@PluginParameter(:name="key", :type=String)
@PluginParameter(:name="iterationCount", :type:Integer)
class samplePluginClass implements sampleInterface, InitializablePlugin {
// Define a string constant for each parameter name
public final static var ID_PARAM : String = "identifier"
public final static var KEY_PARAM : String = "key"
public final static var ITERATION_PARAM : String = "iterationCount"

// Class parameter variables

var _identifier : Integer
var _key : String
var _iterationCount : Integer

// Demonstrate various techniques to access parameter values

override function setParameters(params : Map<Object, Object>) {
_identifier = params.get(ID_PARAM) as Integer
_key = getParameter(params, KEY_PARAM, "Sample debug message").toCharArray()
_iterationCount = getIntegerParameter(params, ITERATION_PARAM, 20)

// ... Remainder of class implementation ...

}
}

General plugin behavior

Plugin methods must strive to be idempotent so that calls to the method during a single transaction produce the same
results whether executed once or multiple times. Plugin methods must also attempt to be reentrant.
If the interface contains a method starting with the substring get, set, or is and takes no parameters, define the
method using the property getter or setter syntax. Do not implement the method using the name as it is defined in the
interface. For example, if samplePluginClass declares the method getMyVar(), the implementation must define a
property getter method, as demonstrated in the following code segment.

class samplePluginClass implements sampleInterface {

Overview of plugins 135

Guidewire PolicyCenter 9.0.6 Integration Guide

property get MyVar() : String {

// ... Property getter implementation ...
}
}

For plugins written in Java, the Java API libraries must be regenerated whenever changes are performed on the data
model configuration.

Base configuration plugin implementation classes

For most plugin interfaces, a base configuration class implementation is provided and registered in the Studio plugin
registry. A few of these base implementations can be used as-is in a production environment. However, base
implementations are typically provided for demonstration purposes only. Their intention is to be used as a beginning
foundation to which extra configuration code is added before being placed in a production environment.
Some plugin implementations connect with other Guidewire InsuranceSuite applications. The InsuranceSuite plugin
implementations are stored in packages with names that reference the target application and its version number. For
example, a package name for a plugin that integrates with PolicyCenter 9.0.0 would include the characters pc900.
This naming convention assists in achieving a smooth migration and backward compatibility between Guidewire
applications.

Registering a plugin implementation class

After implementing the plugin class, the class must be registered so PolicyCenter knows about it. The registry
configures which implementation class is responsible for which plugin interface. If you correctly register your
plugin implementation, PolicyCenter calls the plugin at the appropriate times in the application logic. The plugin
implementation performs some action or computation and in some cases returns results back to PolicyCenter.
To register a plugin, in Studio in the Project window, navigate to configuration→config→Plugins→registry. Right-click
on registry, and choose New → Plugin.
To use the Plugins registry, you must know all of the following.
• The plugin interface name. You must choose a supported PolicyCenter plugin interface. You cannot create your
own plugin interface.
• The fully-qualified class name of your concrete plugin implementation class.
• Any initialization parameters, also called plugin parameters.
In nearly all cases, you must have only one active enabled implementation for each plugin interface. However, there
are exceptions, such as messaging plugins, encryption plugins, and startable plugins. If the plugin interface supports
only one implementation, be sure to remove any existing registry entries before adding new ones.
As you register plugins in Studio, the interface prompts you for a plugin name. Plugin names can include
alphanumeric characters only. Space or blank characters are not allowed.
If the interface accepts only one implementation, the plugin name is arbitrary. However, it is the best practice to set
the plugin name to match the plugin interface name and omit the package.
If the interface accepts more than one implementation, the plugin name may be important. For example, for
messaging plugins, enter the plugin name when you configure the messaging destination in the separate Messaging
editor in Studio. For encryption plugins, if you ever change your encryption algorithm, the plugin name is the unique
identifier for each encryption algorithm.
If the interface field is blank, PolicyCenter assumes the interface name matches the plugin name. You might notice
that some of the plugin implementations that are pre-registered in the default configuration have that field blank for
this reason.

Plugin parameters
In the Plugins Registry editor, you can add a list of parameters as name-value pairs. The plugin implementation can
use these values. For example, you might pass a server name, a port number, or other configuration information to
your plugin implementation code using a parameter. Using a plugin parameter in many cases is an alternative to
using hard-coded values in implementation code.
To use plugin parameters, a plugin implementation must implement the InitializablePlugin interface in addition
to the main plugin interface. If PolicyCenter detects that your plugin implementation implements
136 chapter 7: Overview of plugins
 Guidewire PolicyCenter 9.0.6 Integration Guide

InitializablePlugin, PolicyCenter calls your plugin’s setParameters method. That method must have exactly
one argument, which is a java.util.Map object. In the map, the parameters names are keys in the map.
By default, all plugin parameters have the same name-value pairs for all values of the servers and environment
system variables. However, the Plugins registry allows optional configuration by server, by environment, or both.
For example, you could set a server name differently depending on whether you are running a development or
production configuration.

See also
• “Getting plugin parameters from the plugins registry editor” on page 139

For Java plugins (without OSGi), define a plugin directory

For Java plugin implementations that do not use OSGi, the Plugins Registry editor has a field for a plugin directory.
A plugin directory is where you put non-OSGI Java classes and library files. In this field, enter the name of a
subdirectory in the PolicyCenter/modules/configuration/plugins directory.
To reduce the chance of conflicts in Java classes and libraries between plugin implementations, define a unique
name for a plugin directory for each plugin implementation. If you do not specify a plugin directory, the default is
shared.
OSGi plugin implementations automatically isolate code for your plugin with any necessary third-party libraries in
one OSGi bundle. Therefore, for OSGi plugin implementations, you do not configure a plugin directory in the
Plugins Registry editor in Studio.

Deploying Java files, including Java code called from Gosu plugins
To deploy any Java files or third-party Java libraries varies based on your plugin type, perform the following
operations.
• If your Gosu plugin implements the plugin interface but accesses third-party Java classes or libraries, you must
put these files in the right places in the configuration environment. It is important to note that the plugin directory
setting discussed in that section has the value Gosu for code called from Gosu.
• For Java plugins that do not use OSGi, first ensure you define a plugin directory.
• For Java plugin classes deployed as OSGi bundles, deployment of your plugin files and third party libraries is
very different from deploying non-OSGi Java code. PolicyCenter supports OSGi bundles only to implement a
PolicyCenter plugin interface and any of your related third-party libraries. It is unsupported to install OSGi
bundles for any other purpose.

See also
• “Deploying non-OSGi Java classes and JAR files” on page 661
• “Using IntelliJ IDEA with OSGi editor to deploy an OSGi plugin” on page 662

Error handling in plugins

PolicyCenter tries to respond appropriately to errors that occur during the execution of a plugin method. When
possible, a default action is performed. However, when an error occurs in certain cases, such as the generation of a
policy or claim number, no reasonable default behavior exists. In such cases, the action that triggered the plugin fails
and displays an error message.
Plugin error handling is dependent on the plugin interface and program context. Check the plugin method signature
to view the possible exceptions.
A plugin method can throw custom exceptions. The custom exception can be any of the following types.
• A Gosu-accessible exception declared in the gw.api.util package
• A Gosu-accessible exception declared in the plugin's module
• A Java built-in exception, such as IllegalArgumentException or IOException
The DisplayableException shows an error message in the user interface.
Overview of plugins 137
Guidewire PolicyCenter 9.0.6 Integration Guide

uses gw.api.util.DisplayableException

public class MyCustomPluginHandler {

function myPluginHandler(){
throw new DisplayableException("MyCustomPluginHandler: myPluginHandler Error Message")
}
}

Enabling or disabling a plugin

PolicyCenter calls plugins registered in the Plugins registry at the appropriate time in the application logic.
To disable a registered plugin, navigate to the Plugins Registry editor in Studio for your plugin implementation. To
disable the plugin implementation, select the Disabled checkbox.
To enable a disabled plugin, deselect the Disabled checkbox.

Example Gosu plugin

The following example code implements a simple Gosu messaging plugin that uses parameters.

uses java.util.Map;
uses java.plugin;

class MyTransport implements MessageTransport, InitializablePlugin {

private var _servername : String

private var _destinationID : int

// Note the empty constructor. If you provide an empty constructor, the application calls it
// as the plugin instantiates, which occurs before the application calls setParameters().
construct() {
}

override function setParameters(parameters : Map<String,String>) {

// Access values in the Map argument to retrieve parameters defined in Studio Plugins registry
_servername = parameters["MyServerName"] as String
}

override function suspend() {}

override function shutdown() {}

override function setDestinationID(id:int) { _destinationID = id }

override function resume() {}

override function send(message : entity.Message, transformedPayload : String) {

print("MESSAGE SEND ====== ${message.Payload} --> ${transformedPayload}")
message.reportAck()
}
}

Special notes for Java plugins

Users can trigger a plugin call by performing a user-interface action. External applications can trigger a plugin by
calling a web service. It can sometimes be useful for a Java plugin method to know which user or application
triggered the plugin call.
The CurrentUserUtil utility class and its getCurrentUser method can be called by a Java plugin to retrieve the
triggering user or application. Sample code is shown below. The getUser method returns a User entity.

trigger = CurrentUserUtil.getCurrentUser().getUser();

138 chapter 7: Overview of plugins

 Guidewire PolicyCenter 9.0.6 Integration Guide

See also

• “Accessing entity data from Java” on page 656.

Getting plugin parameters from the plugins registry editor

In the Studio Plugins Registry editor, you can add one or more optional parameters to pass to your plugin during
initialization. For example, you could use the editor to pass server names, port numbers, timeout values, or other
settings to your plugin code. The parameters are pairs of String values, also known as name/value pairs.
PolicyCenter treats all plugin parameters as text values, even if they represent numbers or other objects.
To use the plugin parameters in your plugin implementation, your plugin must implement the
InitializablePlugin interface in addition to the main plugin interface.
If you do this, PolicyCenter calls your plugin’s setParameters method. That method must have exactly one
argument, which is a java.util.Map object. In the map, the parameters names are keys in the map, and they map to
the values from Studio.

See also

• For an implementation of a messaging plugin that uses parameters, see “Example Gosu plugin” on page 138.

Getting the local file path of the root and temp directories
For Gosu and Java plugins, the names of the plugin’s root and temporary directory paths can be retrieved by
accessing built-in properties from the Map. These properties are not available from OSGi plugins.
The root directory name is stored in the static variable InitializablePlugin.ROOT_DIR.
The temporary directory name is stored in the static variable InitializablePlugin.TEMP_DIR.

Plugin registry APIs

Getting references to plugins from Gosu

To ask the application for the currently-implemented instance of a plugin, call the Plugins.get static method and
pass the plugin interface name as an argument. It returns a reference to the plugin implementation. The return result
is properly statically typed so you can directly call methods on the result. The following code block demonstrates
this process.

var plugin = gw.plugin.Plugins.get(ContactSystemPlugin)

try{
plugin.retrieveContact("abc:123")
}catch(e){
e.printStackTrace()
throw new DisplayableException(e.Message)
}

Alternatively, you can request a plugin by the plugin name defined in the Plugins registry. This syntax is used when
there is more than one plugin implementation of the interface. For example, multiple implementations of an
interface are common in messaging plugins. In such cases, use the get method signature that takes a String for the
plugin name.

var plugin = gw.plugin.Plugins.get("MyContactPluginRegistryName") as ContactSystemPlugin

Overview of plugins 139

Guidewire PolicyCenter 9.0.6 Integration Guide

Checking whether a plugin is enabled

You can call the isEnabled method of the Plugins class to determine if a plugin is enabled in Studio. Pass either of
the following String arguments.
• The interface name type with no package
• The plugin name defined in the Plugins registry
The following code segment demonstrates how to call the isEnabled method.

var contactSystemEnabled = gw.plugin.Plugins.isEnabled(ContactSystemPlugin)

Getting references to Java plugins from Java

From Java you can get references to other installed plugins either by class or by the string representation of the class.
Do this using methods on the PluginRegistry class within the guidewire.pl.plugin package. Get the plugin by
class by calling the getPlugin(Class) method. Get the plugin by name calling the getPluginByName(String)
method.
This is useful if you want to access one plugin from another plugin. For example, a messaging-related plugin that
you write might need a reference to another messaging-related plugin to communicate or share common code.
Also, this allows you to access plugin interfaces that provide services to plugins or other Java code. For example, the
IScriptHost plugin can evaluate Gosu expressions. To use it, get a reference to the currently-installed
IScriptHost plugin. Next, call its methods. Call the putSymbol method to make a Gosu context symbol, such
policy to evaluate to a specific Policy object reference. Call the evaluate method to evaluate a String containing
Gosu code.
Do not call these methods from Gosu. Instead, call the Plugins.get static method and pass the plugin interface
name or plugin name as an argument.

Plugin thread safety

If you register a Java plugin or a Gosu plugin, exactly one instance of that plugin exists in the Java virtual machine
on that server, generally speaking. For example, if you register a document production plugin, exactly one instance
of that plugin instantiates on each server.
The rules are different for messaging plugins in PolicyCenter server clusters. In general, messaging plugins
instantiate on servers with the messaging server role. Servers without that role typically have no instances of
message request, message transport, and message reply plugins. Messaging plugins must be especially careful about
thread safety because messaging supports a large number of simultaneous threads, configured in Studio.
However, one server instance of the Java plugin or Gosu plugin must service multiple user sessions. Because
multiple user sessions use multiple process threads, follow the these rules to avoid thread problems.
• Your plugin must support multiple simultaneous calls to the same plugin method. A plugin can be called from
either PolicyCenter or from different threads. You must ensure multiple calls to the plugin never access the same
shared data. Alternatively, protect access to shared resources so that two threads do not access it simultaneously.
• Your plugin implementation must support multiple user sessions. Generally speaking, do not assume shared data
or temporary storage is unique to one user request (one HTTP request of a single user).
The most important way to avoid thread safety problems in plugin implementations is to avoid variables stored once
per class, referred to as static variables. Static variables are a feature of both the Java language and the Gosu
language. Static variables let a class store a value once per class, initialized only once. In contrast, object instance
variables exist once per instance of the class.
Static variables can be extremely dangerous in a multi-threaded environment. Using static variables in a plugin can
cause serious problems in a production deployment without taking great care to avoid problems. Be aware that such
problems, if they occur, are extremely difficult to diagnose and debug. Timing in an multi-user multi-threaded
environment is difficult, if not impossible, to control in a testing environment.
Because plugins could be called from multiple threads, there is sometimes no obvious place to store temporary data
that stores state information. Where possible and appropriate, replace static variables with other mechanisms, such
as setting properties on the relevant data passed as parameters. For example, in some cases perhaps use a data model
140 chapter 7: Overview of plugins
 Guidewire PolicyCenter 9.0.6 Integration Guide

extension property on a Policy or other relevant entity (including custom entities) to store state-specific data for the
plugin. Be aware that storing data in an entity shares the data across servers in a PolicyCenter cluster. Additionally,
even standard instance variables (not just static variables) can be dangerous because there is only one instance of the
plugin.
If you are experienced with multi-threaded programming and you are certain that static variables are necessary, you
must ensure that you synchronize access to static variables. Synchronization refers to a feature of Java that locks
access between threads to shared resources, such as static variables.

Using Java concurrent data types, even from Gosu

The simplest way of synchronizing access to a static variable in Java is to store data as an instance of a Java classes
defined in the package java.util.concurrent. The objects in that package automatically implement
synchronization of their data, and no additional code or syntax is necessary to keep all access to this data thread-
safe. For example, to store a mapping between keys and values, instead of using a standard Java HashMap object,
instead use java.util.concurrent.ConcurrentHashMap.
These tools protect the integrity of the keys and values in the map. However, you must ensure that if multiple
threads or user sessions use the plugin, the business logic still does something appropriate with shared data. You
must test the logic under multi-user and multi-thread situations.
Be aware that all thread safety APIs that use blocking can affect performance negatively. For high performance, use
such APIs carefully and test all code under heavy loads that test the concurrency.

Using synchronized methods (Java only)

Java provides a feature called synchronization that protects shared access to static variables. It lets you tag some or
all methods so that no more than one of these methods can be run at once. Then, you can add code safely to these
methods that get or set the object’s static class variables, and such access are thread safe.
If an object is visible to more than one thread, and one thread is running a synchronized method, the object is
locked. If an object is locked, other threads cannot run a synchronized method of that object until the lock releases.
If a second thread starts a synchronized method before the original thread finishes running a synchronized method
on the same object, the second thread waits until the first thread finishes. This is known as blocking or suspending
execution until the original thread is done with the object.
Mark one or more methods with this special status by applying the synchronized keyword in the method definition.
This example shows a simple class with two synchronized methods that use a static class variable.

public class SyncExample {

private static int contents;

public int get() {

return contents;
}

// Define a synchronized method. Only one thread can run a syncced method at one time for this object
public synchronized void put1(int value) {
contents = value;
// do some other action here perhaps...
}

// Define a synchronized method. Only one thread can run a syncced method at one time for this object
public synchronized void put2(int value) {

contents = value;
// do some other action here perhaps...
}
}

Overview of plugins 141

Guidewire PolicyCenter 9.0.6 Integration Guide

Synchronization protects invocations of all synchronized methods on the object; it is not possible for invocations of
two different synchronized methods on the same object to interleave. For the earlier example, the Java virtual
machine does all of the following.
• Prevents two threads simultaneously running put1 at the same time
• Prevents put1 from running while put2 is still running
• Prevents put2 from running while put1 is still running.
This approach protects integrity of access to the shared data. However, you must still ensure that if multiple threads
or user sessions use the plugin, your code does something appropriate with this shared data. Always test your
business logic under multi-user and multi-thread situations.
PolicyCenter calls the plugin method initialization method setParameters exactly once, hence only by one thread,
so that method is automatically safe. The setParameters method is a special method that PolicyCenter calls during
plugin initialization. This method takes a Map with initialization parameters that you specify in the Plugins registry
in Studio.
On a related note, Java class constructors cannot be synchronized; using the Java keyword synchronized with a
constructor generates a syntax error. Synchronizing constructors does not make sense because only the thread that
creates an object has access to during the time Java is constructing it.

Using Java synchronized blocks of code (Java only)

Java code can also synchronize access to shared resources by defining a block of statements that can only be run by
one thread at a time. If a second thread starts that block of code, it waits until the first thread is done before
continuing. Compared to the method locking approach described earlier in this section, synchronizing a block of
statements allows much smaller granularity for locking.
To synchronize a block of statements, use the synchronized keyword and pass it a Java object or class identifier. In
the context of protecting access to static variables, always pass the class identifier ClassName.class for the class
hosting the static variables.
For example, the following code segment demonstrates statement-level or block-level synchronization.

class MyPluginClass implements IMyPluginInterface {

private static byte[] myLock = new byte[0];

public void MyMethod(Address f){

// SYNCHRONIZE ACCESS TO SHARED DATA!

synchronized(MyPluginClass.class){

// Code to lock is here....

}
}

This finer granularity of locking reduces the frequency that one thread is waiting for another to complete some
action. Depending on the type of code and real-world use cases, this finer granularity could improve performance
greatly over using synchronized methods. This is particularly the case if there are many threads. However, you
might be able to refactor your code to convert blocks of synchronized statements into separate synchronized
methods.
Both approaches protects integrity of access to the shared data. However, you must plan to handle multiple threads
or user sessions to use your plugin, and do safely access any shared data. Also, test your business logic under
realistic heavy loads for multi-user and multi-thread situations.

Avoid singletons due to thread‐safety issues

Thread safety problems apply to any Java object that has only a single instance–also referred to as a singleton–
implemented using static variables. Because accessing static variables in multi-threaded code is complex, Guidewire
strongly discourages using singleton Java classes. You must synchronize access to all data singleton instances just as
for other static variables as described earlier in this section. This restriction is important for all Gosu Java that
PolicyCenter runs.
142 chapter 7: Overview of plugins
 Guidewire PolicyCenter 9.0.6 Integration Guide

The following code segment provides an example of creating a singleton using a class static variable.

public class MySingleton {

private static MySingleton _instance = new MySingleton();

private MySingleton() {
// construct object . . .
}

public static MySingleton getInstance() {

return _instance;
}

Design plugin implementations to support server clusters

Generally speaking, if your plugin deploys in a PolicyCenter server cluster, there are instances of the plugin
deployed on every server in the cluster. Consequently, design your plugin code (and any associated integration code)
to support concurrent instances. If the Gosu code calls out to Java for any network connections, that code must
support concurrent connections.
There is an exception for this cluster rule: In general, messaging plugins instantiate only on servers with the
messaging server role.
Because there may be multiple instances of the plugin, you must ensure that you update a database from Java code
carefully. Your code must be thread safe, handle errors fully, and operate logically for database transactions in
interactions with external systems. For example, if several updates to a database must be treated as one action or
several pieces of data must be modified as one atomic action, design your code accordingly.
General plugin thread safety synchronization techniques are insufficient to synchronize data shared across multiple
servers in a cluster. Additional safeguards are required because each server has its own Java virtual machine and,
therefore, its own data space. You must implement your own approach to ensure access to shared resources safely
even if accessed simultaneously by multiple threads and on multiple servers. Write your plugins to know about the
other server’s plugins but not to rely on anything other than the database to communicate among each other across
servers.

Reading system properties in plugins

You can test plugins in multiple deployment environments without recompiling plugins. For example, if a plugin
runs on a test server, then the plugin queries a test database. If the plugin runs on a production server, then the plugin
queries a production database.
Alternatively, you might want a plugin to be run on multiple machines in a cluster with each machine having a
server identity. You can implement unique behavior within the cluster. Additionally, you can add this information to
log files both on the local machine and in the external system also.
In these cases, plugins can use environment (env) and server ID (serverid) deployment properties to deploy a
single plugin with different behaviors in multiple contexts or across clustered servers. Define these system
properties in the server configuration file or as command-prompt parameters for the command that launches your
web server container. In general, use the default system property settings. If you want to customize them, use the
Plugin Registry editor in Guidewire Studio™.
Gosu plugins can query system properties by using the following gw.api.system.server.ServerUtil static
methods:

getEnv
Get runtime values for the environment for this cluster member.

getServerId
Get the runtime value for the server ID for this cluster member.

getServerRoles
Get the set of server roles for this cluster member.
Overview of plugins 143
Guidewire PolicyCenter 9.0.6 Integration Guide

To query general system properties, use the getProperty static method of java.lang.System and pass a property
name. For example:

java.lang.System.getProperty("gw.pc.env");

Do not call local web services from plugins

Do not call locally-hosted SOAP web service APIs from within a plugin or the rules engine in production systems. If
the web service hosted locally modifies entity data and commits the bundle, the current transaction does not always
detect and reload local data for your plugin implementation. Instead, refactor your code to avoid this case. For
example, write a Gosu class that performs a similar function as the web service but that does not commit the bundle.
This type of refactoring also results in higher server performance.

Creating unique numbers in a sequence

Typical PolicyCenter implementations need to reliably create unique numbers in a sequence for some types of
objects. For example, to enforce a series of unique IDs, such as public ID values, within a sequence. You can
generate new numbers in a sequence using sequence generator APIs in the SequenceUtil class.
These methods take two parameters.
• An initial value for the sequence, if it does not yet exist.
• A String with up to 26 characters that uniquely identifies the sequence. This is the sequence key
(sequenceKey).
For example, the following Gosu code gets a new number from a sequence called WidgetNumber.

nextNum = gw.api.system.database.SequenceUtil.next(10, "WidgetNumber")

If this is the first time any code has requested a number in this sequence, the value is 10. If other code calls this
method again, the return value is 11, 12, and so on, depending on the number of times code has requested numbers
for this sequence key.
You can disable the sequence utility class by setting the config.xml parameter DisableSequenceUtil. Use this to
ensure that any sequences in your code use some alternative mechanism for sequenced identifiers.

Restarting and testing tips for plugin developers

If you frequently modify your plugin code, you might need to frequently redeploy PolicyCenter to test your plugins.
If it is a non-production server, you may not want to shut down the entire web application container and restart it.
For development use only, reload only the PolicyCenter application rather than the web application container. If
your web application container supports this, replace your plugin class files and reload the application.

Summary of all PolicyCenter plugins

The following table summarizes the plugin interfaces that PolicyCenter defines.

PolicyCenter Plugin Interface Description

Contact‐related plugins
ContactSystemPlugin Searches for contacts and retrieve contacts from an external system. See “Inte‐
grating with a contact management system” on page 529.
IAccountContactPlugin Configures how to copy properties between account contacts. See “Account con‐
tact plugin” on page 536.

144 chapter 7: Overview of plugins

 Guidewire PolicyCenter 9.0.6 Integration Guide

PolicyCenter Plugin Interface Description

IAccountContactRolePlugin Configures how to copy properties between account contact roles and copy
pending updates. See “Account contact role plugin” on page 537.
IAccountSyncable Customizes how PolicyCenter synchronizes contact with accounts. For more infor‐
mation. See “Synchronizing contacts with accounts” on page 536.
IAddressBookAdapter Internal only. Never use or implement this plugin.
IContactConfigPlugin Configures contacts, such as the address contact roles that are available and get‐
ting the display name for an account contact role type. See “Configuring how
PolicyCenter handles contacts” on page 535.
IContactSearchAdapter Internal only. Never use or implement this plugin.
IGeocodePlugin Geocoding support in PolicyCenter. See “Geographic data integration” on page
237.
OfficialIdToTaxIdMappingPlugin Determines whether PolicyCenter treats an official ID type as a tax ID for con‐
tacts. See “Official IDs mapped to tax IDs plugin” on page 266.
Other PolicyCenter plugins
AccountLocationPlugin For account locations and policy locations, customize how PolicyCenter performs
the following operations.
• Determines that two locations are the same
• Clones a location
See “Location plugin” on page 157.
ConversionOnRenewal Configures actions to perform if a renewal fails during converting. See “Conver‐
sion on renewal plugin” on page 153.
IAccountPlugin Manipulates accounts. See “Account plugin details” on page 151.
IArchivingSource Stores and retrieves archived policies from an external backing source. See “Ar‐
chiving integration” on page 573.
IAuditSchedulePatternSelectorPlugin Customizes how PolicyCenter chooses the audit schedule pattern for cancellation
and expiration. See “Audit schedule selector plugin” on page 153.
IBillingSummaryPlugin Generates billing summaries for the billing summary screen. See “Implementing
the billing summary plugin” on page 510
IBillingSystemPlugin Interacts with an external billing system for actions that PolicyCenter initiates.
See “Implementing the billing system plugin” on page 501
IClaimSearchPlugin Searches for claims. See “Claim search from PolicyCenter” on page 449.
IEffectiveTimePlugin Determines the time of day (since midnight) for a job. See “Effective time plugin”
on page 153.
IETLProductModelLoaderPlugin Extracts product model data from the running PolicyCenter server, and stores the
information in ETL product model tables in the PolicyCenter database. See “ETL
product model loader plugin” on page 155.
IExchangeRateSet Internal only. Never use or implement this plugin.
IFXRatePlugin Handles exchange rate conversion.
IImpactTestingPlugin Only for customers who license Guidewire Rating Management.
This plugin configures rating routine impact testing.
IJobCreation Creates a job process. See “Job process creation plugin” on page 156
IJobProcessCreationPlugin Creates the right job process subtype. See “Job process creation plugin” on page
156.
ILossHistoryPlugin Handles loss history summaries for a policy. See “Loss history plugin” on page
158.

Overview of plugins 145

Guidewire PolicyCenter 9.0.6 Integration Guide

PolicyCenter Plugin Interface Description

IMotorVehicleRecordPlugin Generates a request to the motor vehicle record (MVR) provider and returns the
MVR data. See “Motor vehicle record (MVR) plugin” on page 158.
INotificationPlugin Customizes the minimum lead time and the maximum lead time for different
types of notifications. See “Notification plugin” on page 160.
IPolicyEvaluationPlugin Customizes how PolicyCenter adds underwriter issues (UWIssue objects) on a pol‐
icy period. See “Policy evaluation plugin” on page 163.
IPolicyNumGenPlugin Generates policy numbers of two types: core policy numbers and current policy
revision numbers. See “Policy number generator plugin” on page 165.
IPolicyPaymentPlugin Returns the filtered reporting plans based on the policy. See “Policy payment plu‐
gin” on page 166.
IPolicyPeriodDiffPlugin Customizes how PolicyCenter generates and filters difference items that repre‐
sent comparing two policies for policy changes, multi‐version policy comparisons,
and other contexts. See “Policy difference customization” on page 427.
IPolicyPeriodPlugin Various important policy period customizations, including the following:
• Calculating the period end date from a TermType
• Calculating a TermType from period start and end dates
• Dynamically setting the initial wizard step in the job wizard
• Creating a job process
• Prorating bases from cancellation
• Specifying types to omit while copying a PolicyPeriod
• Customizing behavior after creating draft branch in new period
• Customizing behavior before promoting a branch
• Customizing behavior after handing a preemption
See “Policy period plugin” on page 166.
IPolicyPlugin Informs PolicyCenter whether it is OK to start various jobs, based on dynamic cal‐
culations on the policy. See “Policy plugin” on page 169.
IPolicyTermPlugin Calculates values related to policy terms. See “Policy term plugin” on page 171
IRateQueryLookupPlugin Only for customers who license Guidewire Rating Management.
This plugin enables you to customize the rate query fail‐over logic in PolicyCenter.
IRateRoutinePlugin Only for customers who license Guidewire Rating Management.
This plugin configures processing of rate routines.
IRatingPlugin This is the main plugin interface that defines the interaction between the applica‐
tion and a rating engine. See “Rating integration” on page 359.
IReferenceDatePlugin Evaluates the type of date to use to calculate the reference date on a given ob‐
ject. See “Reference date plugin” on page 179.
IRenewalPlugin Handles renewals. See “Renewal plugin” on page 179.
IUWCompanyPlugin Finds all the underwriting companies that are available for the jurisdictions in the
set. See “Underwriting company plugin” on page 180.
IVinPlugin Allows an external system to provide information about vehicles. See “Vehicle
identification number plugin” on page 264.
JobNumberGenPlugin Generates a new, unique job number. See “Policy number generator plugin” on
page 165.
PaymentGatewayConfigPlugin Configures the payment gateway that PolicyCenter uses to communicate with an
electronic payment service. See “Payment gateway configuration plugin” on page
161.
PaymentGatewayPlugin Communicates with an electronic payment service. See “Payment gateway plu‐
gin” on page 162.

146 chapter 7: Overview of plugins

 Guidewire PolicyCenter 9.0.6 Integration Guide

PolicyCenter Plugin Interface Description

PCPurgePlugin Modifies the behavior of quote purging. Quote purging removes from the data‐
base jobs not resulting in bound policies and alternate policy periods created
through multi‐version quoting and side‐by‐side quoting. Quote purging also re‐
moves orphaned policy periods, which are policy periods not associated with a
job. See “Quote purging plugin” on page 175.
ProrationPlugin Prorate a value. This is used by two places in PolicyCenter:
• Generate transaction calculations
• Rating integration
See “Proration plugin” on page 173.
QuotingDataPlugin Provides methods for saving quoting data to an external database.
WorksheetExtractPlugin Only for customers who license Guidewire Rating Management.
This plugin identifies which rating worksheet to extract and extracts the work‐
sheet data to files.
WorksheetPurgePlugin Only for customers who license Guidewire Rating Management.
This plugin configures how PolicyCenter purges rating worksheets.
Authentication plugins
AuthenticationServicePlugin Authorizes a user from a remote authentication source, such as a corporate LDAP
or other single‐source sign‐on system.
AuthenticationSource A marker interface representing an authentication source for user interface login.
The implementation of this interface must provide data to the authentication
service plugin that you register in PolicyCenter. All classes that implement this in‐
terface must be serializable. Any object contained with those objects must be se‐
rializable as well.
For WS‐I web services authentication, see the row in this table for
WebservicesAuthenticationPlugin.

AuthenticationSourceCreatorPlugin Creates an authentication source (an AuthenticationSource) for user interface

login. This takes an HTTP protocol request (from an HTTPRequest object). The
authorization source must work with your registered implementation of the
AuthenticationServicePlugin plugin interface.

DBAuthenticationPlugin Provides the ability to store the database username and password in a way other
than plain text in the config.xml file. For example, retrieve it from an external
system, decrypt the password, or read a file from the file system. The resulting
username and password substitutes into the database configuration for each in‐
stance of that ${username} or ${password} in the database parameters.
WebservicesAuthenticationPlugin For WS‐I web services only, configures custom authentication logic This plugin in‐
terface is documented with other WS‐I information. See “Web services authenti‐
cation plugin” on page 61.
Document content and metadata plugins
IDocumentContentSource Provides access to a remote document repository for storage and retrieval opera‐
tions.
The example IDocumentContentSource plugin provided in the base configuration
must be linked to a commercial document management system before being
used in a production environment.
IDocumentMetadataSource Stores metadata associated with a document, typically in a remote document
management system.
The example IDocumentMetadataSource plugin provided in the base configura‐
tion stores metadata locally and is not intended to be used in a production envi‐
ronment. For maximum data integrity and feature set, implement the plugin and
link it to a commercial document management system.
Document production plugins

Overview of plugins 147

Guidewire PolicyCenter 9.0.6 Integration Guide

PolicyCenter Plugin Interface Description

IDocumentProduction Generates documents from a template. For example, from a Gosu template or a
Microsoft Word template. This plugin can create documents synchronously
and/or asynchronously. See “Document production” on page 213.
IDocumentTemplateSource Provides access to a repository of document templates that can generate forms
and letters, or other merged documents. An implementation may simply store
templates in a local repository. A more sophisticated implementation might inter‐
face with a remote document management system.
IDocumentTemplateSerializer This plugin serializes and deserializes document template descriptors. Typically,
descriptors persist as XML, as such implementations of this class understand the
format of document template descriptors and can read and write them as XML.
Use the built‐in version of this plugin using the “Plugins registry.” In general, it is
best not implement your own version.
Messaging plugins (see “Messaging and events” on page 295)
MessageTransport The main messaging plugin interface within a messaging destination. This plugin
sends a message to an external/remote system by using an appropriate transport
protocol. This protocol could be a messaging queue, a remote API call, saving
special files in the file system, sending emails, and so on.
You can register multiple implementation for this interface to communicate with
multiple external systems.
MessageBeforeSend Optional pre‐processing of messages, primarily to transform the payload and re‐
turn a String that the message transport will use instead. For example, this plu‐
gin might convert a flat file of name/value fields to an XML document that is too
resource‐intensive to create at message creation time.
You can register multiple implementation for this interface to communicate with
multiple external systems.
MessageAfterSend Optional post‐send processing of messages.
You can register multiple implementation for this interface to communicate with
multiple external systems.
MessageRequest Optional pre‐processing of messages, and optional post‐send processing. The
MessageRequest interface perform roles of both the related plugins
MessageBeforeSend and MessageAfterSend.
You can register multiple implementation for this interface to communicate with
multiple external systems.
MessageReply Handles asynchronous acknowledgments of a message. After submitting an ac‐
knowledgment to optionally handles other post‐processing afterward such as
property updates. If you can send the message synchronously, do not implement
this plugin. Instead, implement only the transport plugin and acknowledge each
message immediately after it sends the message.
You can register multiple implementation for this interface to communicate with
multiple external systems.
Other plugins
BackgroundTaskLoadBalancingPlugin Defines strategies for managing the load balancing of messaging destinations and
startable services.
ClusterBroadcastTransportFactory For internal use only.
ClusterFastBroadcastTransportFactory
ClusterUnicastTransportFactory

IActivityEscalationPlugin Overrides the behavior of activity escalation instead of simply calling rule sets.
See “Exception and escalation plugins” on page 260.
IAddressAutocompletePlugin Configures how address automatic completion and fill‐in operate. See “Automat‐
ic address completion and fill‐in plugin” on page 264.

148 chapter 7: Overview of plugins

 Guidewire PolicyCenter 9.0.6 Integration Guide

PolicyCenter Plugin Interface Description

IBaseURLBuilder Generates a base URL to use for web application pages affiliated with this appli‐
cation, given the HTTP servlet request URI (HttpServletRequest). See “Defining
base URLs for fully qualified domain names” on page 262.
IBatchCompletedNotification Launches custom actions after a work queue or batch process completes process‐
ing a batch of items.
IEmailTemplateSource Retrieves email templates. In the base configuration, the templates are retrieved
from the server file system, but the plugin can be customized to access an alter‐
native location.
IEncryptionPlugin Encodes or decodes a String based on an algorithm you provide to hide impor‐
tant data, such as bank account numbers or private personal data. PolicyCenter
does not provide any encryption algorithm in the product. PolicyCenter simply
calls this plugin implementation, which is responsible for encoding an unencrypt‐
ed String or reversing that process. The implementation of this plugin in the
base configuration does nothing. See “Encryption integration” on page 247.
You can register multiple implementation for this interface.
IGroupExceptionPlugin Overrides the behavior of group exceptions instead of simply calling rule sets.
See “Exception and escalation plugins” on page 260.
InboundIntegrationStartablePlugin High performance inbound integrations, with support for multi‐threaded proc‐
essing of work items. See “Multi‐threaded inbound integration” on page 277.
You can register multiple implementation for this interface to communicate with
multiple external systems.
INoteTemplateSource Retrieves note templates. In the base configuration, the templates are retrieved
from the server file system, but the plugin can be customized to retrieve them
from a document management system.
IPhoneNormalizerPlugin Normalizes phone numbers that users enter through the application and that en‐
ter the database through data import. See “Phone number normalizer plugin” on
page 264.
IPreupdateHandler Implements your preupdate handling in plugin code rather than in rules. See
“Preupdate handler plugin” on page 258.
IProcessesPlugin Instantiates custom batch processing classes so they can be run on a schedule or
on demand. See “Implementing the processes plugin” on page 617.
IScriptHost Evaluates Gosu code to provide context‐sensitive data to other services. For ex‐
ample, this service could evaluate a String that has the Gosu expression
"policy.myFieldName" at run time.

IStartablePlugin Creates new plugins that immediately instantiate and run on server startup. See
“Overview of startable plugins” on page 269.
You can register multiple implementation for this interface.
ITestingClock Used for testing complex behavior over a long span of time, such as multiple bill‐
ing cycles or timeouts that are multiple days or weeks later. This plugin is for de‐
velopment (non‐production) use only. It programmatically changes the system
time to accelerate passing of time in PolicyCenter.
See “Testing clock plugin (for non‐production servers only)” on page 266.
IUserExceptionPlugin Overrides the behavior of user exceptions instead of simply calling rule sets. See
“Exception and escalation plugins” on page 260.
IWorkItemPriorityPlugin Calculates a the processing priority of a work item. See “Work item priority plu‐
gin” on page 260.
ManagementPlugin The external management interface for PolicyCenter, which enables you to imple‐
ment management systems, such as JMX and SNMP. See “Management integra‐
tion” on page 253.

Overview of plugins 149

Guidewire PolicyCenter 9.0.6 Integration Guide

150 chapter 7: Overview of plugins

chapter 8

Account and policy plugins

Plugins are software modules that PolicyCenter calls to perform an action or calculate a result. This topic details
plugins related mainly to PolicyCenter accounts, policies, and policy-related jobs.

Account plugin details

You can use the account plugin (IAccountPlugin) to customize how PolicyCenter manages accounts.

Performing account name clearance

Name clearance is part of an insurance application in which the insurance insurer determines whether this client
already has insurance with the insurer or is represented by a different producer. If represented by another producer,
the account is reserved for the other producer. Reservation is performed by line of business, so a client represented
by one producer for one line of business could be represented by another producer for another type of policy. If the
name is reserved, then the producer needs to be informed of the conflict. If not, the account is now reserved for this
producer and the process can proceed.
The plugin’s performNameClearance method performs name clearance on the given account and producer in the
form of an Account and a ProducerSelection. It returns the available products and sets the status appropriately
based on the product model configuration. The status on a product might be something other than available, for
example that the product is risk reserved or inapplicable.

Customizing deleting an account

PolicyCenter calls this plugin’s freezeAccount method to signal that the passed-in Account entity is frozen and
about to be deleted. If you need to do any special action before deletion, do it in this method. For example, if you
have linked data through foreign keys on the Account entity, you might need to delete that data also.
PolicyCenter only calls this if PolicyCenter is not the true system of record for the account and the account is about
to be deleted from the account system of record. This is also called after withdrawing accounts. PolicyCenter does
not allow deletion of accounts if PolicyCenter is the account system of record.

Generate new account number

Generate a new account number in the generateAccountNumber method. It takes an Account number and must
return a unique ID for the account.
Account and policy plugins 151
Guidewire PolicyCenter 9.0.6 Integration Guide

See also

• “Creating unique numbers in a sequence” on page 144

Is account editable?
Implement the isEditable method in this plugin to indicate whether an account is editable. It takes an Account
object and returns a boolean.
The default behavior is that an account is editable, but you can customize this behavior. For example, if
PolicyCenter is not the system of record for the account, you might choose to always make the account non-editable.

Customizing checking whether risk is reserved

Implement the isRiskReserved method to customize how PolicyCenter checks whether the given PolicyPeriod is
already risk reserved.

Customizing behavior after merging accounts

After PolicyCenter merges two accounts, calls the mergeAccounts method in this plugin so you can customize the
application logic. There is no required behavior, but if you have data model extension properties, you might need to
merge or copy data to the merged account. If you have related foreign key fields to other data, you might need to
merge or delete that data also.
PolicyCenter calls this method after the two accounts were merged into a single entity but the other (non-merged)
account entity has not yet been retired. The first parameter to the method is Account that is soon to be retired. The
second parameter is the destination merged account.
Merging two accounts is not enabled in the built-in PolicyCenter user interface, but can be triggered using the
AccountAPI web service mergeAccounts.

Populating account summaries with extension properties

PolicyCenter has an entity called AccountSummary that it uses in several places in the user interface to summarize an
account. The application copies the standard built-in properties automatically.
There is no required behavior. However, if you have data model extension properties in the Account that you want
in the summary, copy them from the Account to the AccountSummary. Implement this action in the account plugin’s
populateAccountSummary method.

Customizing transferring policies from one account to another account

After PolicyCenter transfers policies from one account to another, you can customize the application logic.
There is no required behavior, but if you have any data model extension properties and possibly additional foreign
key references, you might need to customize this logic. Implement the transferPolicies method, with the
following signature.

void transferPolicies(Policy[] policies, Account fromAccount, Account toAccount)

Transferring policies from one account to another is not enabled in the built-in PolicyCenter user interface, but you
can trigger it using the AccountAPI web service method transferPolicies.

See also

• “Account web services” on page 114

152 chapter 8: Account and policy plugins
 Guidewire PolicyCenter 9.0.6 Integration Guide

Audit schedule selector plugin

You can customize how PolicyCenter chooses the audit schedule pattern for cancellation and expiration by
implementing the IAuditSchedulePatternSelectorPlugin plugin interface. You define (and edit) the audit
schedule patterns in Product Designer as part of the product model.
The built-in implementation is provided in AuditSchedulePatternSelectorPlugin.gs, which you can modify or
use as the basis for your own version.
PolicyCenter includes several schedules in the built-in implementation. The built-in plugin implementation
references several of these.
There are two methods that you must implement.
• selectFinalAuditSchedulePatternForCancellation – Returns the cancellation audit schedule pattern to use
for final audits. It takes a PolicyPeriod and returns an AuditSchedulePattern object.
• selectFinalAuditSchedulePatternForExpiredPolicy – Returns the expiration audit schedule pattern to use
for final audits. It takes a PolicyPeriod and returns an AuditSchedulePattern object.
In the built-in implementation, these methods ignore the PolicyPeriod. Instead, the methods simply iterate across
all schedule patterns to find a pattern that matches a specific pattern code.

class AuditSchedulePatternSelectorPlugin implements IAuditSchedulePatternSelectorPlugin {

override function selectFinalAuditSchedulePatternForCancellation(period : PolicyPeriod) :

AuditSchedulePattern {
return AuditSchedulePatternLookup.getAll().firstWhere(\ f -> f.Code == "CancellationPhone")
}

override function selectFinalAuditSchedulePatternForExpiredPolicy(period : PolicyPeriod) :

AuditSchedulePattern {
return AuditSchedulePatternLookup.getAll().firstWhere(\ f -> f.Code == "ExpirationPhysical")
}
}

Conversion on renewal plugin

To configure actions to perform if a renewal fails during converting, implement the ConversionOnRenewal plugin.
There is only a single method, called conversionOnRenewalFailed. Before calling this plugin method,
PolicyCenter unlocks the PolicyPeriod and sets its status to draft so that it is editable.
The plugin can perform actions that improve the chances of the renewal conversion succeeding.
PolicyCenter provides a default plugin implementation called
gw.plugin.job.impl.ConversionOnRenewalPluginImpl. The class implements the following default behavior.
• Set the policy period status to TC_NEW, which allows eventual purging.
• Reassign a new policy number to each policy period, to reduce chance of conflict with existing policies.
If you want a different behavior, re-implement this plugin interface.
The conversionOnRenewalFailed method has two parameters: A renewal period (Renewal) and the original policy
period for the renewal (PolicyPeriod).
The method must return the original Renewal object passed to the method. Do not create and return a new Renewal
object.

Effective time plugin

Certain PolicyPeriod properties that denote effective dates and expiration dates are treated as datetime properties
with millisecond resolution. You can set the effective time (the clock time on that day) along with the effective date.
You can choose to have all effective dates always be the same time on any day, such as midnight or 12:01 AM on
that day. However, you can also choose to use more complex rules, and even vary the rules based on the type of job
or the jurisdiction if rules vary by state. PolicyCenter provides a plugin interface that lets you set the effective time
of day for various jobs. Modify the built-in version or implement your own implementation of the
IEffectiveTimePlugin plugin.
Account and policy plugins 153
Guidewire PolicyCenter 9.0.6 Integration Guide

After a job starts, PolicyCenter calls this plugin to set the default effective and expiration times on the job’s
associated PolicyPeriod entity. The return value from each of this interface’s methods is a Date object with its time
component (HH:mm:ss) set to the desired time. The day component of the Date is ignored. As a convenience, you
can return null to set the time component to midnight.
The plugin is called at varying points during job setup, according to the type of job. The main reason for this
difference is to allow you to customize the user interface to allow effective/expiration time settings to be manually
overridden. The following table compares the types of jobs, at what time the application calls the plugin, and why.

What time For which job types Description

PolicyCenter calls
the Effective Time
plugin
Before job is creat‐ Policy Change, Cancellation. These The only place where EditEffectiveDate can be edited is on the
ed are jobs that mainly affect a period’s StartPolicyChange or StartCancellation page, so the plugin
EditEffectiveDate property. must be called within the PCF file before the job is started.
After job is created Submission, Reinstatement, Rewrite, The effective/expiration time settings on PeriodStart and
and Renewal. These are jobs that PeriodEnd can be made editable by simply customizing the
mainly affect a period’s PolicyInfo page, which is not shown until after the job is start‐
PeriodStart and PeriodEnd prop‐ ed.
erties.
Never Issuance, Audit This plugin is not called for the Issuance job because it is logically
seen as a continuation/completion of a Submission job. Conse‐
quently, its PolicyPeriod simply inherits the dates set by the
Submission job. Similarly, there are no hooks for the Audit job,
since it simply uses the dates of the PolicyPeriod being audited.

Each method is responsible for determining either an effective time or expiration time for a date given the date and
the job type. The methods for determining expiration time also take an effectiveDateTime parameter, for cases in
which the expiration time depends on the period’s PeriodStart. Each method takes a PolicyPeriod entity
parameter. Use this parameter to access other information, such as state, line of business, or detecting other
contractual periods on this policy. Finally, each method has a strongly-typed job parameter, which can be used to
access information specific to the associated job type.
The following table lists the required methods and their purpose. Each method returns a java.util.Date object.

Method Description
getCancellationEffectiveTime Gets effective time for a cancellation job.
getConversionRenewalEffectiveTime Gets a renewal policy period's effective date for an imported legacy policy.
getConversionRenewalExpirationTime Gets a renewal policy period's expiration date for an imported legacy policy.
Includes an argument for the renewal policy period's effective date, as returned by
getConversionRenewalEffectiveDate.

getPolicyChangeEffectiveTime Gets effective time for a policy change job.

getReinstatementEffectiveTime Gets effective time for a reinstatement job.
getReinstatementExpirationTime Gets expiration time for a reinstatement job. Includes an argument for the reinstat‐
ed policy period's effective date, as returned by getReinstatementEffectiveTime.
getRenewalEffectiveTime Gets effective time for a renewal job.
getRenewalExpirationTime Gets expiration time for a renewal job. Includes an argument the renewal policy pe‐
riod's effective date, as returned by getRenewalEffectiveTime.
getRewriteEffectiveTime Gets effective time for a rewrite job.
getRewriteExpirationTime Gets expiration time for a rewrite job. Includes an argument for the rewritten policy
period's effective date, as returned by getRewriteEffectiveTime.

154 chapter 8: Account and policy plugins

 Guidewire PolicyCenter 9.0.6 Integration Guide

Method Description
getRewriteNewAccountEffectiveTime Gets a policy period's effective date for a policy that was rewritten to a new
account.
getRewriteNewAccountExpirationTime Gets a policy period's expiration date for a policy that was rewritten to a new
account. Includes an argument for the policy period's effective date, as returned by
getRewriteNewAccountEffectiveTime.

getSubmissionEffectiveTime Gets effective time for a submission job.

getSubmissionExpirationTime Gets expiration time for a submission job. Includes an argument for the policy peri‐
od's effective date, as returned by getSubmissionEffectiveTime.

PolicyCenter includes a built-in implementation of this interface with default behavior. The following table lists
effective times for a new job and the key values on the PolicyPeriod entity for that job after PolicyCenter calls this
plugin. The shaded cells are the effective times set explicitly by this plugin and the other cells indicate unchanged
values or dependence on other properties.

Job Value of PeriodStart Value of PeriodEnd Value of Value of

EditEffectiveDate CancellationDate
Submission 12:01 AM (changed by plu‐ 12:01 AM (changed by Same as this period's null
gin) plugin) PeriodStart

Policy Unchanged Unchanged 12:01 AM Unchanged

Change
Cancella‐ Unchanged Unchanged If canceled flat, same as can‐ Same as this period's
tion celed period's PeriodStart. EditEffectiveDate
Otherwise, 12:01 AM (changed
by plugin).
Reinstate‐ Unchanged Same as based‐on peri‐ Same as based‐on period's null
ment od's PeriodEnd CancellationDate (changed
(changed by plugin). by plugin)
Rewrite Same as based‐on period's If new‐term rewrite, Same as this period's null
CancellationDate 12:01 AM. Otherwise, PeriodStart
(changed by plugin). such as full‐term or
remainder‐of‐term re‐
write, same as based‐
on period's PeriodEnd
(changed by plugin).
Renewal Same as previous period's 12:01 AM (changed by Same as this period's null
PeriodEnd (changed by plugin) PeriodStart
plugin).

ETL product model loader plugin

The ETL Product Model Loader plugin extracts product model data from the running PolicyCenter server, and stores
the information in ETL product model tables in the PolicyCenter database. Policy data combined with the ETL
product model data can be extracted, transformed, and loaded into a data warehouse or data store for analysis or
reporting.
When the PolicyCenter server starts, it runs the ETL Product Model Loader plugin. PolicyCenter provides two
implementations of this plugin interface (IETLProductModelLoaderPlugin).
• ETLProductModelLoaderPlugin – Operational plugin implementation that is enabled and registered in the base
configuration.
• ETLProductModelLoaderEmptyPlugin – Non-operational plugin implementation.
Only one implementation can be enabled at a time.
Account and policy plugins 155
Guidewire PolicyCenter 9.0.6 Integration Guide

See also
• Product Model Guide

ETL product model loader plugin implementation

In the base configuration, the ETL Product Model Loader plugin implementation is registered and enabled in the
plugins registry. This plugin implementation first removes data from the ETL product model database tables. Then
the plugin extracts the PolicyCenter product model to ETL entities and writes these entities to the ETL product
model database tables.
If you update the product model in Product Designer, first synchronize the product model from Product Designer to
propagate your changes to PolicyCenter. Then restart PolicyCenter to run the Product Model Loader plugin. The
plugin repopulates the ETL database tables with the current product model.
If you add policy lines or add clauses and coverage terms to existing policy lines, the Product Model Loader creates
ETL product model tables for these additions. You can also extend the Product Model Loader to access other
product model data, including product offerings or questions in question sets. These changes may require modifying
the ETL entities.
The Gosu code for the Product Model Loader plugin is in ETLProductModelLoaderPlugin.gs in the
gw.plugin.etlprodmodloader.impl package. In the start method, the plugin first clears the ETL database tables
and entities by calling the deleteModel method. Then the plugin populates the ETL database tables and entities by
calling the loadModel method.
The factory subpackage contains creator classes for each ETL product model entity type. For example, the
ETLClausePatternCreator.gs class contains code to create ETLClausePattern entity instances.

Non‐operational plugin implementation

To effectively disable the ETL Product Model Loader plugin, register and enable the Non-operational ETL Product
Model Loader plugin implementation. This implementation does not populate the ETL database tables. Nor does the
implementation clear the ETL database tables.
The code for the Non-operational ETL Product Model Loader plugin implementation is in
ETLProductModelLoaderEmptyPlugin in the gw.plugin.etlprodmodloader.impl package.
In the registry for this plugin (IETLProductModelLoaderPlugin.gwp), perform the following operations.
• Register and enable the ETLProductModelLoaderEmptyPlugin plugin implementation.
• Remove the ETLProductModelLoaderPlugin plugin implementation from the registry.

Job process creation plugin

The JobProcessCreationPlugin job process creation plugin creates a new job process for a policy period entity
based on its job subtype. Its one method, called createJobProcess, takes a PolicyPeriod entity and returns an
instance of a JobProcess. For example, for a policy change job, this plugin must create a PolicyChangeProcess
object. The included version of this plugin creates job processes for all built-in job subtypes.
The plugin method is important if you created subtypes of one or more of the built-in job process classes. If that is
the case, you must detect your new subtypes in this method. Checking the value of Job property on the
PolicyPeriod and check its subtype. Next, instantiate your own job process subtype and return it.
Use the code of the included version of this plugin as a template for your version.

class JobProcessCreationPlugin implements IJobProcessCreationPlugin {

...
override function createJobProcess(period: PolicyPeriod): IJobProcess {
switch (period.Job.Subtype) {
case "Audit": return new AuditProcess(period)
case "Cancellation" : return new CancellationProcess(period)
...
}
}
}

156 chapter 8: Account and policy plugins

 Guidewire PolicyCenter 9.0.6 Integration Guide

See also
• Configuration Guide

Job number generator plugin

The IJobNumberGenPlugin job number generator plugin interface is responsible for generating a job number. The
base configuration plugin implementation in the Gosu JobNumberGenPlugin class is for demonstration purposes
only. You must replace the built-in implementation with your own version of the plugin before moving your system
into production.
The interface method genNewJobNumber takes an array of parameter strings and returns a non-null unique identifier
string for the job.
The input parameter strings do not have a Guidewire-defined meaning, and you can customize the use of these
parameters in user interface code that calls this plugin. You can change the Gosu code to pass values other than the
default value of null.
The JobNumberGenPlugin plugin is the built-in implementation of this interface. This plugin checks for job
numbers that already exist, and generates a new random value. The value is randomly generated using the procedure
described below.
• The first five digits increment a counter. This counter is reset at server restart.
• The last five digits are random.
For example, in a single server startup, job numbers increase. The first job is 00000<random5>, the second is
00001<random5>, the third is 00002<random5>, and so on. When the server restarts, the counter resets to zero, and
therefore job numbers do not reflect creation time. When the counter reaches the limit of five digits, the counter
increases to six digits. Therefore, the plugin returns 11 digit job numbers.

Location plugin
You can customize how PolicyCenter treats account locations and policy locations using the
AccountLocationPlugin location plugin. The base configuration of the plugin is implemented in the Gosu
AccountLocationPluginImpl class.
The basic tasks you can customize are described below.
• Customize how two location records are compared to see if they represent the same location or two different
locations.
• Customize how to copy your data model extension properties during cloning of a location entity.
If you want to add custom code after creating a primary location or before deleting a location, modify each policy
line’s methods called onPrimaryLocationCreation and preLocationDelete. Similarly, to define whether a
location is safe to delete, modify each policy line’s canSafelyDeleteLocation method.

Compare locations
Your areAccountLocationsEquivalent method must return true if two AccountLocation entities passed as
parameters are effectively equal.
The behavior in the built-in implementation returns true if and only if the following properties match:
AddressLine1, AddressLine2, AddressLine3, City, State, and PostalCode.
If you have data model extension properties on your locations that are important in the comparison, customize this
logic as needed.

Customize location cloning

If you have data model extension properties or arrays on an AccountLocation or one of its subtypes, copy them if
an account location entity clones to another account location. Implement this plugin’s cloneExtensions method to
copy these properties, including any foreign keys or array information. The built-in implementation does nothing.
Account and policy plugins 157
Guidewire PolicyCenter 9.0.6 Integration Guide

override function cloneExtensions(oldLocation: AccountLocation, newLocation: AccountLocation){

}

It is critical that you not make any changes to the related PolicyPeriod entities, Account entities, or any other
entity within this method. PolicyCenter calls this method while binding a PolicyPeriod entity. If you modify any
entity other than the new location contact, the policy could become out of sync and create serious problems later on.
Only copy your data model extensions from the old account contact to the new one and do nothing else in this
method. In particular, this method must not make changes to a related PolicyPeriod, Account, or other entity or
else serious problems can occur.

Loss history plugin

The ILossHistoryPlugin interface retrieves the loss history financial information for a particular account or policy
period.
The base configuration implements the interface in the LossHistoryPlugin class. The class methods retrieve
financial data stored in PolicyCenter. If desired, the methods can be customized to retrieve data stored in an external
system.

Retrieve loss history for an account

The getLossFinancialsForAccount method retrieves PolicyCenter financial information for all policies in a
specified account.

getLossFinancialsForAccount(accountNumber : String) : LossFinancials[]

The accountNumber argument specifies the relevant account.

The method returns an array of LossFinancials objects that contain financial information for the individual
policies in the account. Each object contains financial data for a policy's latest policy period.
The plugin method is invoked whenever PolicyCenter calls an Account entity's getLossFinancials method to
retrieve the account's financial information.

Retrieve loss history for a policy period

The getLossFinancialsForPolicy method retrieves PolicyCenter financial information for a specified policy
period.

getLossFinancialsForPolicy(policyNumber : String, periodAsOfDate : Date) : LossFinancials

The policyNumber argument specifies the relevant policy. The periodAsOfDate argument specifies an effective
date used to identify the desired policy period.
The method returns a LossFinancials object that contains financial information for the policy period in effect at
the specified periodAsOfDate.
The plugin method is invoked whenever PolicyCenter calls a PolicyPeriod entity's getLossFinancials method to
retrieve the period's financial information.

Motor vehicle record (MVR) plugin

PolicyCenter provides the IMotorVehicleRecordPlugin to request a motor vehicle record (MVR) from an external
MVR service provider. The base configuration of PolicyCenter uses a built-in implementation,
DemoMotorVehicleRecordPlugin.gs. To edit the registry for the IMotorVehicleRecordPlugin, in Studio,
navigate to configuration→config→Plugins→registry, and open the IMotorVehicleRecordPlugin.gwp file.

Overview of motor vehicle record integration

A motor vehicle record (MVR) documents a driver’s driving history. The MVR report contains information such as
identifying data, license status, convictions, traffic violations, accidents, license suspensions, and revocations. In the
158 chapter 8: Account and policy plugins
 Guidewire PolicyCenter 9.0.6 Integration Guide

U.S., the information in this report usually comes from the Department of Motor Vehicles (DMV) for each
jurisdiction. The information in the report can vary by jurisdiction. In the U.S., most service providers provide MVR
data for all jurisdictions, so you need to integrate only with a single service provider.

How PolicyCenter uses motor vehicle records

An insurer uses MVR reports to evaluate risks associated with drivers. Violations are assigned point values, with
more severe violations having a higher point value. A high MVR point total indicates a high risk driver and can
result in higher policy premiums. Agents who use PolicyCenter click Retrieve MVR on the Drivers screen of a personal
auto job to start a ProcessMVRsWF workflow. This workflow calls the IMotorVehicleRecordPlugin to retrieve
MVR reports for drivers submitted by agents.
Since there is a cost associated with retrieving reports from external MVR service providers, PolicyCenter stores the
retrieved MVR data to minimize future lookups. PolicyCenter requests the MVR report from an external service
provider only if PolicyCenter does not have a copy or if the report is considered to be stale.
The retrieved MVR report is maintained in a separate MVR repository that is independent of the driver’s account or
policy. This allows an MVR report to be reused for a driver associated with multiple accounts or policies. This also
provides flexibility as to when to update an MVR report on in-force policies. In the base configuration, the MVR
report for an in-force policy is updated at renewal or during a policy change.

See Also
• Application Guide

Implementations of the motor vehicle record plugin

The base configuration of PolicyCenter provides a built-in demonstration implementation of the Motor Vehicle
Record plugin, DemoMotorVehicleRecordPlugin.gs. This plugin implementation does not integrate with a specific
MVR service provider. Instead, it simulates the reception of MVR reports for U.S. drivers.
In the base configuration, the IMotorVehicleRecordPlugin is enabled and specifies its implementation class as
gw.plugin.motorvehiclerecord.DemoMotorVehicleRecordPlugin. Use the code in this demonstration class as
an example for writing your own motor vehicle record plugin implementation.

Writing a motor vehicle record plugin

To implement requests to a real motor vehicle record (MVR) provider, write your own Gosu class that implements
the IMotorVehicleRecordPlugin interface. Your implementation is responsible for contacting an MVR service
provider and returning MVR data to PolicyCenter. It is not responsible for determining whether PolicyCenter
already has a report for the driver in its MVR repository or whether the report in the repository is stale.

Data used by the motor vehicle record plugin

The methods defined by the IMotorVehicleRecordPlugin interface and their internal implementations use these
data-type interfaces defined in the gw.api.motorvehiclerecord package.
• IMVROrder – Information about an MVR order, such as internal or provider request IDs and order status
• IMVRSubject – Header information about an MVR order, including the search criteria for a driver
• IMVRSearchCriteria – Search criteria for an MVR order, such as the driver’s name and date of birth
• IMVRData – Incidents and licenses on a motor vehicle report
• IMVRLicense – Details of a license on a motor vehicle report
• IMVRIncident – Details of an incident on a motor vehicle report

Methods on the motor vehicle record plugin

The IMotorVehicleRecordPlugin interface defines three methods.
Account and policy plugins 159
Guidewire PolicyCenter 9.0.6 Integration Guide

Method Description
orderMVR Sends an array of orders to the MVR service provider to request reports for specific drivers
getMVROrderResponse Sends an array of orders to the MVR service provider asking which reports are ready

getMVRDetails Sends an array of orders to the MVR service to obtain reports that are ready

Each methods accept an array of IMVRSubject instances as its sole input parameter.

Notification plugin
You can customize notification dates for a variety of types of notifications. Implement the INotificationPlugin
plugin or modify the built-in implementation of this plugin. This plugin is responsible for determining the minimum
lead time and maximum lead time for different types of notifications. The law frequently specifies these values, so
define and calculate these numbers carefully.
For the methods in this plugin, the effective date is a method parameter. It specifies the date at which the action
occurs. For example, suppose the lead time is 10 days if the effective date is prior to June 5, and 15 days if the
effective date is June 5 or later. The plugin must return the value 10 for effective dates prior to June 5 and 15 for
effective dates on or after June 5. This effective date argument is never null.
Another parameter is the line to jurisdictions mapping, using generics syntax this is Map<PolicyLinePattern,
State[]>. This maps from a line of business to an array of jurisdictions. For example, imagine a commercial
package policy with two lines: general liability and commercial property. The general liability line has only one
jurisdiction (California) and the commercial property line has two jurisdictions (California and Arizona). In this
case, the passed map contains two mappings.
• One mapping from general liability to an array containing the single value of California
• One mapping from commercial property to an array containing the values California and Arizona
Large commercial policies likely have much large mappings that could contain dozens of jurisdictions. This method
parameter is never null and never empty. None of the mappings contain empty arrays of jurisdictions.
Refer to the built-in implementation of this plugin for a general pattern to use. Also, the built-in implementation of
this plugin (gw.plugin.notification.impl.NotificationPlugin) has some utility functions that you can use to
simplify your code. Specifically, look at the code for the method forAllLinesAndJurisdictions.
The built-in implementation of this plugin calculates the results based on looking up the input values in the system
table NotificationConfig (controlled by the file notificationconfigs.xml).
If you write your own version of this plugin, you can use the notification system table or use completely different
logic to calculate the lead time dates.

Notification by action type (minimum)

The first minimum lead time method has the following method signature.

int getMinimumLeadTime(Date effDate, Map<PolicyLinePattern, State[]> lineToJurisdictions,

NotificationActionType actionType)

Notice that one of the parameters is a java.util.Map that maps a policy line pattern to an array of states. Using
Gosu generics syntax, this is Map<PolicyLinePattern, State[]>. You must iterate across all the policy line
patterns and the matching list of states and calculate the minimum lead time for all combinations of line of business
and jurisdiction. Use the actionType typecode and effective date as appropriate. Your plugin method must return a
value that represents the minimum lead time as a number of number of days.
The action type is an NotificationActionType typecode to indicate the type of notification for which PolicyCenter
requests a date. A NotificationActionType includes typecodes such as those listed below.
• fraudcancel – Notification requirements in days for cancellation due to fraud
• rateincrease – Notification requirements in days for rate increases
160 chapter 8: Account and policy plugins
 Guidewire PolicyCenter 9.0.6 Integration Guide

The list of typecodes in this list is extensive. Refer to the typelist in Studio or the “Data Dictionary” for the complete
list.

Notification by action type (maximum)

There is another method with identical method signature as the previously-mentioned method except the name is
getMaximumLeadTime. That method must calculate the maximum lead time (not the minimum) for all combinations
of line of business and jurisdiction.

int getMaximumLeadTime(Date effDate, Map<PolicyLinePattern, State[]> lineToJurisdictions,

NotificationActionType actionType)

Notification by category (minimum)

Another variant of the getMinimumLeadTime method has the following method signature.

int getMaximumLeadTime(Date effDate, Map<PolicyLinePattern, State[]> lineToJurisdictions,

NotificationCategory category) throws RemoteException;

As you can see, it takes a notification category (NotificationCategory) instead of an action type.
The method uses the following notification category values in the built-in implementation.
• cancel – Cancellation notification configurations
• nonrenew – Non-renewal notification configurations
• renewal – Renewal notification configurations
The plugin must return the number of days lead time that represents the minimum value for the lead time column.
This must be the minimum value for all combinations of line of business and jurisdiction for the category and
effective date.

Notification by category (maximum)

There is another method with identical method signature as the previously-mentioned method except that the name
is getMaximumLeadTime. This method must calculate the maximum lead time (not the minimum) for all
combinations of line of business and jurisdiction.

int getMaximumLeadTime(Date effDate, Map<PolicyLinePattern, State[]> lineToJurisdictions,

NotificationCategory category) throws RemoteException;

Payment gateway configuration plugin

PolicyCenter supports electronic payment of the up-front payment for a policy job. The
PaymentGatewayConfigPlugin payment gateway configuration plugin uses properties to provide configuration
setting values for communication with an electronic payment service. The Payment Gateway plugin uses these
values to communicate with an electronic payment service.
The base configuration implements the plugin in the Gosu DefaultPaymentGatewayConfigPlugin class. You can
modify the plugin to set the configuration values that you require. Alternatively, implement your own instance of the
plugin to customize PolicyCenter application logic. You can use script parameters to specify the configuration
settings. Using script parameters avoids having to change the plugin code if your payment gateway changes. To
change the value of a script parameter, in PolicyCenter, navigate to Administration→Utilities→Script Parameters and
then click the parameter to edit.
The following Gosu code example demonstrates this approach.

class CustomPaymentGatewayConfig implements PaymentGatewayConfigPlugin {

/*
* The URL to the deployed PolicyCenter application

Account and policy plugins 161

Guidewire PolicyCenter 9.0.6 Integration Guide

* @return The value of the PolicyCenterURL script parameter

*/
override property get PolicyCenterURL(): String {
return ScriptParameters.PolicyCenterURL
}
...
}

The ScriptParameters.xml file contains the definition of the PolicyCenterURL script parameter.
The following table lists the configuration properties and their purpose.

Property Description
PaymentGatewayConnectionTimeoutInSeconds The length of time to wait for a response from the payment gateway, in sec‐
onds.
PaymentGatewayGetURL The URL for HTTP GET commands on the payment gateway. PolicyCenter re‐
directs the user to this address to take payment with a new instrument
when the RedirectToPaymentGateway property has a value of true.
PaymentGatewayPartner The payment gateway partner.
PaymentGatewayPassword The password to access the payment gateway.
PaymentGatewayPostConnectionPORT The connection port for HTTP POST commands on the payment gateway, for
example, 443.
PaymentGatewayPostURL The URL for HTTP POST commands on the payment gateway.
PaymentGatewayTransactionType The transaction type of the payment gateway command, as a
PaymentTransactionType typecode. PolicyCenter supports only the Sale
transaction type.
PaymentGatewayUser The user to access the payment gateway.
PaymentGatewayVendor The payment gateway vendor, also known as the merchant.
PolicyCenterURL The URL that the payment gateway uses to return information to
PolicyCenter, such as http://mygwpcserver:8180/pc.
RedirectToPaymentGateway Whether to redirect to the payment gateway for a payment that uses a new
payment instrument. If this property is false, PolicyCenter informs the user
that collection of electronic payment is not available.

See also
• “Implementing the payment gateway configuration plugin” on page 521
• Configuration Guide

Payment gateway plugin

PolicyCenter supports electronic payment of the up-front payment for a policy job. To customize how PolicyCenter
communicates with an electronic payment service, implement your own version of the payment gateway plugin
interface PaymentGatewayPlugin. The plugin handles communication between PolicyCenter and any payment
gateway that you need to support, such as PayPal or BarclayCard SmartPay. The interface methods provide the
typical functionality of a payment gateway.
The base configuration implements the plugin in the Gosu StandAlonePaymentGatewayPlugin class. The plugin
emulates the interaction with a payment gateway by running the PCF files in the pcf/payment/demo folder under the
Page Configuration folder. You can examine this plugin to see the basic tasks that a payment gateway performs.
Typically, you create your own implementation of this plugin to communicate between PolicyCenter and the
payment gateways that you support.
The following table lists the required methods and their purpose.
162 chapter 8: Account and policy plugins
 Guidewire PolicyCenter 9.0.6 Integration Guide

Method Description
getCardDetails Gets a representation of the credit card as a payment instrument.
inquiryPaymentGatewayTransaction Returns a payment gateway response object that contains information
about the status of a transaction.
isApprovedTransaction Returns a boolean value, which has a value of true if the specified
transaction succeeded and false otherwise. This method uses the re‐
sponse object that inquiryPaymentGatewayTransaction returns to get
this information.
isVoidedTransaction Returns a boolean value, which has a value of true if the specified
transaction has been voided and false otherwise. This method uses
the response object that inquiryPaymentGatewayTransaction returns
to get this information.
mapSilentPostRequestToPaymentGatewayResponse Returns a payment gateway response object that maps the parameters
from an incoming HTTP servlet request to payment gateway response
properties. The servlet handles closure of the browser when the user is
accessing the payment gateway.
redirectToPaymentGateway Uses exit points to redirect from PolicyCenter to the supported pay‐
ment gateways.
refundFullAmountForTransaction Returns a payment gateway response object that contains information
about an attempt to refund a credit card transaction. PolicyCenter can
perform this action only before binding a job.
requestSecureToken Returns a payment gateway response object that contains a secure to‐
ken for communication with the payment gateway as part of the pay‐
ment gateway response. Implement code for each payment gateway
that you need to support.
submitAccountVerification Returns a payment gateway response object that contains information
about the status of a new credit card verification. If the payment gate‐
way does not require this verification, create a successful response
without calling the gateway.
takePaymentUsingPaymentInstrument Returns a payment gateway response object that contains information
about an attempt to use a payment instrument to make a payment.

See also

• “Implementing the payment gateway plugin” on page 521

Policy evaluation plugin

To customize how PolicyCenter raises underwriting issues (UWIssue object) on a policy period, implement the
policy evaluation plugin interface, IPolicyEvaluationPlugin. PolicyCenter includes a built-in implementation
that raises underwriting issues and removes orphaned underwriting issues. The built-in implementation
accomplishes these tasks indirectly through other classes. You only need to modify or reimplement this plugin if you
choose an alternate way of raising and removing underwriting issues. Most likely, you can use the built-in
implementation of this plugin without any modifications. To raise and remove your underwriting issue types, you
modify the evaluator classes that this plugin uses indirectly.
If however, you choose an alternate way of raising and removing underwriting issues, the remainder of this topic
provides guidance.
The plugin interface contains only one method, called evaluatePeriod.

void evaluatePeriod(PolicyPeriod period, UWIssueCheckingPoint checkingPoint);

Account and policy plugins 163

Guidewire PolicyCenter 9.0.6 Integration Guide

Before returning from this method, your method must add all relevant underwriting issues (UWIssue objects) on the
period. Additionally, the method must remove all orphaned underwriting issues.
One of the parameters is an underwriting issue checking set typecode defined in the UWIssueCheckingSet typelist.
The typecode describes a point at which PolicyCenter can evaluate a policy and generate an underwriting issue.
Each typecode contains a Priority property that indicates the order within the typelist. High priority checking set
are evaluated first.
Use the typecode value to raise new issues appropriate for the policy. Next, remove any orphaned issues.
If you choose to modify this plugin, Guidewire recommends that your implementation use the PolicyEvalContext
class to create and remove orphaned issues because these are complex and error-prone tasks. To add an issue, use the
addIssue method on the PolicyEvalContext object.
The addIssue method finds an existing UWIssue with this type and key or, if no such issue exists, creates a new
issue. If this method returns a pre-existing issue, this method marks it as touched by setting the HumanTouched
property to true. Because pre-existing issues are marked touched, the removeOrphanedIssues method (see later in
this topic) does not remove them.
For example, you can create a new issue with the following code.

var context = new PolicyEvalContext(period, checkingPoint)

var newIssue = context.addIssue( "PAHighValueAuto", "testissue", "this is a longer description", null )

Just as in the built-in implementation, you can use the PolicyEvalContext object to remove old issues using the
PolicyEvalContext.removeOrphanedIssues() method. That method removes or marks as inactive all issues for
which both of the following conditions are true.
• The issue existed at the time PolicyCenter created the context object.
• No previous call to the addIssue method on PolicyEvalContext affected this issue.
The method removes any issues that are open or marked no longer applicable. In contrast, for issues that are
approved or declined, this method marks them as inactive.

See also
• Configuration Guide

Policy hold job evaluation plugin

PolicyCenter uses the IPolicyHoldJobEvalPlugin plugin to configure policy holds in the policy hold batch
process. A batch process called Policy Hold Job Evaluation runs nightly to reevaluate the policy holds that changed
and no longer apply to the job. You can also run this batch process manually. Refer to the Batch Process Info menu
item in the Server Tools page.
By default, this batch process performs the following operations.
1. Checks if the policy hold was modified and no longer applies to the job.
2. If so, sends activity reminders to producers to retry quote or bind of the job.
To support this behavior, a policy hold (PolicyHold) contains an array of PolicyHoldJob entity instances. They
keep track of jobs that are currently held by a policy hold and the last time the job evaluated against the policy hold.
A PolicyHoldJob consists of the following fields.
• PolicyHold – A foreign key to the policy hold
• Job – A foreign key to the job
• LastEvalTime – The last time this job was evaluated against this policy hold
A PolicyHoldJob is created when PolicyCenter evaluates the Policy Holds Type Filter checking set and determines
that an underwriting issue needs to be raised. In the base configuration, PolicyCenter evaluates the checking set in
the DefaultUnderwriterEvaluator class.
PolicyCenter updates LastEvalTime when the batch process reevaluates a job against a policy hold. The
PolicyHoldJob row for that policy hold and job is deleted if the hold no longer applies to the job and an activity
reminder is sent to the producer.
164 chapter 8: Account and policy plugins
 Guidewire PolicyCenter 9.0.6 Integration Guide

IPolicyHoldJobEvalPlugin exposes the methods that this batch process uses to find jobs that need to be
reevaluated and how to evaluate it. This plugin interface has two methods.
To find jobs that need to be evaluated against the policy holds blocking them, implement the following method.

public IQueryBeanResult<PolicyHoldJob> findJobsToEvaluate();

In the base configuration, this plugin is implemented by PolicyHoldJobEvalPlugin and finds jobs that have any of
the following qualities.
• Open jobs
• Jobs with policy periods with a active blocking policy hold
• Jobs not evaluated since the last time the policy hold changed
To evaluate a job against a policy hold, implement the following method.

public void evaluate(PolicyHoldJob policyHoldJob)

In the built-in plugin implementation, the evaluate method checks if the policy hold has been deleted or the hold
changed to cause the job to no longer match. If so, the method creates an activity and assigns to the producer.

Policy number generator plugin

The IPolicyNumGenPlugin interface is responsible for generating a policy number for the current policy period.
This number differs from the policy number associated with the root Policy object which is shared by all periods of
the policy. The policy number for the current policy period is associated with a particular instance of a
PolicyPeriod object and can vary from one period to another.
The plugin interface has a single method called genNewPeriodPolicyNumber.

genNewPeriodPolicyNumber(policyPeriod : PolicyPeriod) : String

The policyPeriod argument references the PolicyPeriod entity to generate a policy number for.
The method returns the generated policy number as a String.
The method is called as part of a Submission job when creating the first period of a policy and also when rewriting
or renewing a policy. If the user attempts to rewrite a policy, the PolicyCenter user interface provides a choice
between reusing the current policy number or generating a new one. Depending on the user's selection, the value of
the Rewrite.isChangePolicyNumber is set appropriately. If set to true, PolicyCenter calls the plugin to generate a
new number.
The base configuration implements the plugin in the PolicyNumGenPlugin class. This implementation is for
demonstration purposes and must be configured prior to being placed in a production environment. Its single public
method always generates a new and random policy number if the policyPeriod argument's Status field is set to
the typecode value of PolicyPeriodStatus.TC_LEGACYCONVERSION. Otherwise, the Job field of the policyPeriod
determines whether to generate a new policy number. If the Job is of type Submission, Rewrite, or
RewriteNewAccount, a new and random policy number is generated. For all other types of Job, such as Renewal,
the policyPeriod object's PolicyNumber field value is returned.

Policy numbers conform to field validator

PolicyCenter includes a feature called field validators that help you ensure accurate input within the web application
user interface. In the case of policy numbers, field validators ensure that user input of a policy number exactly
matches the correct format. The following example shows a policy number field validator.

<ValidatorDef name="PolicyNumber" value="[0-9]{3}-[0-9]{5}"

description="Validator.PolicyNumber"
input-mask="###-#####" />

Account and policy plugins 165

Guidewire PolicyCenter 9.0.6 Integration Guide

If you are implementing policy number generator code for the first time, you must configure the policy number field
validator so that it matches the format of your policy number. After you first implement a policy number generator
or later change the policy number format, coordinate changes to the field validators or user entry of policy numbers
fails.

Policy payment plugin

To customize how PolicyCenter generates a list of available reporting plans for a policy, implement your own
version of the policy payment plugin interface, IPolicyPaymentPlugin.
The plugin has only a single method, which is called filterReportingPlans. This method takes a Policy entity
and an array of PaymentPlanData objects. Your method must return an array of payment plan data objects
(PaymentPlanData), which collectively represents the subset of plans that are available for the policy. You can use
properties on both the policy period and the payment plans to filter the payment plans to return. For example, you
can use the AllowsPremiumAudit property on the policy period to determine whether to return payment plans that
allow premium reporting.
You can return the same array as was passed in. You do not have to generate a new identical array if you do not need
to perform any filtering.
In the base configuration, for a policy period that allows premium reporting, this method returns all payment plans.
For a policy period that does not allow premium reporting, this method returns only non-premium-reporting
payment plans.
The following example implementation filters payment plans. If the policy allows premium reporting, the meth