Integration Guide
The TSANet Integration Guide is used by developers to build custom integrations and system connectors. TSANet has Connectors for Salesforce, Microsoft Dynamics and Service Now.
Integration Guide
Contributors and References
Contributors
Paul Esch, TSANet, https://www.linkedin.com/in/pauleesch/
Sean Dulac, Appko, https://www.linkedin.com/in/seandulac/
References
The following documents explain the details behind the integration framework Technology and Methods.
Enterprise Integration Patterns: Designing, Building, and deploying messaging solutions.
By Grregor Hohpe and Bobby Woolf - https://www.amazon.com/o/asin/0321200683/ref=nosim/enterpriseint-20
Apache Camel: https://developers.redhat.com/products/redhat-build-of-apache-camel/overview
Apache ActiveMQ: https://activemq.apache.org/components/artemis/
Executive Summary
TSANet is a member-driven, not-for-profit, global collaborative alliance of 900+ technology companies working together to improve the support experiences of their shared customers. Member companies use TSANet to enable collaboration with their Technology and Service Partners. The TSANet Partner Framework is flexible and supports several relationship models.
Members use the TSANet Connect system to connect and collaborate with other members. The collaboration process is described in the image below:
Why Use TSANet Connect
TSANet Members can integrate their system into TSANet Connect to improve the user experience and process compliance. TSANet vs Alternative solutions are compared below:
Cost
Included with Membership
Usage model (example Per user)
High cost (~100k) per connection
Scalability & flexibility
Single Integration – Connect to One,
Connect to Anyone. Supports all Partner Models: Certified, Solution, OEM and Service Provider
Multiple extranet access is an operational challenge. Drives bad security practices. Customer model often used
Duplicate costs per integration. Every new connection requires each company to budget & prioritize. Each Partner Model requires new integration
Security
ISO70001, ISO27701, Microsoft SSPA
No SSO, MFA, Shared accounts, Data protection
Depends on the Members IT Organization
User Experience
Consistent & Integrated experience
Swivel chair process – Not integrated
Missing features and Fragmentation (B2B with everyone not possible)
Ongoing Support
Support and continuous improvements
Based on multiple companies' extranet
Dependent on the IT prioritization and decisions of multiple companies. Slow to change or improve
System Overview
The TSANet Connect Platform includes a Web App and Integration Framework based on Apache Camel on Spring Boot, ActiveMQ and PostgreSQL. The Integration Framework provides a complete set of REST APIs for creating integrations. This document will describe the TSANet Connect REST APIs and how they were used to develop the Salesforce App. The Salesforce App and other System Apps can be found at: https://github.com/tsanetgit
TSANet Connect – Integration Framework
The TSANet Connect Integration Framework is based on Apache Camel on Spring Boot with Active MQ message broker. Apache Camel is an open-source integration framework facilitating seamless communication between applications, systems, and services. It simplifies connecting disparate components by providing a flexible and extensible platform.
Key features of Apache Camel:
Routing Engine: Camel allows you to define routes that connect various endpoints (such as databases, messaging systems, APIs, and files). These routes guide the flow of data between components.
Component-Based: Camel supports many components (e.g., HTTP, JMS, FTP, REST) out of the box. You can also create custom components tailored to your specific needs.
Domain-Specific Language (DSL): Camel offers a concise DSL for defining integration routes. This DSL abstracts away the complexities of low-level APIs.
Enterprise Integration Patterns (EIP): Camel implements EIPs, which provide standardized solutions for common integration challenges.
Extensibility: You can easily extend Camel by adding custom processors, components, and data transformations.
Testing Support: Camel provides robust testing capabilities to ensure the correctness of your integration flows.
TSANet Connect – Database Structure
TSANet Connect is designed to provide a simple and flexible method for Members to collaborate. The following objects are found in the database to support the collaboration process:
Groups: Groups are used to create relationships between Members. A Member could be part of several groups. One-Many and Many-Many groups are supported. TSANet-hosted groups and Member-hosted groups are used. Groups define the rules for collaboration (For example SLA response times)
Accounts: Accounts provide high-level information about a Member. Integration is at an account level so if multiple systems are used within a Member company Parent - Child accounts can be created.
Departments: An account can have one or more departments. This allows you to assign separate process forms for departments (e.g., Division A and Division B).
Users: Users are associated with an account. A Members Identify management system can manage user access through SAML2.0.
Process Forms: An account can have one or more forms. These forms are linked to a department or group to support inbound workflow. They define what data the member receives for inbound requests.
TSANet Cases: Metadata for a collaboration request (Sender and Receiver metadata).
Case Responses: Initial response and updates
Case Notes: Notes related to a collaboration
Case Attachments: Secure File transfer method (Integrates to Members Secure File Storage)
A facade pattern has been implemented to facilitate the translation of API consumer language to database persistence language.
TSANet Connect REST API
TSANet provides a complete set of APIs to create apps and custom integrations. Authentication, webhooks, and the full endpoint summary are on the API Reference page, with generated request and response schemas on the reference pages listed in the sidebar.
Postman Collection is also available at: Postman Collection
Contact TSANet at membership@tsanet.org to request access to the Beta site. The Salesforce reference integration section provides an example of how these APIs are used.
TSANet Case Status and Priority.
The TSANet case status and Priority are separate from the member's case. Members can map these to their case or keep them separate.
Priority: P1 (High), P2 (Medium), P3 (Low). The system defines and monitors each SLA's initial response. If the SLA is not met, an escalation workflow triggers, alerting both the sender and receiver management contacts. Default SLAs are set in TSANet Hosted groups (P1=2hr, P2=4hr, P3=24Hr). Member can modify these defaults in their Hosted groups.
Status: The following status definitions are used.
Open (New waiting for initial response)
Information (Sent if information is needed to accept or reject)
Accepted (Collaboration Accepted)
Rejected (Collaboration rejected. For example, the end customer does not have support). This status is not used for solution or OEM support models.
Closed (set by submitter or auto-close after 30 days of inactivity)
The diagram below shows the valid state transitions
Error Handling
The /v1 API has two error-response modes, selected by the request's Accept header. This is documented, permanent behavior — not a defect to work around.
Default (legacy). No Accept header, or Accept: application/json only. Most business-rule, validation, and authorization rejections return HTTP 500 with a {"message": "..."} body. This is locked in for backward compatibility with existing integrations and will not change.
RFC 7807 (opt-in). Send Accept: application/json, application/problem+json. The same rejections return their documented status code (400/401/403/404/409/422) with a structured error body: {type, title, status, detail, instance}.
Recommended for all new integrations:
List application/json first. With application/problem+json alone, successful (200) responses are also labeled Content-Type: application/problem+json, which can confuse content-type-keyed HTTP clients. Branch on the response status code, and read the error message from detail, falling back to title.
Example — GET /v1/collaboration-requests/{unknownToken}:
Without the header:
500—{"message": "Case with token ... not found."}With the header:
404—{"type": "...", "title": "Not Found", "status": 404, "detail": "Case with token ... not found.", "instance": "/v1/collaboration-requests/..."}
Integration Process
Beta Environment
Members can access the Beta environment to develop and test integrations. TSANet will provide the following:
User account on the system (Beta-Member_Name). User/password for API
Connection to the Test Account or other Members also in Beta to support end-end testing.
API Documentation and Postman collection
Access to System Apps
Access to the Connect SDK (To assist in creating new Apps and Custom Integrations)
Access to a TSANet developer resource for questions and assistance with integration.
TSANet will work with members to co-develop Apps for reuse in the most common systems. For an example of this approach, see the Salesforce reference implementation section.
Production Environment
After validating the Member integration, TSANet will work with the Member to transition to the Production environment.
Last updated