The architecture and technical structure of the Telco Company connector

After a short late start 00:00, Speaker 1 framed the goal 00:41: an overview of the connector architecture as currently implemented — explicitly acknowledging that “some design choices may not be ideal,” but keeping the focus on the existing state, not on redesign. The slides largely condense a more detailed document shared the previous week; a review of that document had already been requested and was acknowledged as the more insightful artifact.

Speaker 2 and Speaker 3 were invited as backup experts — Speaker 3 specifically for front-end aspects, to which he also contributed a section. Why this framing matters: the presenter enforced this boundary several times during the call — improvement ideas and future-architecture questions were consistently parked “offline” for follow-up with specialists.

Starting at 02:04, Speaker 1 walked the chain:

• TelcoCRMWebApp — the main web application and integration entry point.
• TelcoCRM — generic, provider-independent CRM orchestration, routing and data normalization.
• Provider connectors — Salesforce and HubSpot today; a New CRM connector (e.g., MS Dynamics) is a third-party implementation of the very same contract.
• External CRM — Salesforce, HubSpot, MS Dynamics or any other supported system.

Key principle on the slide: TelcoCRM stays provider-independent; the connector owns provider-specific API details. The only hard requirement for a new provider is to implement the documented interface 02:50 — getContact, create/update contact, notes. Internal flow organization is up to the implementer; it does not have to mirror the Salesforce/HubSpot implementations 03:05.

From 04:42: provider configuration is stored in a database configuration table. The entry is instantiated automatically when the CRM provider is provisioned/activated — triggers fire and create the row with the provider details 07:08. The Connect use case then performs the OAuth authorization against the CRM and populates the row with the refresh token and access token 08:02.

The authorization flow in the GUI 31:21: an OAuth icon points to the REST API defined in the connector → request to the provider → the provider presents its login page → on success it redirects to the configured redirect URL → the platform flow receives access token, refresh token, scope, type and (optionally) expiry 18:42 → tokens are persisted and used for all subsequent REST requests.

Tokens are stored in the VPBX, unique per connector + company 32:57. The first user of a company who completes authorization “opens the door” for all other users of that company 33:36.

Prompted by Speaker 5's question (relayed by Speaker 2 10:56), Speaker 1 switched from slides to the vendor platform's dev portal 14:08 and opened the Salesforce module: southbound API → OAuth configuration tab 14:56. This is where the redirect URL, client ID, client secret, authorization/token URLs and scopes live — and these values must be consistent with what is registered at the third party 15:28.

Speaker 1 separated the two concepts cleanly 16:59:

• Authentication — validating that the caller is a valid VPBX user with a session inside the vendor platform.
• Authorization — allowing the application to talk to the third-party CRM on the user's behalf (OAuth).

Company context flow 25:00: a call arrives in the VPBX workplace and opens the CRM iframe → the iframe carries a token with userId, companyId and validity → the token is validated client-side and companyId is set as a security property → it becomes available to all TelcoCRM server flows → the Persistence API applies companyId as a filter automatically 26:12. Requests lacking the security property fail with an error 29:38.

Confirmed in Q&A 29:58: it is enough to declare a parameter named companyId/userId in the API and it is filled in automatically — but only for the Persistence API (every database interaction inside the VPBX model), not for external REST calls to the CRM 30:30.

Explained from 33:52. The currently implemented strategy — used for both HubSpot and Salesforce 38:21 — is refresh-and-retry-after-failure:

• Send the CRM request “blindly” with the stored access token — no validity check.
• Only if the response is an OAuth/token error → call the refresh-token request.
• On success → persist the new token and retry the original request exactly once.

The alternative — validate-before-request (pre-emptive refresh based on token expiry) — is described in the shared document (chapter 5.3, raised at 36:57). Both approaches may be implemented in a connector, but it is not a configuration switch: Salesforce does not return expiry information, so the pre-emptive approach cannot be universal; HubSpot (and providers that expose expiry) can use it 36:26. The only contract constraint is consistency of what the connector returns to TelcoCRM and ultimately the GUI 37:44.

Summarized on slide 9 42:24 and confirmed in dialogue 44:07:

• Create a separate provider connector module alongside the existing Salesforce and HubSpot connectors.
• Implement the required connector interfaces using the provider's REST API.
• Map generic contact field/value inputs to the provider-specific request format.
• Return provider-specific raw JSON where the contract uses ANY; TelcoCRM handles the common-model mapping.
• Implement OAuth2 authorization, token exchange and refresh behavior for the provider.
• Add provider-specific branches in TelcoCRM (“a branch to almost every flow”) and the small GUI/configuration additions needed to make the provider selectable — front-end details deferred to Speaker 3.

Stated goal: keep provider-specific implementation inside the connector while preserving the existing Telco Company CRM interfaces and data model.

How many connectors? Speaker 8 asked Speaker 4 directly 45:07. Answer: a living wish list of 6–7 CRMs from customers; not all will be built, the list may grow, and winning a large customer could add specific ones. MS Dynamics is the deliberate learning case that should make each subsequent connector cheaper 46:09.

The trade-off. Speaker 8 framed it 47:37: a fully dynamic, pluggable system is harder to secure than platform-native flows with manual per-provider additions — but at ~20 connectors the dynamic investment might pay off. Speaker 5 made it concrete 48:22: the two existing server flows are already big; with six providers branching inside them, pinpointing bugs and maintaining the flows becomes hard, so modularity should be an explicit design goal — “not to repeat the same error again and again” 49:27.

Could TelcoCRM be change-free per new connector? Asked at 51:27: could the model reach a state where adding a connector requires no TelcoCRM changes at all? Speaker 1 acknowledged the point but kept it within scope — this goes offline to the experts as an improvement exercise 52:03; Speaker 4 asked for that exercise to actually happen 52:20. No feasibility commitment was made.

Speaker 5 asked how global variables can be consumed in JavaScript, dialogs and modules 53:06. Speaker 3 shared his screen and demonstrated 53:58:

• In a JavaScript icon, access globals via VariableService.global; configuration-defined variables live under .config 54:48.
• In flow set icons, global variables appear with a globe symbol; hover reveals whether a variable is global 56:18.
• Common patterns: copy a global into a local flow variable and reference it from the flow, or call the service directly inside heavier JavaScript logic 56:54.

Wrap-up from 57:56. The team named its biggest blockers:

Next steps: Speaker 4 sends the topic list by email/Teams (points already posted in the Teams channel; redirect URI to be added 62:40). A next session was floated for Wednesday 63:50. Speaker 8's process suggestion 64:02: because specialists are scattered, collect questions upfront and categorize sessions (OAuth integration vs. front-end) so the right experts attend, rather than expecting one call to cover everything.

• Three of the four blockers left the meeting unanswered (redirect URI generation, preview testing, IPv6), two of them as “I'll follow up” without an owner or date. With the presenter's vacation imminent, pinning owners in the Teams list is the highest-leverage follow-up.
• The reference implementation encodes at least two admitted workarounds: the custom refresh endpoint (instead of the built-in mechanism) and retry-after-failure chosen partly because Salesforce lacks expiry. Copying Salesforce/HubSpot verbatim for Dynamics would propagate them — and Dynamics/Entra ID tokens do carry expiry, making the pre-emptive strategy viable there.
• The scalability concern was validated but deferred. Since the vendor confirmed implementers are “at liberty” inside their own module, the pragmatic move is to make the Dynamics module exemplary in modularity even if TelcoCRM's per-provider branching can't change yet.