OneSpan Sign Accelerator for ClaimCenter

The OneSpan Sign Accelerator for ClaimCenter integration provides a seamless integration between Guidewire ClaimCenter and OneSpan Sign, allowing ClaimCenter users to trigger electronic signature workflows from within ClaimCenter. It is an event-driven integration that uses app events webhooks, offering a modern, robust, and scalable solution. This API based integration replaces a traditional Gosu integration making it easier to maintain and scale. This integration includes:

API-driven business logic implemented by OneSpan iPaaS solution partner.
Seamless creation and management of OneSpan Sign packages via ClaimCenter events.
Rich package, signer, and document-level features specified at the OneSpan Sign account through event-driven architecture powered by Guidewire Cloud APIs.
Automatic download of signed documents back to ClaimCenter.

Intended Audience

The rest of the topics in this section are intended for the following:

Customer Implementation Managers
Implementation Architects/Consultants
Business Analysts
Integration Architects/Developers

The following items are not included in this reference implementation:

This topic focuses on the interactions between ClaimCenter and the OneSpan Sign platform and will not provide generic implementation details for integrating to OneSpan Sign. Detailed descriptions of the features and integrations offered by the OneSpan Sign platform are available on the OneSpan website at https://www.onespan.com.

The implementation does not explicitly include security information that may be desired by an implementation. Security for the integration calls to OneSpan Sign is provided and detailed in the relevant section below.

The referenced implementation does not make use of the Guidewire User/Role security model, although it is easily added. It is up the implementation to determine and implement the users, roles, and permissions that are relevant to a specific configuration.

Impacted Systems

The following systems are involved in, or are affected by, this solution:

OneSpan Sign
Guidewire ClaimCenter Cloud
Guidewire App Events Webhooks
Workato - OneSpan iPaaS solution partner

General Workflow

The following provides a general overview of a OneSpan Sign Accelerator for ClaimCenter workflow. For more detailed instructions on how to use OneSpan Sign Accelerator for ClaimCenter see Using OneSpan Sign Accelerator for ClaimCenter

Webhook Event Triggered Integration

A ClaimCenter custom event - SendToOSS - triggers the integration.
This in turn triggers an iPaaS recipe that collects signer information from the Claim Contacts.
The document that triggers the integration is uploaded and used to assemble the OneSpan Sign package. Note that this document needs to be pre-tagged by either OneSpan Sign Text Tags or Document Extraction.
When the OneSpan Sign package is successfully created, a success message is returned, as an activity.
If the creation fails, a failure message with the failure reason is sent back, also as an activity.

Post Signing Process

Once the signing is complete, the following takes place:

The OneSpan Sign Integration Framework triggers the iPaas recipe to download the signed document back to the Claim's document section.
A success message is sent in an activity, and the OneSpan Sign package is then archived.

Using OneSpan Sign Accelerator for ClaimCenter

The following provides more detailed instructions on how OneSpan Sign Accelerator for ClaimCenter works. In general, this process involves the following:

The creation of a OneSpan Sign Package using Guidewire ClaimCenter
The archiving of the package, once all signing is complete

Creating a OneSpan Sign Package using ClaimCenter

The OneSpan Sign package creation process begins by selecting specific account contacts who will act as the e-signature recipients. Custom roles such as “OneSpan Signer1,” “OneSpan Signer2,” and “OneSpan Sender” are introduced to define these roles.

After adding the custom claim contacts, the user moves to the Claim Documents screen.

When one or more documents are selected from the document list, the “Send for e-Sign” button becomes enabled. Clicking the button triggers the SendToOss custom event.

Depending on the document type, users receive an immediate success or failure message if the selected document type is unsupported.

The triggered SendToOss event initiates an iPaaS recipe in the background to perform the package creation, covering the following capabilities:

Package Properties
- OneSpan Sign Package Name
- Description
- Expiry Date
- Language
- Time zone
- Enable In-Person Signing
- Package email message
- Reminder Notification
- Send on Behalf of
Signer Information Collection
- First Name (required)
- Last Name (required)
- Email Address (required)
- Phone Number
- Authentication Method (e.g., SMS, ID Verification)
- Signing Order
Document Management
- Document order can be set based on criteria such as Last Modified Date (Ascending/Descending) or Name (Ascending/Descending).

Once the OneSpan Sign package is either successfully created or fails, an activity will be added to the current claim, logging the result.

Archiving a Package

The archival process is fully automated once the signing process is completed. Upon completion of signatures by all signers, the OneSpan Sign Integration Framework triggers an iPaaS recipe. The signed document is downloaded into the claim’s document section within ClaimCenter.

A success message is sent as an activity in ClaimCenter, indicating the successful completion of the package.

The package status changes from ARCHIVAL_PENDING to ARCHIVAL_COMPLETED in the OneSpan Sign application.

Logging and Error Notifications

Logging and error management relies on OneSpan Sign, GuideWire Cloud, and iPaaS logging systems. The following points outline this approach:

OneSpan Sign Error Notifications: OneSpan Sign account owners will receive notification emails detailing any errors that occur during the integration process.
OneSpan iPaaS solution partner Logging System: All integration-related logs are stored and managed within OneSpan iPaaS solution partner. Customers can reach out to OneSpan Sign support for detailed tracking and troubleshooting information.
GuideWire Cloud Application Logs: Logs within Guidewire Cloud conform to Guidewire's privacy standards and ensure that no Personal Identification Information (PII) is included.

Technical Overview

The Technical Overview provides a brief introduction to the components and flow of the OneSpan Sign integration with Guidewire ClaimCenter using OneSpan iPaaS solution partner as the business logic layer. The key sections within the technical design include:

ClaimCenter Cloud API: The APIs used to interact with ClaimCenter, allowing retrieval of claim documents, signer information, and posting activities related to e-signature processes.
OAuth2 Permissions: Describes the required OAuth2 permissions for accessing ClaimCenter APIs, and how the OneSpan Sign integration is securely authorized.
Automating the Integration via Gosu Code: Describes how the integration can be automated using Gosu code. Integrators can use the example code in their workflows or leverage out-of-the-box Guidewire events for full automation, enhancing flexibility and efficiency.
Security Requirements and Risks: Focuses on how the integration ensures data security and compliance, including webhook security, encryption, and risk mitigation strategies.

ClaimCenter Cloud APIs

This integration leverages several key Guidewire ClaimCenter Cloud APIs to perform key tasks related to e-signature functionality. These APIs enable the seamless exchange of data between Guidewire ClaimCenter and OneSpan Sign.

The following API endpoints, extracted from the OAuth2 role permission file, are critical to the integration:

To retrieve Claim Contacts

GET /claim/v1/claims/*/contacts: This endpoint retrieves contact details for the specified claim, which are used to populate signer information in OneSpan Sign.

To retrieve Claim Document Content

GET /claim/v1/claims/*/documents/*/content: This API call is used to fetch the content of documents associated with a claim, allowing iPaaS to upload them into OneSpan Sign.

To Post Activities to a Claim

POST /claim/v1/claims/*/activities: This API is used to log activities such as success or failure messages related to the e-signature package creation or document signing process.

To Upload Documents to a Claim

POST /claim/v1/claims/*/documents: This endpoint allows the integration to upload signed documents back into the ClaimCenter document section after the signing process is completed.

OAuth2 Permissions

To securely interact with the ClaimCenter APIs, the integration requires a registered OAuth2 client with specific permissions. These permissions are defined in the sasolnpart_onespan-client.role.yaml file provided in the implementation.

This file includes an example role definition that specifies the necessary API endpoints and methods, ensuring that the OneSpan Sign integration can:

Retrieve claim contact details
Access and manage claim documents
Log activities for status updates
Upload signed documents back to the ClaimCenter

Refer to the sasolnpart_onespan-client.role.yaml file for the complete role definition and permissions required for this integration.

Automating the Integration via Gosu Code

The SendToOss functionality can be triggered programmatically using Gosu code, offering Guidewire integrators flexibility to invoke the integration at any point in their business workflow. The following code snippet shows how the integration can be automatically triggered by passing a list of documents and a claim as input:

static public function sendToOss(docs : Document[], claim : Claim) {
  try {
    var publicIDs = new ArrayList<String>()
    for (doc in docs) {
      if (!_isAllowedMimeType(doc)) {
        throw new DisplayableException(DisplayKey.get("Accelerator.OneSpan.InvalidMimeTypeMsg", doc.Name, doc.MimeType))
      }
      publicIDs.add(doc.getPublicID())
    }
    Transaction.runWithNewBundle(\bundle -> {
      var bundleClaim = bundle.add(claim)
      bundleClaim.OssDocumentList_Acc = String.join(";", publicIDs)
      bundleClaim.addEvent('SendToOss')
    })

    _handleSuccess('Accelerator.OneSpan.SendClaimSuccessMsg', claim.ClaimNumber, #sendToOss(Document[],Claim))
  } catch (e : Exception) {
    _handleFailure('Accelerator.OneSpan.SendClaimFailureMsg', claim.ClaimNumber, e, #sendToOss(Document[],Claim))
  }
}

Guidewire integrators can use a code snippet similar to the one provided to automate the integration process in their own business workflows. For example for post document generation, after a specific document is generated, integrators can insert a code snippet like the sendToOss() function into their existing workflow. This would automatically trigger the signing process without requiring manual intervention. By adapting the provided Gosu code, integrators can ensure a seamless flow between document generation and e-signature initiation.

Additionally, integrators may choose to leverage Out-of-the-Box Guidewire Events to trigger the integration. Instead of using the custom SendToOss event, integrators can utilize an existing event that aligns with their specific business logic. This approach allows for a fully automated process, where the integration is triggered at predefined points within the ClaimCenter system, such as after a claim is created or updated.

These two options provide flexibility depending on whether the integration is tied to custom logic or existing system events.

Security Requirements and Risks

Security is a crucial aspect of this integration, particularly given the sensitive nature of claim documents and signer information. The following security measures are implemented:

Authentication and Authorization:

OAuth2 Authentication: The integration uses a registered OAuth2 client to authenticate and authorize access to both Guidewire Cloud APIs and OneSpan Sign APIs. This ensures that only authorized clients can access the necessary resources.
Role-Based Access Control (RBAC): In Guidewire ClaimCenter Cloud, permissions are scoped to only allow access to the required APIs and fields, limiting potential exposure to sensitive data.

Webhook Security:

Guidewire App Events Webhook: Webhooks sent from ClaimCenter to iPaaS are authenticated via RSA key signing. This ensures the integrity of the event data, preventing unauthorized events from triggering the integration.
OneSpan Sign Webhook: Webhooks sent from OneSpan Sign to iPaaS are secured by a secret token, ensuring that only legitimate payloads from OneSpan Sign are processed.

IP Whitelisting:

Guidewire Cloud requires IP whitelisting to restrict access to the integration. Only pre-approved IP addresses from trusted data centers can interact with the APIs and send or receive webhooks.

Data Privacy and Compliance:

Secure Logging: Logs in Guidewire Cloud, OneSpan Sign and iPaaS adhere to data privacy regulations, ensuring that no Personal Identifiable Information (PII) is stored in log files. Only metadata and event details are logged.
Encrypted Data Transfer: All communication between Guidewire Cloud, iPaaS, and OneSpan Sign is encrypted using HTTPS, ensuring that data (e.g., claim documents and signer details) cannot be intercepted or tampered with during transmission.

Risk Mitigation Strategies:

Timeouts and Retries: API calls and webhooks are configured with timeout and retry logic to handle temporary network failures or service outages, ensuring the integration remains reliable.
Audit Logs: Detailed audit logs are maintained across all systems (Guidewire, iPaaS, OneSpan Sign) to track integration activities and detect any security issues or anomalies.

These security measures ensure that the integration remains robust, secure, and compliant with industry standards.

Deployment - Guidewire Configurations

To ensure the OneSpan Sign integration with Guidewire ClaimCenter Cloud is properly configured, follow these steps:

Submit a Guidewire Support Ticket to have the OneSpan iPaaS solution partner’s data center IP addresses whitelisted to allow communication between Guidewire Cloud and iPaaS platform. You can refer to IP allowlist documentation here.
Register an OAuth2 Client.
- Register an OAuth2 client in Guidewire Hub. The Type of Authentication for this client should be set to Standalone Service.
- The application name used in this solution is "onespan-client".
- Use the Guidewire support case template provided by Guidewire Support to complete this process.
Clone and Setup the ClaimCenter Cloud Project:
- Clone and check out a new branch for your Guidewire ClaimCenter Cloud project.
- Deploy the accelerator files to your local deployment environment. Refer to the following section for a detailed file manifest.
Rename the OAuth2 Client Role YAML File:
- Locate the OAuth2 client role definition file at /modules/configuration/config/integration/roles/sasolnpart_onespan-client.role.yaml.
- Rename the file to match the actual OAuth2 client name provisioned by Guidewire Support in step 2.
Configure Guidewire App Events Webhooks:
- Configure the Guidewire App Events Webhooks to point to the iPaas recipe callback URLs. This enables the integration to trigger the SendToOss event within ClaimCenter and communicate with iPaas.
- The iPaas recipe callback URLs will be provided by OneSpan Sign support.
- Use the Guidewire Public Key URL to retrieve the RSA public key in JWK format (you can find the URL in the Information tab). Share the n value (modulus) from this response with OneSpan Sign support for secure communication. An example of the JWK format is:
  { "keys":[ { "kty":"RSA", "e":"AQAB", "n":"xceNdCq49Pxxxxxxupa7bk5w" } ] }
Add Custom Activity Patterns:
- Import the provided Custom Activity Pattern.xml file, which contains two custom activity patterns (OneSpan Sign Success Activity and OneSpan Sign Failure Activity), into your Guidewire ClaimCenter environment, under ClaimCenter Admin Data.
- This Custom Activity Pattern.xml file is included in the implementation package.
- If you choose to use an out-of-the-box activity pattern instead of the custom patterns, ensure that the selected activity pattern is available for your integrated claims.

Data Model Extensions

Existing Entities

Claim.OneSpan.etx: A custom event and a varchar field have been added

Existing Typelists

ContactRole.OneSpan.ttx: Introduced 6 custom Claim contact roles
DocumentType.OneSpan.ttx: Introduced 1 custom Document type

User Interface Modifications

Existing PCF Files:

ClaimDocuments.pcf : Addition of the Send for e-Sign button

Configuration Files

Below is a list of all files included in this configuration for the OneSpan Sign integration with Guidewire ClaimCenter Cloud:

config

\contact

entityroleconstraints-config.xml (line 53-58, line 170-175)

\conf

\entity
- Claim.OneSpan.etx
\typelist
- ContactRole.OneSpan.ttx
- DocumentType.OneSpan.ttx
\integration
- \mappings\ext\claim\v1
  - claim_ext-1.0.mapping.json (line 8-17)
- \roles
  - sasolnpart_onespan-client.role.yaml
- \schemas\ext\claim\v1
  - claim_ext-1.0.schema.json (line 8-16)
\locale
- display.properties
\logging
- log4j2.xml (line 72-79, line 383-388)
\web\pcf\claim\documents
- ClaimDocuments.pcf (line 87-92)

gsrc

\acc\oneSpan
- OneSpanUIHelper.gs

Deployment - OneSpan Sign Configurations

This event-driven integration uses OneSpan iPaaS to connect Guidewire ClaimCenter Cloud and OneSpan Sign via webhook callbacks and Cloud APIs. The iPaaS platform enables internal logic by invoking Guidewire and OneSpan Sign APIs through imported OpenAPI specification files.

To begin your setup, please work with your sales team or contact our Support Team to arrange for your environment to be prepared. Below are the features and settings provided in this solution to tailor the business workflow according to your unique requirements. Ensure these details are enclosed with your request:

Name	Required	Description	Example Value	Default Value
GuideWire Webhooks public key	true	The RSA public key used for authenticating webhooks from Guidewire.	xceNdxxxxxx8upa7bk5w
Success Activity Pattern	true	The activity pattern to log success messages.	oss_success_notification	oss_success_notification
Failure Activity Pattern	true	The activity pattern to log failure messages.	oss_failure_notification	oss_failure_notification
Document Order	true	The order in which documents will be processed during integration. You can choose from "Date Modified Ascending," "Date Modified Descending," "Name Ascending," or "Name Descending."	Date Modified Ascending	Date Modified Ascending
Enable Signing Order	false	This option determines whether a signing order is enforced during the signing process.	true	true
Signer Authentication Method	false	Defines the method of authentication for signers. Options include “NONE”, “SMS” and “ID_VERIFICATION”. The phone number will be collected from the claim contact's primary phone number.	NONE	NONE
IDV Workflow	false	If signer authentication method is “ID_VERIFICATION”, provide the IDV workflow in JSON format.	{"id":"00000000-0000-0002-0001-200000000055","type":"DV","tenant":"OSS","desc":""}
Download Document Type	true	Specifies the document type to be downloaded after the signing process.	onespan_esignature	onespan_esignature
Download Evidence Summary	true	Determines whether to include the evidence summary in the zip file containing the signed documents.	true	true
Download Flattened Document	true	Determines whether to download the flattened format of signed documents in the zip file.	false	false
Download Signed Documents	true	Determines whether to include the signed documents in the zip file.	true	true

For Further Assistance

You may wish to make changes to any of the integration content provided in this solution. For example, you might want to extend the solution, or to adapt it to suit your unique needs. If during your implementation you require assistance with any of these changes, please contact your Guidewire or partner Implementation Manager to discuss options for consulting assistance.

For assistance with additional features such as branding, email templates, and account-level options, please reach out to our Support Team as part of your request.

In addition, please provide the Admin Notification and Recipe Error Notification Emails, along with a list of names and emails for customer collaborators to be invited to your iPaaS workspace. Once the support team enables the required features in your account and sets up your workspace, please follow the instructions provided for the next steps.