.png)
Iress Xplan Integration Guide
Iress Xplan integrates with enterprise systems primarily through its Open Integration Platform and provisioned REST APIs, with selected notification or callback options subject to tenant configuration.
Iress Xplan integration options at a glance
Iress Xplan’s primary integration route is its Open Integration Platform and provisioned REST APIs. Martini can authenticate to approved Xplan environments, retrieve or update resources such as Clients, Contacts, Groups, Accounts, Portfolios, and Transactions, and transform JSON data for downstream systems. Xplan notification or callback support may be available for selected events, but coverage must be confirmed for each tenant and object. Where event delivery is unavailable, scheduled Martini workflows can poll supported resources using pagination and incremental filters. OAuth 2.0 is the expected authorization model, while bulk APIs, general-purpose attachment APIs, GraphQL, SOAP, and direct database access should not be assumed.
| Integration point | Supported by Iress Xplan? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Retrieve or update provisioned Xplan resources such as Clients, Contacts, Groups, Accounts, Portfolios, and Transactions. Exact operations depend on enabled API products and permissions. | Martini can consume authenticated REST endpoints, handle JSON responses, paginate through results, transform fields, and expose downstream APIs or workflows. |
| Authentication | Yes | Xplan Open Integration Platform access requires provisioned authentication and authorization. OAuth 2.0 is the expected model, with grants, scopes, and tenant permissions confirmed during provisioning. | Martini stores credentials, tokens, URLs, and environment-specific settings in secure configuration and uses them when invoking Xplan APIs. |
| Webhooks / outbound callbacks | Limited | Selected Xplan environments may provide notifications, callbacks, or event subscriptions for particular objects and events. Universal change coverage is not confirmed. | Martini can expose an authenticated endpoint, validate inbound requests, deduplicate notifications, retrieve current Xplan state, and start a workflow. |
| Scheduled synchronization | Yes | Scheduled polling is the fallback when required event notifications are unavailable. It can support incremental reads using available timestamps, identifiers, versions, or other source filters. | Martini provides scheduler-triggered workflows with checkpoints, pagination, replay windows, throttling, reconciliation, and retry handling. |
| Bulk / async / batch APIs | Not confirmed | A general-purpose Xplan bulk or asynchronous API was not verified. Larger loads may require pagination, scheduled incremental extraction, or an Iress-approved export facility. | Martini can orchestrate controlled batches and checkpoint progress, but the availability and semantics of any Xplan bulk facility must be confirmed with Iress. |
| File / attachment APIs | Not confirmed | Xplan manages advice and client documentation, but a generally available document or attachment API was not verified. | Martini can process files or binary responses if the tenant exposes suitable resources, subject to permissions, formats, size limits, and delivery behavior. |
| GraphQL APIs | Not confirmed | No official Xplan GraphQL API was verified. Xplan REST resources should not be assumed to have GraphQL equivalents. | Martini can consume GraphQL generally, but an Xplan GraphQL integration should be designed only if Iress confirms an endpoint. |
| SOAP APIs | Legacy | Older or product-specific Xplan web services may exist in some environments, but a current recommended SOAP interface was not verified. | Martini can consume SOAP services when a supported Xplan endpoint and contract are supplied, but REST should remain the default planning assumption. |
How Iress Xplan exposes data and business events
Iress Xplan REST APIs
Xplan’s Open Integration Platform and published APIs are the primary standards-based route for current integrations. Access, resource availability, operations, and field definitions depend on the customer’s provisioned environment, licensed modules, and permissions.
Martini implementation pattern
Martini implementation pattern: Martini authenticates to the approved Xplan environment, invokes the required REST resources, handles pagination and JSON responses, maps Xplan objects to canonical or target models, and records checkpoints and correlation details. Workflows can run on a schedule or behind a Martini API.
Implementation sequence
Iress Xplan notifications and callbacks
Some Xplan environments may provide outbound notifications, callbacks, or event subscriptions for selected objects and events. General-purpose webhook coverage and delivery guarantees are not confirmed and must be checked with Iress.
Martini implementation pattern
Martini implementation pattern: Martini exposes an authenticated endpoint for the confirmed notification mechanism, validates and deduplicates the inbound message, retrieves the current Xplan object state, and starts downstream processing. If notifications are unavailable, a scheduled polling workflow provides the fallback.
Implementation sequence
Common Iress Xplan integration patterns
Pattern 1: Synchronize clients and relationships to a CRM
When to use this pattern
Use this pattern when advisers need Xplan client and relationship information available in a CRM. A scheduled workflow is appropriate when event coverage is unavailable or has not been confirmed for the required objects.
Integration direction
Example Mapping
| Iress Xplan Field | Canonical Field | Target Field |
|---|---|---|
| clientId | customer.externalId | Account.External_Id__c |
| displayName | customer.name | Account.Name |
| contactDetails | customer.contactMethods | Contact.Email / Contact.Phone |
| groupMembership | customer.relationships | Account household relationships |
Martini implementation pattern
Martini reads paginated Clients, Contacts, and Groups using an incremental filter where supported, matches records by stable source identifiers, preserves household relationships, and applies validation for required contact data. Create-or-update operations are made idempotent; transient failures are retried and rejected records are routed for review.
Martini capabilities used
- workflows
- API consumption
- scheduling
- data mapping
- business rules
- error handling
Pattern 2: Distribute portfolio and transaction data
When to use this pattern
Use this pattern to publish investment information from Xplan to reporting, analytics, or internal financial-planning services without granting those systems direct access to Xplan.
Integration direction
Example Mapping
| Iress Xplan Field | Canonical Field | Target Field |
|---|---|---|
| portfolioId | investmentPortfolio.id | PortfolioId |
| accountId | investmentAccount.id | AccountId |
| transactionDate | activity.date | TransactionDate |
| transactionAmount | activity.amount | Amount |
Martini implementation pattern
A scheduled Martini workflow retrieves Portfolios, Accounts, and Transactions, follows the tenant’s pagination model, transforms Xplan structures into a canonical investment model, and filters by reporting period. It checkpoints progress, applies throttling and retry rules, and reconciles source and target counts and totals.
Martini capabilities used
- workflows
- API consumption
- scheduling
- data mapping
- transformations
- reconciliation
- error handling
Pattern 3: Process advice documents when an attachment API is available
When to use this pattern
Use this pattern only after Iress confirms that the customer’s Xplan environment exposes the required document or attachment resources, permissions, file formats, and delivery behavior.
Integration direction
Example Mapping
| Iress Xplan Field | Canonical Field | Target Field |
|---|---|---|
| documentId | document.externalId | SharePoint item sourceId |
| documentName | document.name | FileLeafRef |
| documentType | document.category | ContentType |
| clientId | document.clientExternalId | ClientReference |
Martini implementation pattern
Martini retrieves approved document metadata or content, applies naming, retention, and access rules, and sends it to SharePoint or another approved repository. The workflow records source identifiers and file status, avoids duplicate uploads, and sends unsupported file or permission errors to an exception path.
Martini capabilities used
- workflows
- API consumption
- file handling
- data mapping
- business rules
- error handling
Pattern 4: Process selected client or account notifications
When to use this pattern
Use this pattern when the Xplan tenant supports outbound notifications for the required object and event. It provides lower-latency processing than polling while retaining a REST read-after-notification step for authoritative state.
Integration direction
Example Mapping
| Iress Xplan Field | Canonical Field | Target Field |
|---|---|---|
| eventId | event.id | integrationEventId |
| objectId | sourceObject.id | xplanObjectId |
| objectType | sourceObject.type | sourceType |
| updatedAt | sourceObject.updatedAt | modifiedon |
Martini implementation pattern
Martini receives the authenticated notification, validates its source and event identifier, suppresses duplicate delivery, retrieves the current Xplan object, and maps the resulting state to Dynamics 365. Failures are classified by type, transient errors are retried, and permanently rejected events are retained for replay or reconciliation.
Martini capabilities used
- API exposure
- workflows
- event handling
- API consumption
- data mapping
- idempotency
- error handling
Applications commonly integrated with Iress Xplan
Xplan data can be routed to adjacent enterprise applications when the required API resources, permissions, and data ownership rules are confirmed. The following are practical architecture patterns rather than verified native Xplan pairings.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Xplan client, contact, and relationship data with adviser CRM records and activity management. | Iress Xplan → Martini → Salesforce | A scheduled Martini workflow retrieves changed Clients, Contacts, and Groups, matches them by stable external identifiers, maps relationship fields, and routes validation failures for review. Selected Salesforce updates can be sent back to Xplan where the enabled API resources permit it. |
| Microsoft Dynamics 365 | Align client, household, opportunity, and adviser workflow information across Xplan and the CRM. | Iress Xplan → Martini → Microsoft Dynamics 365 | Martini orchestrates incremental Xplan reads, applies ownership and field-precedence rules, transforms Groups and Contacts into the Dynamics model, and performs create-or-update operations with retry and reconciliation handling. |
| Microsoft SharePoint | Distribute approved advice or client documents to an enterprise document repository when Xplan document resources are available. | Iress Xplan → Martini → Microsoft SharePoint | If the Xplan tenant exposes the required document or attachment resources, Martini retrieves permitted content or metadata, applies document naming and access rules, and sends it to SharePoint while recording source identifiers and processing status. |
| DocuSign | Coordinate advice-document signature processes and exchange signature status with planning operations. | Iress Xplan → Martini → DocuSign | Martini can transform approved document metadata, initiate an authorized DocuSign process, receive status updates through supported endpoints, and update Xplan only where the enabled resources support the required workflow. |
| Power BI | Provide normalized portfolio, account, transaction, and adviser-performance data for reporting. | Iress Xplan → Martini → Power BI | A scheduled workflow extracts paginated Xplan data, converts it to a canonical reporting model, applies period and eligibility rules, and publishes it to an approved Power BI data endpoint or reporting store with checkpointing. |
| NetSuite | Exchange approved client, billing, or financial-administration data where an advisory business also uses NetSuite. | Iress Xplan → Martini → NetSuite | Martini maps selected Xplan client or account information to NetSuite fields, enforces data ownership rules, and uses idempotent create-or-update operations. Financial fields should be transferred only after API permissions and business definitions are confirmed. |
| ServiceNow | Create operational tickets for integration failures, data exceptions, and client-service remediation work. | Iress Xplan → Martini → ServiceNow | Martini classifies Xplan authentication, permission, validation, throttling, and availability errors, then creates or updates ServiceNow incidents with source identifiers, correlation details, and retry status. |
| Jira | Track data-quality exceptions, remediation tasks, and integration incidents for delivery and operations teams. | Iress Xplan → Martini → Jira | A Martini error or reconciliation workflow creates Jira issues for actionable exceptions, includes the affected Xplan object and workflow run details, and suppresses duplicate issues using a deterministic correlation key. |
How to build a Iress Xplan integration in Martini
Objective
Establish access to the provisioned Xplan Open Integration Platform environment and confirm the API resources, tenant context, permissions, and OAuth 2.0 configuration required for the integration.
Instructions in Martini
- Obtain the approved Xplan API specification, base URL, environment, and enabled resources
- Configure OAuth 2.0 credentials, scopes, tokens, and tenant settings in Martini secure configuration
- Test authentication and distinguish authorization failures from endpoint or validation errors
Objective
Select the execution model based on Xplan capabilities confirmed for the tenant and the required latency of the business process.
Instructions in Martini
- Use a Martini scheduler for polling and incremental synchronization
- Use an authenticated Martini API endpoint if Xplan notifications or callbacks are confirmed
- Define the fallback polling approach for objects without event coverage
Objective
Read the required Xplan objects while respecting the API’s pagination, filtering, rate, and permission behavior.
Instructions in Martini
- Invoke the confirmed REST resources for Clients, Contacts, Groups, Accounts, Portfolios, or Transactions
- Implement the tenant-specific pagination model and incremental filters
- Persist cursors, timestamps, source identifiers, or replay windows between runs
Objective
Coordinate retrieval, enrichment, validation, routing, target writes, and state management in a maintainable Martini workflow.
Instructions in Martini
- Separate extraction, transformation, business rules, delivery, and checkpoint activities
- Preserve relationships between Xplan objects instead of flattening household or portfolio structures
- Route unsupported resources and incomplete payloads to explicit exception handling
Objective
Convert Xplan JSON structures into a canonical or target-specific model while retaining source identifiers and relevant relationships.
Instructions in Martini
- Map source fields to canonical and target fields
- Normalize dates, amounts, statuses, identifiers, and relationship roles
- Apply validation and data-quality rules before target writes
Objective
Enforce ownership, eligibility, privacy, and duplicate-prevention policies before data is distributed or updated.
Instructions in Martini
- Define source-of-truth and field-precedence rules for bidirectional flows
- Minimize personal, account, transaction, and document data transferred to each target
- Use deterministic matching and idempotency keys for create-or-update behavior
Common Iress Xplan data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Clients | People or organizations receiving financial-planning services. | Salesforce, Microsoft Dynamics 365, reporting stores, customer-service applications | Martini retrieves permitted client data, validates required fields, matches stable identifiers, preserves tenant context, and maps it to the target model. |
| Contacts | Contact and relationship information associated with clients and other parties. | Salesforce, Microsoft Dynamics 365, customer-service applications | Martini transforms names, addresses, communication preferences, and relationship references while routing incomplete or ambiguous data to exception handling. |
| Groups | Household, family, business, or other structures that associate clients. | CRMs, reporting platforms, planning services | Martini preserves group membership and relationship structure rather than flattening it, applying target-specific ownership and matching rules. |
| Accounts | Financial accounts or account-level holdings connected to a client or portfolio. | Reporting stores, analytics platforms, financial-administration applications | Martini retrieves accounts incrementally, maps identifiers and classifications to a canonical investment model, and applies eligibility and reconciliation rules. |
| Portfolios | Investment or asset groupings used for portfolio management and reporting. | Power BI, reporting data stores, internal financial-planning services | Martini orchestrates scheduled extraction, pagination, period filtering, transformation, and delivery while avoiding repeated retrieval of unchanged portfolios. |
| Transactions | Financial activity associated with accounts or portfolios. | Analytics platforms, reporting stores, financial-administration applications | Martini retrieves transactions using supported filters, preserves source identifiers and dates, applies reporting-period rules, and reconciles counts and totals. |
Authentication and security considerations
Provisioned access and OAuth 2.0
Xplan API access is controlled by the Open Integration Platform and an appropriately provisioned environment. OAuth 2.0 is the expected authorization model, but grants, token endpoints, scopes, refresh behavior, and tenant permissions must be confirmed with Iress.
Protect sensitive planning data
- Store credentials, tokens, and environment-specific URLs in Martini secure configuration.
- Apply least-privilege permissions for Clients, Contacts, Groups, Accounts, Portfolios, Transactions, and any document resources.
- Minimize personal, financial, transaction, and advice-document data transferred to each target.
- Use transport encryption, target-system access controls, retention policies, and audit requirements appropriate to the data.
Operational considerations for Iress Xplan integrations
Throughput and synchronization
- Confirm Xplan rate, concurrency, and volume limits with Iress and implement exponential backoff for throttling.
- Confirm pagination semantics rather than assuming page numbers, offsets, cursors, or continuation links.
- Prefer updated-time, version, or change-token filters where available and retain replay windows for delayed updates.
- Use stable object identifiers and event IDs, or object/version combinations, to make writes idempotent.
Reliability and change management
- Retry transient failures but do not blindly retry authorization or validation errors.
- Monitor schema changes, status values, product types, account classifications, and relationship roles.
- Reconcile source and target counts, timestamps, and key totals after significant synchronization runs.
- Test resource permissions, multi-page extraction, concurrent updates, archived clients, and partial failures in a non-production environment where available.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration beyond point-to-point scripts
Martini separates API consumption, workflow orchestration, mapping, business rules, target delivery, and operational state. This makes Xplan integrations easier to adapt when resource permissions, schemas, or target requirements change.
Reusable and observable integration logic
- Build reusable workflows and APIs for synchronization, façade services, validation, and reconciliation.
- Support scheduled polling and confirmed event-driven entry points without duplicating integration logic.
- Centralize secure configuration, transformations, retries, error routing, and correlation details.
- Monitor workflow outcomes and provide controlled replay paths for failed or duplicate-prone messages.
Frequently asked questions
Iress Xplan is primarily integrated through its Open Integration Platform and provisioned REST APIs. Martini can retrieve or update enabled Xplan resources, transform JSON payloads, and deliver data to enterprise applications. Selected tenants may also support notifications or callbacks, while scheduled incremental synchronization is the fallback when event coverage is unavailable.
Yes. Martini can integrate with Iress Xplan by consuming its supported REST APIs and, where the tenant provides them, receiving supported notifications or callbacks. The exact resources, permissions, authentication details, and event coverage must be confirmed with Iress.
No. A dedicated Iress Xplan connector is not required. Martini can use Xplan’s confirmed native REST APIs, authentication mechanisms, and supported notification endpoints to orchestrate workflows, expose APIs, transform data, and manage synchronization.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Iress Xplan. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Iress, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
REST through the Xplan Open Integration Platform should be treated as the primary method for current integrations. OAuth 2.0 is the expected authorization model, subject to confirmation of grants and scopes. GraphQL was not verified, and SOAP should be treated as unconfirmed or environment-specific rather than a default approach.
Selected Xplan environments may support notifications, callbacks, or event subscriptions, but universal webhook coverage was not verified. Confirm the required objects, events, payload completeness, authentication, signatures, retry behavior, and delivery guarantees with Iress. Martini can receive confirmed notifications and start workflows; otherwise it can poll REST resources on a schedule.
Martini can run scheduled or event-triggered workflows that retrieve paginated Xplan data, apply incremental filters where available, preserve source identifiers and relationships, and map objects into canonical or target-specific models. Checkpoints, replay windows, validation, business rules, and reconciliation help control duplicate or missed updates.
Martini can classify authentication, permission, validation, throttling, and transient availability errors, retry appropriate failures, and route permanent exceptions for review. Stable Xplan identifiers and event or object versions support idempotency. Martini can also expose a controlled API façade for downstream applications, without requiring those applications to access Xplan directly.
Related Martini documentation
Workflows
Operations
Integrate Iress Xplan with Martini
Use Martini to connect provisioned Iress Xplan APIs and supported notifications with enterprise applications through secure, maintainable workflows.