Guides

Simple E2E Strategy - Technical Overview

A synchronous approach for e2e guaranteed delivery.


🚧

Under construction and subject to changes

Summary

The Alert to Ticket Module provides Integrators with the capabilities to automatically create PSA tickets from your alerts. The system features multi-layered control mechanisms, intelligent duplicate handling, and self-healing capabilities to streamline Partner incident management workflows. This approach is designed for low throughput alerting. Where most alerts are expected to be created as tickets within the routed PSA integration. If this is not the expectation, please see the Webhook E2e Strategy.

Core Functionality

Automated Ticket Creation: Integrators can programmatically create PSA tickets through MSPCentric's oem alerting API, with intelligent routing to appropriate PSA queues/boards based on rule creation by the user.

Smart Duplicate Handling: The system prevents ticket spam by appending related alerts to existing tickets rather than creating duplicates, configurable per Partner preferences.

Self-Healing Resolution: When underlying issues resolve automatically, vendors can close associated tickets programmatically, reducing manual intervention requirements.

Layered Control System: Multiple configuration layers ensure Partners maintain full control:

  • Integration-level alerting enablement
  • Status-based suppression rules
  • Individual feature toggles (ticket creation, self-healing, de-duplication)
  • Granular account-to-PSA-queue mapping

Technical Architecture

API Structure: RESTful endpoints hosted on MSPCentric platform (/api/oem-alerts-api/*) with secure authentication and rate limiting.

Multi-PSA Support: Compatible with ConnectWise Manage, Datto Autotask(tbd), Halo PSA (tbd), Kaseya BMS, Syncro PSA (tbd), and Pulseway PSA.

Audit & Visibility: Comprehensive logging of all operations with dashboard visibility for Partners, including success/failure metrics and complete event history.

Rules Engine: Configurable suppression logic allowing MSPs to prevent ticket creation based on Product Groups, alert statuses, or custom business rules.

Integration Requirements

Vendors must implement alert detection logic, API integration for ticket operations, robust error handling with retry mechanisms, and correlation ID management for tracking ticket lifecycles. The system supports both real-time alert processing and historical status queries.

What am I implementing?

Scope: Implement API integration to automatically create PSA tickets from alerts.

API Endpoints (Hosted on MSPCentric Platform)

  • Alert POST /api/oem-alerts-api/alert/sync Alert endpoint that handles creating tickets, smart appending and auto-healing
  • List Tickets: GET /api/oem-alerts-api/alert - List all tickets for a partner
  • Get Ticket: GET /api/oem-alerts-api/alert/{correlationId}- Get ticket for Partner by correlationId
  • Integration Check: GET /api/oem-api/integration/list - Validate alerting enabled

Vendor Implementation Requirements

1. Alert Detection & Filtering

Key Considerations:

  • Consider alert frequency to avoid ticket spam

2. Determining Account IDs

Account ids for Vendor will be the Vendor identifiers that you apply to your accounts internally as a company. Therefore, it is a requirement that you provide unique identifiers via your Vendor API.

Retrieve Accounts

When calling the create alert endpoint, you will provide the internal Vendor identifier that uniquely identifies the company of your Partner.

All account identifiers should be retrievable via your own Vendor API as when we create those accounts within the integration, they are pulled from the Vendor API and stored for mapping.

3. Product Groups and Alert Types

To create agnostic of a product as possible and to give power into the hands of our users, we have devise Product Groups and Alert Types fields.

This allows users to create rules such that target specific product groupings with specific alert types and decide which queues to assign them to, with specific priorities, statuses, types, and subtypes.

To that end, as the Integrator, you must provide us a list of Product Groups and a list of corresponding Alert Types that match those product groups. This means that each product group will have a list of alert types associated to it.

We will store this as a list of comma separated values for use during runtime to help the rules engine determine which rule to use when calling the alert endpoint.

4. API Integration Development

Required API Calls:

Alert Creation:

POST /api/oem-alerts-api/alert/sync HTTP/1.1
Content-Type: application/json

{
  "clientId": "66abbbae5a078102ccf5790c6a84b4de4cac647110f3db597399cde2010d7d17",
  "clientSecret": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214eae3a0c2781a95efc1859347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "grantType": "client_credentials",
  "scope": "vendor_manage",
  "organizationOemToken": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214easdas34d39347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "integrationId": "690b98ea1a4906f08f785ad8",
  "data": {
    "title": "Backup Failed: Agent not checking in",
    "summary": "A descriptive summary of the incident.",
    "alertType": "Backup Failed",
    "accountId": "as23cCS13",
    "productGroup": "firewalls", 
    "incidentStatus": "OPEN"
  }
}

HTTP/1.1 201 OK
Content-Type: application/json

'{
	"statusCode": 201,
  "message": "created",
  "data": {
    "messageId": "string", <-- unique identifier for this single transaction
    "correlationID": "string" <-- unique identifier for entire lifecycle of an alert/ticket
  }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
	"statusCode": 201,
  "message": "suppressed"
  "data": {
    "messageId": "string", <-- unique identifier for this single transaction
    "correlationID": "string" <-- unique identifier for entire lifecycle of an alert/ticket
  }
}
HTTP/1.1 4XX OK
Content-Type: application/json

{
	"statusCode": 404,
  "message": "failed"
  "data": {
    "messageId": "string", <-- unique identifier for this single transaction
    "correlationID": "string" <-- unique identifier for entire lifecycle of an alert/ticket
  }
}
📘

Note: Optionally, you can provide your own unique correlationId in the Create Alert endpoint call to manage the lifecycle of a ticket if that works better within your system.

Smart Appending (appending or updating a ticket):

POST /api/oem-alerts-api/alert/sync HTTP/1.1
Content-Type: application/json

{
  "clientId": "66abbbae5a078102ccf5790c6a84b4de4cac647110f3db597399cde2010d7d17",
  "clientSecret": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214eae3a0c2781a95efc1859347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "grantType": "client_credentials",
  "scope": "vendor_manage",
  "organizationOemToken": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214easdas34d39347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
	"correlationId": "AS23-DSA4-ADF3-SASFD1", <--- pass the correlation id when appending
  "integrationId": "690b98ea1a4906f08f785ad8",
  "data": {
    "title": "Backup Failed: Agent not checking in",
    "summary": "A descriptive summary of the incident.",
    "alertType": "Backup Failed",
    "accountId": "as23cCS13",
    "productGroup": "firewalls", 
    "incidentStatus": "UPDATE" <--- pass update to ensure smart append
  }
}

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "message": "updated",
  "statusCode": 201,
  "data": {
    "messageId": "string", <-- unique identifier for this single transaction
    "correlationID": "string" <-- unique identifier for entire lifecycle of an alert/ticket
	}
}
HTTP/1.1 4XX OK
Content-Type: application/json

{
	"statusCode": 404,
  "message": "failed"
  "data": {
    "messageId": "string", <-- unique identifier for this single transaction
    "correlationID": "string" <-- unique identifier for entire lifecycle of an alert/ticket
  }
}

Auto-Healing:

POST /api/oem-alerts-api/alert/sync HTTP/1.1
Content-Type: application/json

{
  "clientId": "66abbbae5a078102ccf5790c6a84b4de4cac647110f3db597399cde2010d7d17",
  "clientSecret": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214eae3a0c2781a95efc1859347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "grantType": "client_credentials",
  "scope": "vendor_manage",
  "organizationOemToken": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214easdas34d39347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
	"correlationId": "AS23-DSA4-ADF3-SASFD1", <--- pass the correlation id when auto-healing
  "integrationId": "690b98ea1a4906f08f785ad8",
  "data": {
    "title": "Backup Failed: Agent not checking in",
    "summary": "A descriptive summary of the incident.",
    "alertType": "Backup Failed",
    "accountId": "as23cCS13",
    "productGroup": "firewalls", 
    "incidentStatus": "RESOLVED" <--- pass update to ensure auto-healing
  }
}
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "message": "closed",
  "statusCode": "200",
  "data": {
    "messageId": "string", <-- unique identifier for this single transaction
    "correlationID": "string" <-- unique identifier for entire lifecycle of an alert/ticket
	}
}

3. Customer Configuration Interface

Recommended UI Elements:

  • Test alert button
  • Alert preview/simulation

4. Error Handling & Retry Logic

Required Implementation:

  • Handle HTTP error responses (403 Forbidden, 500 errors, rate limits)
  • Implement retry logic for temporary failures
  • Log failed API calls for customer troubleshooting
  • Graceful degradation when MSPCentric API is unavailable

Error Scenarios to Handle:

  • Integration alerting disabled (409 Forbidden)
  • Alert suppressed by rules (409 OK, but no ticket created)
  • PSA system unavailable (500/502 errors)
  • Network connectivity issues

5. Correlation ID Management

Critical Requirement:

  • Store the correlationId returned from alert creation calls
  • Use correlationId for self-healing and smart-appending
  • Maintain mapping between your internal alerts and MSPCentric correlationIds
  • Implement correlation ID cleanup for resolved/closed alerts

Runtime Alert Processing:

  1. Alert Triggered: Your system detects an issue (e.g., backup failure)
  2. Create Ticket: Call MSPCentric API to create/append ticket
  3. Store Correlation: Save the returned correlationId for future reference
  4. Monitor Resolution: When issue resolves, call self-healing endpoint
  5. Handle Errors: Log any API failures and retry if appropriate

Error Handling

This section contains a list of possible known errors that our system will throw given certain scenarios when working with the Alerts API.

  1. 404 OemNotFoundException - Thrown when:
    1. No PSA found on the organization
    2. Account was not found in our system
    3. Account was not mapped by user and cannot be communicated to the psa
    4. User has no rules defined for a given Product Group
    5. User has turned off all rules for a Product Group
    6. Ticket not found that corresponds to the correlationId provided
    7. Rule was not found during smart append or auto-healing, means rule was likely deleted by the user
    8. Integration not found during smart append or auto-healing, means integration was likely removed by user.
  2. 409 OemConflictException - Thrown when:
    1. Integration is not in an active state to receive Alerts
    2. Alerts is not enabled for a user
  3. 500 OemInternalServerException - Throw when:
    1. Server encounters an unknown error