Search
  1. Home
  2. Documentation
  3. OneSpan Sign
  4. Guides
  5. Workflow Integrations Guides
  6. OneSpan Sign Accelerator for PolicyCenter

OneSpan Sign Accelerator for PolicyCenter

Last modified: 2024-11-01

Introducing OneSpan Sign Accelerator for PolicyCenter

The OneSpan Sign Accelerator for PolicyCenter integration provides a seamless integration between Guidewire PolicyCenter and OneSpan Sign, allowing PolicyCenter users to trigger electronic signature workflows from within PolicyCenter. 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 PolicyCenter 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 PolicyCenter.

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 PolicyCenter 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 PolicyCenter Cloud
  • Guidewire App Events Webhooks
  • Workato - OneSpan iPaaS solution partner

General Workflow

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

Webhook Event Triggered Integration

  • One of the following PolicyCenter custom events triggers the integration.
    • SendAccountDocToOss

    • SendJobDocToOss

    • SendPolicyDocToOss

  • This in turn triggers an iPaaS recipe that collects signer information from the Account/Policy 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 into the account, job or policy document section in PolicyCenter.

  • A success message is sent in an activity, and the OneSpan Sign package is then archived.

Using OneSpan Sign Accelerator for PolicyCenter

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

  • The creation of a OneSpan Sign Package using Guidewire PolicyCenter

  • The archiving of the package, once all signing is complete

Creating a OneSpan Sign Package from an Account

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 account contacts roles, the user moves to the Account 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 SendAccountDocToOss custom event.

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

The triggered SendAccountDocToOss 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 account, logging the result.

Creating a OneSpan Sign Package from a Job or Policy

The OneSpan Sign package creation process begins by automatically selecting the primary named insured and any additional named insured persons as e-signature recipients.

After identifying the named insureds, the user navigates to the Policy Documents or Job 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 SendPolicyDocToOss or SendJobDocToOss custom event, depending on the context.

Similar to the account flow, if the selected document type is unsupported, the user will immediately receive a failure message.

The triggered SendAccountDocToOss 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
  • Signer Information Collection
    • First Name (required)
    • Last Name (required)
    • Email Address (required)
    • Phone Number
    • Authentication Method (e.g., SMS, ID Verification)

  • 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 job or policy, logging the outcome.

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 Account, Job or Policy document section within PolicyCenter.

A success message is sent as an activity in PolicyCenter, 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 PolicyCenter using OneSpan iPaaS solution partner as the business logic layer. The key sections within the technical design include:

  • PolicyCenter Cloud API: The APIs used to interact with PolicyCenter , allowing retrieval of account, job, and policy documents, signer information, and posting activities related to e-signature processes.
  • OAuth2 Permissions: Describes the required OAuth2 permissions for accessing PolicyCenter 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.

PolicyCenter Cloud APIs

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

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

To retrieve Account Contacts

GET /account/v1/accounts/*/contacts: This endpoint retrieves contact details for the specified account, which are used to identify the e-signature recipients (signers) in OneSpan Sign.

To retrieve Account Documents

GET /account/v1/accounts/*/documents: This API call is used to fetch the content of documents associated with an account, allowing these documents to be sent to OneSpan Sign.

To upload Documents to an Account

POST /account/v1/accounts/*/documents: This API call is used to upload signed documents back into the account’s document section after the signing process in OneSpan Sign is completed.

To Post Activities to an Account

POST /account/v1/accounts/*/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, into the account's activity feed.

To Retrieve Job Contacts

GET /job/v1/jobs/*/contacts: This API is used to fetch the contact details for a job, including named insureds, which are used as e-signature recipients.

To Retrieve Additional Named Insureds

GET /policy/v1/jobs/*/additional-named-insureds: This API is used to retrieve additional named insureds from a job, adding them to the list of signers for e-signature purposes.

To Retrieve Job Documents

GET /job/v1/jobs/*/documents: This API is used to fetch documents associated with a job, allowing them to be included in the OneSpan Sign package for signature.

To Upload Documents to a Job

POST /job/v1/jobs/*/documents: This API is used to upload signed documents back into the job’s document section after the e-signing process is completed.

To Post Activities to a Job

POST /job/v1/jobs/*/activities: This API is used to log success or failure messages related to the e-signature package creation or document signing process into the job’s activity feed.

To Retrieve Policy Contacts

GET /policy/v1/policies/*/contacts: This API is used to retrieve contact details for the policy, including named insureds, which are then used to populate signer information in OneSpan Sign.

To Retrieve Additional Named Insureds from Policy

GET /policy/v1/policies/*/additional-named-insureds: This API is used to retrieve additional named insureds related to a policy, to act as recipients in the e-signature workflow.

To Retrieve Policy Documents

GET /policy/v1/policies/*/documents: This API is used to fetches the documents tied to a policy to send to OneSpan Sign for e-signature.

To Upload Documents to Policy

POST /policy/v1/policies/*/documents: This API is used to pload signed documents back into the policy’s document section after completion of the OneSpan Sign process.

To Post Activities to Policy

POST /policy/v1/policies/*/activities: This API is used to logs activities, such as the success or failure of the e-signature package creation, into the policy’s activity feed.

To Retrieve Document Content

GET /common/v1/documents/*/content: This API is used to fetch the content of specific documents, enabling iPaaS to upload them into OneSpan Sign for signing.

OAuth2 Permissions

To securely interact with the PolicyCenter 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 account/job/policy contact details

  • Access and manage documents

  • Log activities for status updates

  • Upload signed documents back to the PolicyCenter

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 an account as input:

static public function SendAccountDocToOss(docs : Document[], account : Account) {
    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 bundleAccount = bundle.add(account)
      bundleAccount.OssDocumentList_Acc = String.join(";", publicIDs)
      bundleAccount.addEvent('SendAccountDocToOss')
    })

      _handleSuccess('Accelerator.OneSpan.SendAccountSuccessMsg', account.AccountNumber, #SendToOss(Document[],Account))
    } catch (e : Exception) {
      _handleFailure('Accelerator.OneSpan.SendAccountFailureMsg', account.AccountNumber, e, #SendToOss(Document[],Account))
    }
  }

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 SendAccountDocToOss() 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 SendAccountDocToOss 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 PolicyCenter system, such as after a policyperiod 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 PolicyCenter 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 PolicyCenter 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 PolicyCenter 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., PolicyCenter 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 PolicyCenter Cloud is properly configured, follow these steps:

  1. 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.

  2. 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.

  3. Clone and Setup the PolicyCenter Cloud Project:

    • Clone and check out a new branch for your Guidewire PolicyCenter Cloud project.
    • Deploy the accelerator files to your local deployment environment. Refer to the following section for a detailed file manifest.

  4. 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.

  5. 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 SendAccountDocToOss, SendJobDocToOss, and SendPolicyDocToOss events within PolicyCenter and communicate with iPaaS platform.
    • 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" } ] }

  6. Add Custom Activity Patterns:

    • Within your implementation package locate the file named Custom Activity Pattern.xml. This file contains two custom activity patterns; OneSpan Sign Success Activity and OneSpan Sign Failure Activity.

    • Import this file into your Guidewire Policy Center environment, under PolicyCenter Admin Data.

    • 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 account, job, or policy.

Data Model Extensions

Existing Entities

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

  • Job.OneSpan.etx: A custom event has been added

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

Custom Entities

  • OneSpanSender_Acc.eti: A custom Account Contact Role that represents the Sender

  • OneSpanSigner1_Acc.eti: A custom Account Contact Role that represents the Signer1

  • OneSpanSigner2_Acc.eti: A custom Account Contact Role that represents the Signer2

  • OneSpanSigner3_Acc.eti: A custom Account Contact Role that represents the Signer3

  • OneSpanSigner4_Acc.eti: A custom Account Contact Role that represents the Signer4

  • OneSpanSigner5_Acc.eti: A custom Account Contact Role that represents the Signer5

Existing Typelists

  • DocumentType.OneSpan.ttx: Introduced 1 custom Document type

User Interface Modifications

Existing PCF Files:

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

  • Policy_DocumentsScreen.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 PolicyCenter Cloud:

config

\displaynames

  • OneSpanSender_Acc.en
  • OneSpanSigner1_Acc.en
  • OneSpanSigner2_Acc.en
  • OneSpanSigner3_Acc.en
  • OneSpanSigner4_Acc.en
  • OneSpanSigner5_Acc.en

\extensions

  • \entity
    • Account.OneSpan.etx
    • Job.OneSpan.etx
    • OneSpanSender_Acc.eti
    • OneSpanSigner1_Acc.eti
    • OneSpanSigner2_Acc.eti
    • OneSpanSigner3_Acc.eti
    • OneSpanSigner4_Acc.eti
    • OneSpanSigner5_Acc.eti
    • PolicyPeriod.OneSpan.etx

  • \typelist

    • DocumentType.OneSpan.ttx

  • \integration

    • \mappings\ext

      • \account\v1

        • account_ext-1.0.mapping.json

      • \policyperiod\v1

        • policyperiod_ext-1.0.mapping.json

    • \roles

      • sasolnpart_onespan-client.role.yaml

    • \schemas\ext

      • \account\v1

        • account_ext-1.0.schema.json

      • \policyperiod\v1

        • policyperiod_ext-1.0.schema.json

  • \locale

    • display.properties

  • \logging

    • log4j2.xml (line 72-79, line 383-388)

  • \web\pcf\policy

    • DocumentsScreen.pcf (line 88-93)

    • Policy_DocumentsScreen.pcf (line 96-101)

gsrc

  • \acc\oneSpan

    • OneSpanUIHelper.gs

  • \gw\plugin\contact\impl

    • ContactConfigPlugin.gs (line 38-43, make sure to add a comma at line 36)

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 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

There are two additional features specifically available when creating packages from Policy and Job:

Name

Required

Description

Example Value

Default Value

Include Additional Named Insureds

true

Whether to include additional named insureds as signers in the package.

true

true

Use Relationship as Role Name

true

Whether the relationship of the additional named insureds should be used as their role name in the package.

false

false

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.

Was this information helpful?
X