Web services
Web services provide a language-neutral, platform-neutral mechanism for invoking actions or requesting data between applications across a network.
Web services define request-and-response APIs that enable one web-based application to call an API on another web-based application by using an abstracted, well-defined interface. A data format, the Web Service Description Language (WSDL), describes available web services that other systems can call by 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.
Remote systems call PolicyCenter web services by using the SOAP protocol (Simple Object Access Protocol). 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 conforms to the requirements defined by the WS-I Basic Security Profile 1.1. Consumers of PolicyCenter web services must also be compliant with the profile.
PolicyCenter web services are written in the Gosu programming language. PolicyCenter publishes foundational web services that, when configured with additional code, can be deployed in a production environment.
Publishing or consuming web services from Gosu
Gosu natively supports web services in two ways:
- Calling web service APIs published by external applications
- Write Gosu code that imports and calls web service APIs published by external systems. Gosu parses the web service definition (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 by using Gosu syntax.
- Publishing your Gosu code as new web service APIs
- Write Gosu code that external systems call as a web service by using the SOAP
protocol. Add a single line of code before the definition of the implementing Gosu
class. The application parses the class methods, generates WSDL, and publishes the web
service to external systems.Important: Your web service definition in 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, do not change the WSDL. For example, do not modify data transfer objects (DTOs) after going into production or after widely distributing the WSDL in a user acceptance testing (UAT) environment.
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 that you write a web service in Gosu, 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 into a text-based reply to the remote system.
- Suppose that you use Gosu to call a web service hosted by an external system. Before calling the API, Gosu 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 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, to trigger actions, or to change data in the PolicyCenter database.
Publishing a web service can be as simple as adding a 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 web services in the base configuration
The following tables list all the web services in the base configuration.
Job-related web services
|
Web Service Name |
Description |
More information |
|---|---|---|
|
CancellationAPI |
Starts a cancellation job or rescinds a cancellation that has not completed. |
|
|
JobAPI |
Adds an activity to a job. |
|
|
PolicyChangeAPI |
Starts a policy change job. |
|
|
PolicyRenewalAPI |
Starts a renewal job. |
|
|
ReinstatementAPI |
Starts a reinstatement job for a policy that has been canceled. |
|
|
SubmissionAPI |
Starts a submission job. |
Other application web services
|
Web Service Name |
Description |
More information |
|---|---|---|
|
AccountAPI |
Performs various actions on an account, such as adding a note or a document. |
|
|
AddressAPI |
Notifies PolicyCenter of updates to addresses from an external contact system. |
|
|
ArchiveAPI |
Manipulates archiving from external systems. |
|
|
|
Retrieves policy summaries for claim systems such as ClaimCenter. If you configure ClaimCenter to connect to PolicyCenter, ClaimCenter uses this web service automatically. |
|
|
ClaimToPolicySystemNotificationAPI |
Notifies PolicyCenter about large losses on a claim. If you configure ClaimCenter to connect to PolicyCenter, ClaimCenter uses this web service automatically. |
|
|
ContactAPI |
Notifies PolicyCenter of changes to contacts, including merging of contacts and merging of contact addresses. |
|
|
ImportPolicyAPI |
Import policies from XML data from an external system. |
|
|
PolicyAPI |
Control policy period referral reasons and activities from an external system. |
|
|
PolicyEarnedPremiumAPI |
Calculates earned premiums for a policy number as of a specific date. |
|
|
PolicyLocationSearchAPI |
Retrieves a list of policy location summaries within a rectangular geographic bounding box. |
|
|
PolicyPeriodAPI |
Performs various actions on a policy period, such as adding a note or a document. |
|
|
PolicySearchAPI |
Retrieves the public ID of a policy period based on a policy number and a date. |
|
|
ProducerAPI |
Performs various actions on producers, agencies, and branches. |
|
|
ProductModelAPI |
Modifies the Product Model on a running development (non-production) server. |
|
|
PurgeAPI |
Manipulates quote purging by flagging whether to purge a policy or policy period. |
|
|
RICoverageAPI |
Finds reinsurance risk information for use by an external system. This web service requires Guidewire Reinsurance Management, which you license separately from PolicyCenter. |
General web services
|
Web Service Name |
Description |
More information |
|---|---|---|
| AdminDataAPI | For Guidewire use only. Do not use. | |
|
DataChangeAPI |
Tool for rare cases of mission-critical data updates on running production systems. |
System Administration Guide |
|
|
Imports administrative data from an XML file. You must use this only with
administrative database tables (entities such as |
|
|
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. |
|
|
MaintenanceToolsAPI |
Starts and manages various background processes. The methods of this web service
are available only when the server run level is |
|
|
MessagingToolsAPI |
Manages the messaging system remotely for message acknowledgments error recovery.
The methods of this web service are available only when the server run level is
|
|
| PersonalDataDestructionAPI |
Enables an external application to request the following:
|
|
|
ProfilerAPI |
Sends information to the built-in system profiler. |
|
|
ServerStateAPI |
Provides information about the state of the server that runs the PolicyCenter application, such as the run level and the server name. |
|
|
SystemToolsAPI |
Performs various actions related to server run levels, schema and database consistency, module consistency, and server and schema versions. The methods of this web service are available regardless of the server run level. |
|
|
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. Important methods of this web service are available
only when the server run level is |
|
|
TemplateToolsAPI |
Lists and validates Gosu templates available on the server. |
|
|
TypelistToolsAPI |
Retrieves aliases for PolicyCenter typecodes in external systems. |
|
|
WorkflowAPI |
Performs various actions on a workflow, such as suspending and resuming workflows and invoking workflow triggers. |
|
|
ZoneImportAPI |
Imports geographic zone data from a comma separated value (CSV) file into a staging table, in preparation for loading zone data into the operational table. |