#1. Getting Started

Connected Services Framework (CSF) — Part 2: Implementation — Version 2.0

#1.1 Purpose

This section provides a practical checklist for MAPs implementing the CSF. Whether you are a new MAP joining the network or an existing MAP adding CSF support, this guide covers the prerequisites and steps to get operational.

#1.2 Prerequisites

Before beginning implementation, ensure you have:

• Read Part 1: Framework to understand the architecture and principles
• Reviewed the JSON Asynchronous Messaging Specification (JAM) published on the OTA2 website
• Reviewed the RCPID Standards (in the process of being published by OTA2; no direct link available at the time of this publication — check the OTA2 website for the latest)
• Reviewed the Switching for Business Process Documents published on the FCS website
• Reviewed the TOTSCo Hub API Specification v2.0 for hub interoperability requirements
• Identified a Sponsor MAP (or been assigned one via the rotation)
• Agreed terms and costs with the Sponsor MAP for the onboarding process

#1.3 Implementation Checklist

#Infrastructure Setup

• Provision TLS 1.3-capable endpoints for:
  • Letterbox API (message sending/receiving)
  • Directory API (registry publishing)
  • OAuth 2.0 token endpoint
• Configure OAuth 2.0 authorisation server (Client Credentials flow)
• Set up PKI key management (generation, storage, rotation)
• Implement DNS management for CP _domainkey and _mapkey TXT records

#API Implementation

• Implement the Letterbox API — accepting JAM-formatted JSON messages via HTTP POST, returning HTTP 202 on success (see Message API)
• Implement the Directory API — serving your registry as a JSON document via HTTP GET (see Directory API)
• Implement OAuth 2.0 token endpoint — issuing access tokens to authenticated MAPs (see OAuth 2.0 Implementation)

#Security Implementation

• Implement DKIM message signing for outbound messages (see PKI & DKIM Signing)
• Implement DKIM signature verification for inbound messages
• Implement DNS-based CP verification — validating the _domainkey and _mapkey records
• Generate PKI key pairs for each CP (minimum RSA-2048 or Ed25519)

#Directory and Registry

• Build and publish your MAP registry in the specified JSON format
• Implement registry collection — pulling other MAPs' registries via their directory API
• Implement directory convergence — merging collected registries into a unified directory
• Implement conflict resolution — handling CPs that appear in multiple registries

#Message Processing

• Implement message validation — envelope structure, RCPID verification, signing validation
• Implement retry logic with exponential backoff for failed deliveries
• Implement asynchronous error handling using 9xxx (industry) and 8xxx (CSF) error codes
• Implement message delivery failure notifications to the originating CP/MAP

#Operations

• Set up monitoring and alerting for endpoint availability
• Implement status reporting in the registry (incident flags, planned changes)
• Establish audit logging for all message exchanges
• Implement rate limiting and denial-of-service protections

#Onboarding

• Complete Sponsor MAP assessment — technical, security, and compliance review
• Establish OAuth 2.0 credentials with the Sponsor MAP
• Pass connectivity testing with provisional/restricted access
• Pass process-level testing with test CPs
• Pass operational validation — delivery reliability, retry, and SLA compliance
• Pass exit criteria — including hidden unit tests and PKI verification
• Establish OAuth 2.0 credentials with all other MAPs
• Obtain full access approval from Sponsor MAP

#TOTSCo Integration (if applicable to the protocol e.g. SforB)

• Register CSF endpoints with TOTSCo using existing procedures
• Configure a dedicated endpoint for TOTSCo (separate from CSF MAP endpoint)
• Ensure TOTSCo can access your Directory API using existing OAuth 2.0 credentials
• Test message exchange with TOTSCo using their existing letterbox interface

See TOTSCo Integration for detailed integration guidance.

#1.4 Recommended Endpoint Structure

While the CSF does not mandate specific URL patterns, the following structure is recommended:

Best Practice: Maintain separate letterbox endpoints for CSF MAPs and HMAPs (e.g., TOTSCo). This allows the TAG to iterate the CSF rapidly without affecting established hub exchange networks.

#1.5 Development Resources