The Peoplevox re-authentication response script

This script and associated functionality are coming soon - please check our release notes for upcoming releases.

Introduction

Typically, SOAP authentication via tokens works by authenticating once and sending a valid token in response - this token is included in all subsequent requests until it expires. When the token expires, a 401 (authentication failed) response is returned, and we re-authenticate with the next request.

However, Peoplevox doesn't send a 401 response when a token expires - a 200 (success) code is returned and the authentication outcome is included in the response body. So for optimal performance (i.e. to avoid having to authenticate every request), we need a way to trigger re-authentication based on content in the response body. To achieve this, we use a response script.

Using this script is recommended but not mandatory. Without this script, Peoplevox process flows will run normally, though not optimally (since every request is authenticated).

About the re-authentication response script

Response scripts are applied to process flow connector shapes to control whether the connector shape/process flow fails or continues, based on information returned from the connection request.

The script runs every time a connection is attempted and receives the response code, headers, and body from the request. Utilising response_code actions, the script returns a value determining whether the connector shape/flow run continues or stops.

For more information, please see Using connector shape response scripts.

The script below has been developed for Peoplevox.

<?php

/**
 * Invalid PVX auth response comes with HTTP 200 code and this body:
 * <?xml version="1.0" encoding="utf-8"?>
 *   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 *  <soap:Body>
 *       <AuthenticateResponse xmlns="http://www.peoplevox.net/">
 *           <AuthenticateResult>
 *               <ResponseId>-1</ResponseId>
 *               <TotalCount>0</TotalCount>
 *               <Detail>System : Security:Invalid Username or Password</Detail>
 *               <Statuses />
 *               <ImportingQueueId>0</ImportingQueueId>
 *               <SalesOrdersToDespatchIds />
 *               <ErrorCode>72e420d4-6892-4333-83b5-e7214fbf561b</ErrorCode>
 *           </AuthenticateResult>
 *       </AuthenticateResponse>
 *   </soap:Body>
 * </soap:Envelope> 
 *
 * If this content is present in the response, we'll need to force reauthentication by returning the correct script response code. See https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape/using-connector-shape-response-scripts#response-code for more information
 */

function handle($data)
{
    if (str_contains($data['payload'], 'Invalid Username or Password')) {
        // request had invalid auth, need to force reauth
        $data['response_code'] = 4; // reauth response code
        $data['message'] = 'Request to PVX was unauthenticated, forcing reauthentication.';
    } else {
        // nothing needed, response will be handled as normal
    }

    return $data;
}

This checks the <AuthenticateResponse><AuthenticateResult> section of the SOAP response body to determine success or failure. If authentication is found to have failed, the connector step will retry the request and re-authenticate.

Implementing the response script

If you are receiving or sending data from/to Peoplevox in process flows, we recommend following the steps below to implement the Peoplevox Re-Authentication Response Script:

Step 1 Install the Peoplevox Re-Authentication Response Script from the Patchworks marketplace.

Step 2 Having installed the script, you should apply it to any connector steps in your process flows(s) where Peoplevox is used. This is just a case of accessing connector shape settings and selecting the response script that you installed - for example:

Step 3 Raise a ticket with Patchworks support for the Enhanced Peoplevox Re-Authentication feature to be switched on for your organisation.

For general information about response scripts, please see: Using connector shape response scripts.

What if I don't use this script?

Without this script, Peoplevox process flows will run normally, though not optimally (since every request is authenticated).