Inbound Web Services

by | Jun 15, 2018 | Member News

Hari Kanangi on June 14, 2018

SOURCE CODE: All the source code discussed within this blog is provided @ GitHub – Codebase. You are free to download, extend and send me comments on how you used it. If you want the extensions/changes to be incorporated into the code for others to use or alternatively would like to be part of the group that updates this GitHub project repository, send me a request and I will certainly get back to you. [Link: https://github.com/harikanangi/custom-gosu]

As a leader on several Guidewire Insurance Suite?1 implementations, I have noticed/come across multiple project implementations where designs and development are inconsistent in spite of availability of standards and governance procedures in place.  These inconsistencies unfortunately and inevitably lead to consistent and predictable problems throughout the project lifecycle (resource on-boarding, integration frustration, project technology governance issues, maintenance/support etc).

There are several different and some arguably valid reasons for these inconsistencies

  • Both Business and IT teams of insurance companies implementing the Guidewire Insurance Suite Solution are new and unfamiliar to the architecture of Guidewire and GOSU.

  • Fast paced and short inceptions in projects do not allow the project technical teams (with or without systems integrators) to fully understand the capability, availability of all architectural components (Infrastructure, Software, Framework, Plugins) within the company’s IT team and put in place appropriate application level frameworks that promote for consistency across integrations for the project.

  • As with any technology, lack of experienced technologists/architects within the Guidewire space to envision and bring together the company’s existing IT and Guidewire (processes, architecture, infrastructure, security, components, frameworks, plugins and development tools) technology into a set of consistent and manageable patterns.

  • And some invalid reasons that also occur during the course of the project including large teams with multiple team members working on different integrations failing to adhere to project standards due to schedules or lack of understanding of the overall design.

In this series, the intent is to tackle the various integration mechanisms within the Guidewire Insurance Suite (primarily SOA based Web Services (since Guidewire naturally has support built in for SOAP (vs REST)) with focus on SOAP and use SOAP and web services interchangeably), Message Destinations (Synchronous/Asynchronous) and Batch – Although ETL is yet another mechanism we will leave this for another discussion in its entirety) and provide mechanisms that promote to achieve consistency across the project implementation. This in turn leads to better quality of the product being delivered to the business and support/maintenance team. This set of simple designs/mechanisms/pre built tools/components/documentation will additionally provide every project the head start needed to achieve consistency and most importantly allow the project to be delivered on time and within budget.

If you are still reading this article – there is an assumption made that you understand the basic Guidewire Insurance Suite architecture, its development tools and the GOSU language.To make this exercise useful you will find attached the complete source code of the designs discussed in each installment.

In the first installment of the series lets take a look at Web Services hosted on the Guidewire platform (Service Provider) that are consumed by clients (typically by an Enterprise Service Bus or in a point to point scenario service clients like legacy systems, enterprise scheduler software and other third party systems) – these are inbound integrations into Guidewire through web services consumed by External service consumers (or from one Guidewire product to another ex: PolicyCenter to BillingCenter).

For inbound services the basic typical design issues, beyond implementing the service functionality accurately and efficiently,  exist

  • How does the web service interface look to service clients that integrate call multiple services? After the first inbound web service integration is completed, is there consistency with other integrations as they become available during the project development cycle so the integration itself becomes easier or is it a struggle to integrate each time a new inbound web service is exposed to service clients?

  • Is there a consistency or are there a few manageable patterns defined for all web services exposed by Guidewire Components?

  • Does the design allow the service side developers to focus exclusively on implementing just the functionality of the service and not worry about the service level concerns?

  • Is the design flexible and allow the service implementation development team to use and expose all of Guidewire Insurance Suite’s entities including POGO objects, GX Models and XSD schema objects to service clients consuming the service?

  • How are exceptions returned back to the user?

  • Do all the web services handle exceptions/use logging in a standardized manner for support/maintenance to monitor and react?

  • Does the governance on the project require additional custom SOAP service headers on all service communications?

And of course this list can be expanded but if we can address the above consistently across all web services that will be consumed we have achieved our goal within the project implementation.

The design for the inbound web services uses a basic premise -The service interface to external clients consuming Guidewire WS-I web service interfaces fall into one of the following 5 patterns

  • POGO (plain old GOSU object) Input/Output Parameters

    • Case 1: The input to the web service will be a single POGO instance of a GOSU class ex: the service method interface will take a single GOSU POGO instance that encapsulates all the information/data required to implement the business functionality of the service and return a single GOSU POGO instance or an array of GOSU POGO instances as response to the service client.

    • Case 2: The input to the web service will be an array of POGO instances of a GOSU class ex: the service method interface will take a single array of GOSU POGO instances that will encapsulate all the information/data required to implement the business functionality of the service and return a single GOSU POGO instance or an array of GOSU POGO instances as response to the service client.

  • GX Model Input/Output Parameters

    • Case 1: The input to the web service will be a single GX Model instance of an entity ex: the service method interface will take a single GX Model instance that encapsulates all the information/data required to implement the business functionality of the service and return a single GX Model instance or an array of GX Model instances as response to the service client.

    • Case 2: The input to the web service will be an array of GX Model instances of an entity ex: the service method interface will take a single array of GX Model instances that will encapsulate all the information/data required to implement the business functionality of the service and return a single GX Model instance or an array of GX Model instances as response to the service client.

  • XSD Schema Input/Output Parameters

    • Case 1: The input to the web service will be a single XSD Schema instance ex: the service method interface will take a single XSD Schema instance that encapsulates all the information/data required to implement the business functionality of the service and return a single XSD Schema instance or an array of XSD Schema instances as response to the service client.

    • Case 2: The input to the web service will be an array of XSD Schema instances of an entity ex: the service method interface will take a single array of XSD Schema instances that will encapsulate all the information/data required to implement the business functionality of the service and return a single XSD Schema instance or an array of XSD Schema instances as response to the service client.

  • Mixed Model

    • This is when the input is from one of the models above (POGO, GX Model or XSD Schema) and the output is of another kind ex: the service method interface will take a single array of GX Model instances that will encapsulate all the information/data required to execute the service and return a single XSD Schema instance as response to the service client.

  • No Input/Output Parameters

    • The design should also accommodate the case when the service requires no input (ex: GetAllUsers) OR needs to provide no output to the calling consumer (service client).

To do this lets put in place a simple extensible design that will accomplish most of the above right of the bat and can be extended easily to address additional cross cutting concerns like custom error handling, project governance fulfillment etc (Note: The design uses anonymous blocks, class and method level generics and assumes the reader’s proficiency in these areas)

  • IBaseEntity: To promote consistency within a project, this is an interface that all custom GOSU classes to be used as model/data transfer entities implement. This basic interface can be leveraged to solve issues with regards to several cross cutting concerns (including logging, exception handling etc.) – This interface plays that role and includes two properties that describe the object.

  • IWsiServiceEntity: This is a marker interface that all GOSU class based input and output service parameters for all inbound WS-I services implement.

  • WsiServiceParameterWrapper: Internally used by the design to represent either input or output parameters.

  • ServiceExecutorWsi: Internally used by the design and responsible for invoking the implementation of the service, controlled in turn by WsiServiceBaseAPI. This execute method of this class primarily supports the execution of the following eight service types with different kinds of input and output parameters (ex: taking in a instance of a type and returning an array of instances of another type (or the same type) etc.). At this point, you may want to quickly peruse this class in the source code provided to look at the 8 service types. Additionally 4 of the service types also support the wsi invocation context that can be used to extend the functionality for handling any custom SOAP headers that may be required to be added within the project implementation.

  • WsiServiceBaseAPI: This is the base class for all inbound WS-I web service implementations (denoted with the use of @WsiWebService annotation). The design is based on method level generics and anonymous blocks – the main driver for this is to preserve the ability for sub classes to expose multiple service methods within the same class service implementation. It provides a mechanism for consistent handling of service calls. This base implementation provides the following services

    • Overloaded wsiExecute and wsiExecuteAndReturnArray methods: These provide the base implementations that all service method implementations will invoke. wsiExecute is to be invoked by all methods that return a single instance of an POGO, GX Model or XSD entity and wsiExecuteAndReturnArray is to be invoked by all methods that return multiple instances of POGO, GX Model or XSD based entities.

    • Exception Handling: By default – SOAP Faults are returned to the client, all web service clients extending WsiServiceBaseAPI do not have to wrap operations around try/catch, unless it is meaningful to and the service implementation can recover from certain specific exception scenarios, to catch and log exceptions during the service call.

    • Logging: By default WsiServiceBaseAPI creates a logger when instantiated – the name of the logger is based on the input parameter passed into the constructor. Ex: If AdminAPI extends WsiServiceBaseAPI and passes in “AdminAPI” as the name of the service in the constructor, a logger with a category of “Integration.AdminAPI” is instantiated. The properties of this logger can be controlled through the logging.properties file. This logger is available to all subclasses. In addition, without any further code, the inputs and outputs are logged in debug mode and approx. time taken to execute the service is logged in info mode.

    • Consistency: Everything from inputs/outputs exposed to service clients to format of the log messages is standardized and once understood all services look and feel the same to the development team.

    • Additionally, the WsiServiceBaseAPI class is designed to be extensible. Some reasons for extending this class are

      • Generically handle custom SOAP headers introduced as part of project IT Governance and processed by every inbound WS-I service.

      • Integrate with notification software for custom exception/error handling of services, or have associate levels/severity to errors when errors do occur.

      • Further standardize and provide a business service handling framework that provides transaction support, input validation etc. for all inbound services.

Lets take a look at the 3 example service implementations, one each for POGO, GX Model based, XSD based input/outputs, where each service implementation exposes multiple inbound services to service clients and demonstrate how the design promotes consistency and simplifies the implementation.

  • POGO Based Service Example

  • GX Model Based Service Example

  • XSD Based Service Example

See other blog entries under Source Code for details.

NOTES:

This is a detailed introduction to the design/implementation to handle inbound web services hosted within the Guidewire Insurance Suite in a way that promotes consistency in implementations – further analysis of the code along with the examples that is provided will clarify the implementation specifics

Translate »