Summary
This document outlines the integration for transferring iPaaS Location data to Zuper Locations. The synchronization can be executed through manual syncs or automated via outbound webhooks for create and update events.
Required Fields
LocationID: The unique identifier for the location, which must be in UUID format.
Name: The display name of the location.
Type: A static value defining the location type (e.g.,
SITE).
Recommended Fields
Description: Additional details about the location, such as operating hours or special instructions.
Field Constraints
LocationID: Required, unique UUID (Universally Unique Identifier) format.
Name: Required, unique string (max 100 characters).
Description: Optional, string (max 500 characters).
Integration Configuration
Status: Enabled
Trigger Events: This integration runs on Create and Update events for locations in iPaaS.
System Caveats
iPaaS Caveats
Missing Data: Records missing a unique
LocationIDor aNamewill not be transferred.Duplicate Records: If the same
LocationIDappears multiple times, deduplication logic should be applied to process only the most recent record.
Zuper Caveats
UUID Requirement: Zuper requires all
LocationIDvalues to be in a valid UUID format (e.g.,f1e127f0-dd15-11ed-9b2c-c3a22815cf76). Records with invalid formats will be rejected.Field Constraints: Zuper enforces field limits, such as character length for
Name. Data that violates these rules will be rejected.Orphan Records: Zuper may not automatically remove locations when they are deleted in iPaaS. A separate process or explicit delete API call is required to keep the systems synchronized.
Prerequisites
Authentication
Zuper: Requires an API key generated in the Zuper admin console with Location read/write permissions.
iPaaS: Requires an access token for the Location API endpoint with create and update permissions.
Manual Sync Process
When manually transferring a location, you must accurately input the iPaaS Location ID (e.g., 12452) into the designated field on the manual sync page.
Integration Flow
A Location record is created or updated in iPaaS.
An outbound webhook or a manual sync triggers the integration.
Validation checks are performed, ensuring the
LocationIDis a valid UUID and all required fields are populated.iPaaS fields are mapped to the corresponding Zuper fields.
If validation passes, the location record is created or updated in Zuper. Otherwise, the error is logged for review.
Field Mappings
Mapping Type | Source Field (iPaaS) | Destination Field (Zuper) | Description |
Field | Name | Name | Required. The unique name of the location. |
Field | Description | Description | Recommended: A description of the location. |
Static | SITE | Type | Required. A static value defining the type of the location. |
Error Handling
Invalid or Missing UUID
Description: The LocationID in the iPaaS record is not in the valid UUID format required by Zuper.
Resolution: Log the error, skip the record, and notify an administrator to correct the source data.
Invalid Field Format
Description: The
Nameexceeds the maximum allowed length or contains unsupported characters.Resolution: Apply data truncation and cleanup rules in the iPaaS mapping before sending the record to Zuper.
API Authentication Failure
Description: The API key or token used for the Zuper API call is expired or invalid.
Resolution: Refresh the token or reconfigure the API credentials in the iPaaS connector settings.
Missing Required Field
Description: The
Namefield is null or empty.Resolution: Ensure the source data in iPaaS is complete. The integration should block records missing required fields.
Testing & Validation
Test Scenarios
A valid location is transferred.
Expected Outcome: The location is created successfully in Zuper.
A location with an invalid UUID is transferred.
Expected Outcome: Zuper rejects the record, and the error is logged in iPaaS.
A location missing a required field (e.g.,
Name) is transferred.Expected Outcome: The sync is blocked, the error is logged, and the record is not created in Zuper.
A location with a Name exceeding the character limit is transferred.
Expected Outcome: The record is either rejected by Zuper or the data is truncated by the integration before being sent.
Validation Checklist
Confirm every location has a valid UUID before transfer.
Ensure required fields (LocationID, Name) are populated.
Verify that duplicate LocationID values from iPaaS are not sent.
Check that the
Namelength does not exceed 100 characters.Test the error handling and retry mechanism for failed transfers.