Account Settings API Onboarding

Introduction

This document provides a comprehensive overview of the onboarding process for the Account Settings API within the Account Visibility project. The Account Settings API delivers a unified, scalable, and supportable solution for clients to manage the visibility of their accounts across all Investec business units. This guide outlines the steps that API consumers need to follow to start using the Account Settings service.

Business Unit Example: Throughout this documentation, {business-unit} placeholders are used to represent your specific business unit identifier. For example, Private Bank would use pbza as their business unit identifier, resulting in names like pbza-accst instead of {business-unit}-accst.

Prerequisites

Before beginning the onboarding process, ensure you have the following:

• Azure Subscription: Active Azure subscription with appropriate permissions
• Development Environment: Access to development tools and IDE
• Repository Access: Permissions to create and manage repositories
• Network Access: Ability to access Investec internal systems and Azure DevOps
• Administrative Access: Required permissions to register applications and create resource groups

Getting Started

Step 1: Azure Infrastructure Setup

1.1 Create Azure Subscription

Ensure you have an active Azure subscription for your project. Contact your Azure administrator if you need a new subscription.

1.2 Create Resource Groups

Create the following resource groups in your Azure subscription:

• Development: rg-{project-name}-dev
• Test: rg-{project-name}-test
• Non-Production: rg-{project-name}-nonprod
• Production: rg-{project-name}-prod

1.3 Register Azure AD Application

Register your Azure AD application through the Infrastructure as Code process:

1. Navigate to the ice-infrastructure-as-code repository:

   https://dev.azure.com/investec/ice-infrastructure-as-code/_git/azure-ad-applications?path=/DeploymentFiles/projects

2. Fork the repository into your sandbox environment

3. Create your application directory under /DeploymentFiles/projects/

4. Add the relevant configuration files: reference on of the existing adapp configs

5. Commit your changes with a descriptive commit message:

6. Create a Pull Request and send it to the Landing Zone PR Channel for review and approval

7. Note the Application (client) ID once the application is created - you'll need this for later configuration steps

1.4 Set Up Service Connections

Configure the necessary Azure DevOps service connections for your project to enable automated deployments and resource management.

Step 2: Repository Setup

2.1 Create Repository

Create a new repository for your project in Azure DevOps or your preferred Git hosting service.

2.2 Set Up Repository Structure

Ensure your repository follows the standard structure for Account Settings API implementations.

Step 3: Request Access and Permissions

3.1 Request Onboarding Support

Send an email to CXTOnePlaceTeam@investec.co.za with the following details:

• Subject: Request for Account Setting Onboarding on Dashboard API
• Business Unit: Your business unit name
• Project Name: Your project identifier e.g. PBZA,WealthZA,LifeZA
• Azure AD App ID: The application ID from Step 1.3
• Expected Go-Live Date: Target deployment date

3.2 Raise SNOW Request

Create a ServiceNow request under Investec Cloud Apps category:

• Request Type: API Permission Grant
• Details: Request Dashboard API Azure AD app permissions
  • aadapp-cxt-io-dashboard-api-client-nonprod (for non-production)
  • aadapp-cxt-io-dashboard-api-client-prod (for production)
• Target Azure AD App: Your application ID from Step 1.3

Step 4: SQL Server and Database Provisioning

4.1 Prepare Database Requirements

Before requesting database provisioning, ensure you have reviewed the requirements on the Azure Provision - Information we need | PVBDBA Confluence page:

• Navigate to: https://oneinvestec.atlassian.net/wiki/spaces/PBITZA/pages/286706116/Azure+Provision+-+Information+we+need+PVBDBA
• Review all required information and prerequisites for database provisioning

4.2 Raise ServiceNow Request for SQL Server and Database

Create a ServiceNow request for SQL Server and database creation:

• Request Type: Database Provisioning
• Reference: Use RITM0427060 as a reference for similar requests
• Required Information:
  • Virtual Network (vNet): Provide your vNet details (should be provisioned with your application resources)
  • Resource Group: Specify the resource group for each environment
  • Environment Details: Dev, Test, Non-Prod, and Prod requirements
  • Security Requirements: Any specific security or compliance needs

4.3 Service Principal Configuration

Request the appropriate Service Principal (SP) for database access across environments:

Development Environment:

• Request: sp-cxtdata-sqldb-gen-dev-001 (or equivalent for your business unit)

4.4 Required Information for DBA Team

Provide the following information to the DBA team in your ServiceNow request:

• Virtual Network (vNet): Your application's vNet details
• Service Principal: Your deployment service principal information
• Resource Group Names: For each environment

Note: Database connection documentation is currently being finalized. Updated connection string formats and authentication methods will be provided once available.

Development Environment Setup

Step 5: Install Development Tools

5.1 Install .NET Core 8

1. Download and install .NET Core 8 SDK from Microsoft's official site
2. Verify installation:

   dotnet --version

5.2 Install Required Tools

• Git: For version control
• Azure CLI: For Azure resource management
• Visual Studio or VS Code: Recommended IDE

Step 6: Clone and Configure Template

6.1 Clone Account Settings Template

git clone https://dev.azure.com/investec/client-channel-tech/_git/cxt-account-settings-api

6.2 Clone Your Business Unit Repository

git clone [your-bu-repository-url]
cd [your-bu-repository]
git checkout -b feat/initialDeployment

6.3 Copy Template Files

1. Copy all files from the template repository except the NUGET directory
2. Add these files to your business unit repository

Configuration

Step 7: Application Configuration

7.1 Update appsettings.json

Navigate to your application's appsettings.json file and update:

{
  "AzureAd": {
    "ClientId": "[your-aad-app-client-id]",
    "Audience": "[your-aad-app-client-id]",
    // ... other settings
  }
}

Step 8: Pipeline Configuration

8.1 Update Environment Variables

Navigate to .azuredevops/templates/variables/ and update the following files:

For dev.yml and nonprod.yml:

variables:
  resourceGroupName: "rg-{business-unit}-account-settings-{environment}"
  serviceConnection: "{your-service-connection}"
  aadAppServiceConnection: "{your-aad-service-connection}"
  azureAdAppRegistrationClientId: "{your-client-id}"
  azureAdAppRegApplicationIdUri: "{your-app-id-uri}"

For global.yml:

variables:
  owner: "{your-team-name}"
  costCenter: "{your-cost-center}"
  application: "cxt-account-settings-api-{business-unit}"
  description: "Account Settings API for {Business Unit}"
  repo: "{your-repository-name}"
  subscriptionName: "{your-azure-subscription}"
  containerImageName: "client-channel-tech/cxt-account-settings-api-{business-unit}"

8.2 Update azure.yaml

In the root azure.yaml file, update the name field:

name: cxt-account-settings-api-{business-unit}
# ... rest of configuration

8.3 Update naming.yml File

Navigate to the naming configuration file and update resource names to include your business unit prefix.

Example using Private Bank (pbza) as business unit:

nameSnapshot section:

nameSnapshot:
  # Change from: cxtAccstLogAnalyticsWorkspace
  # To: pbzaAccstLogAnalyticsWorkspace
  # Apply same pattern to other resources

names section:

names:
  # Change from: cxt-accst
  # To: {business-unit}-accst (e.g., pbza-accst)
  # ... other name mappings

Important: After updating naming.yml, ensure you also update the following files with the same naming convention:

1. validate-infra.yml: Update any resource name references to match your nameSnapshot values
2. deploy.yml: Update deployment target names to match your nameSnapshot values

Example for validate-infra.yml and deploy.yml:

# Use the same names as defined in nameSnapshot
resourceName: pbzaAccstLogAnalyticsWorkspace
# instead of: cxtAccstLogAnalyticsWorkspace

Deployment

Step 9: Initial Deployment

9.1 Commit Changes

git add .
git commit -m "feat: initial Account Settings API setup for {business-unit}"
git push origin feat/initialDeployment

9.2 Run Pipeline

1. Navigate to Azure DevOps Pipelines
2. Run the deployment pipeline for your project
3. Monitor the deployment process
4. Verify successful deployment across all environments

Post-Deployment Verification

Step 10: Testing and Validation

10.1 Health Check

Verify that your API endpoints are responding:

• Development: https://{dev-api-url}/api/health
• Non-Production: https://{nonprod-api-url}/api/health
• Production: https://{prod-api-url}/api/health

10.2 Authentication Testing

Test Azure AD authentication integration:

1. Obtain access token using your Azure AD app
2. Make authenticated requests to API endpoints
3. Verify proper authorization and response

10.3 Functional Testing

Perform basic CRUD operations:

• Create account settings
• Retrieve account settings
• Update account settings
• Delete account settings

Troubleshooting

Common Issues

Authentication Failures

• Issue: 401 Unauthorized responses
• Solution: Verify Azure AD app configuration and permissions

Pipeline Failures

• Issue: Deployment pipeline failures
• Solution: Check service connections and variable configurations

Network Connectivity

• Issue: Unable to reach API endpoints
• Solution: Verify network security groups and firewall rules

Getting Help

For additional support:

• Technical Issues: Contact CXTOnePlaceTeam@investec.co.za
• Infrastructure Issues: Raise ServiceNow ticket under Investec Cloud Apps
• Documentation: Refer to the API Documentation

Next Steps

After successful onboarding:

1. Integration Development: Begin integrating with your business applications
2. Monitoring Setup: Configure application monitoring and alerting
3. Documentation: Update your project documentation
4. Testing Strategy: Implement comprehensive testing procedures
5. Go-Live Planning: Plan your production rollout strategy

Additional Resources

• API Overview
• API Layer Documentation
• Dashboard Layer Documentation
• NuGet Package Documentation

---

Note: This guide provides a general onboarding process. Specific requirements may vary based on your business unit's needs and infrastructure setup. Always consult with the CXT One Place Team for business unit-specific guidance.