> For the complete documentation index, see [llms.txt](https://tsanet.gitbook.io/connect/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tsanet.gitbook.io/connect/api-reference/integration-guide.md). # 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, Sean Dulac, Appko, **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 - **Apache Camel:** **Apache ActiveMQ**: #### **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: | | TSANet Connect | Extranet | B2B Integration | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | 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: **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](/connect/api-reference/readme.md) 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 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:** ``` Accept: application/json, application/problem+json ``` 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: 1. User account on the system (Beta-Member\_Name). User/password for API 2. Connection to the Test Account or other Members also in Beta to support end-end testing. 3. API Documentation and Postman collection 4. Access to System Apps 5. Access to the Connect SDK (To assist in creating new Apps and Custom Integrations) 6. 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.