Financial Dimensions API Documentation

Overview

The Financial Dimensions sub-module provides shared dimensional infrastructure used across all finance modules. This module enables multi-dimensional accounting by providing dimension attribute management, value validation, and default dimension sets for master data integration.

Available APIs

Core Dimension Management

• Dimension Attributes API Planned

  • Base URL: /financial-dimensions/dimension-attributes
  • Features: Dimension definition, custom vs entity-backed types, activation lifecycle
  • Integration: Core service for defining dimensional structures

• Dimension Values API Planned

  • Base URL: /financial-dimensions/dimension-attributes/{id}/values
  • Features: Value management, validation, suspension/activation, group dimensions

Default Dimension Sets

• Dimension Attribute Value Sets API Planned
  • Base URL: /financial-dimensions/dimension-value-sets
  • Features: Default dimension collections, hash-based deduplication, master data integration

Lookup & Validation Services

• Dimension Lookup API Planned
  • Base URL: /financial-dimensions/lookups
  • Features: Fast lookup services, type-ahead support, multi-criteria validation

Cross-Module Integration

• Dimension Resolution Service Planned
  • Purpose: Shared service used by other modules for dimension value resolution
  • Features: Get-or-create pattern, string to ID resolution, validation

Quick Start

Basic Dimension Setup Workflow

// 1. Create a custom dimension attribute
const dimension = await fetch('/financial-dimensions/dimension-attributes', {
  method: 'POST',
  body: JSON.stringify({
    name: "Department",
    report_column_name: "Dept",
    type: "CustomList",
    description: "Organizational departments"
  })
});

// 2. Add dimension values
const values = await Promise.all([
  fetch(`/financial-dimensions/dimension-attributes/${dimension.id}/values`, {
    method: 'POST',
    body: JSON.stringify({
      value: "SALES",
      description: "Sales Department",
      group_dimension: "Revenue"
    })
  }),
  fetch(`/financial-dimensions/dimension-attributes/${dimension.id}/values`, {
    method: 'POST', 
    body: JSON.stringify({
      value: "ADMIN",
      description: "Administration",
      group_dimension: "Overhead"
    })
  })
]);

// 3. Activate the dimension for use
await fetch(`/financial-dimensions/dimension-attributes/${dimension.id}/activate`, {
  method: 'PATCH'
});

Creating Default Dimension Sets

// Create a default dimension set for a customer
const dimensionSet = await fetch('/financial-dimensions/dimension-value-sets/get-or-create', {
  method: 'POST',
  body: JSON.stringify({
    dimension_segments: [
      { dimension_attribute_id: departmentDimId, value: "SALES" },
      { dimension_attribute_id: costCenterDimId, value: "CC001" }
    ],
    description: "Default dimensions for sales customers"
  })
});

// Use the dimension set ID in customer master data
await fetch(`/accounts-receivable/customers/${customerId}`, {
  method: 'PUT',
  body: JSON.stringify({
    default_dimension_id: dimensionSet.id,
    // ... other customer data
  })
});

Integration Patterns

With General Ledger Module

// GL uses dimension resolution for transaction entry
const resolutionService = {
  async resolveSegmentValues(segmentInputs) {
    // This calls the Financial Dimensions resolution service
    return await fetch('/general-ledger/dimension-combinations/resolve-and-suggest-segments', {
      method: 'POST',
      body: JSON.stringify({
        ledger_id: currentLedger,
        segment_inputs: segmentInputs
      })
    });
  }
};

// Behind the scenes, GL calls FD services for value resolution
// FD returns stable IDs that GL uses in dimension combinations

With Master Data Modules (Future)

// Customer setup with default dimensions
const customer = await fetch('/accounts-receivable/customers', {
  method: 'POST',
  body: JSON.stringify({
    name: "Acme Corporation",
    default_dimensions: [
      { dimension_attribute_id: departmentDimId, value: "SALES" },
      { dimension_attribute_id: regionDimId, value: "NORTH" }
    ]
  })
});

// FD automatically creates dimension value set and returns ID
// Customer stores the dimension set ID for inheritance

Dynamic Dimension Providers

// For entity-backed dimensions (e.g., Customer dimension)
class CustomerDimensionProvider {
  async getValues(searchContext) {
    // Returns customer data formatted as dimension values
    const customers = await fetch('/crm/customers', {
      params: { search: searchContext.searchTerm, limit: 10 }
    });
    
    return customers.map(customer => ({
      id: customer.id,
      value: customer.customer_number,
      display_value: customer.name,
      is_suspended: !customer.is_active
    }));
  }
}

Dimension Types & Configuration

Custom List Dimensions

{
  "name": "Department",
  "type": "CustomList",
  "report_column_name": "Dept",
  "description": "Organizational departments",
  "values": [
    {
      "value": "SALES",
      "description": "Sales Department", 
      "group_dimension": "Revenue",
      "is_suspended": false
    }
  ]
}

Entity-Backed Dimensions

{
  "name": "Customer",
  "type": "DynamicEntity",
  "backing_entity_key": "customer",
  "value_attribute": "customer_number",
  "name_attribute": "customer_name",
  "key_attribute": "id",
  "provider_module": "accounts-receivable"
}

Financial Dimensions (Special)

{
  "name": "MainAccount",
  "type": "FinancialDimension",
  "backing_entity_key": "main_account",
  "is_system_required": true,
  "validation_rules": {
    "required": true,
    "unique_per_structure": true
  }
}

Lookup & Validation Services

Fast Dimension Lookups

// Type-ahead search for dimension values
const searchDimensionValues = async (dimensionId, searchTerm) => {
  return await fetch(`/financial-dimensions/lookups/dimension-attributes/${dimensionId}/values`, {
    params: {
      search: searchTerm,
      limit: 10,
      exclude_suspended: true
    }
  });
};

// Validate multiple dimension values at once
const validateDimensions = async (dimensionValueMap) => {
  return await fetch('/financial-dimensions/lookups/validate-dimension-values', {
    method: 'POST',
    body: JSON.stringify(dimensionValueMap)
  });
};

Cross-Dimensional Validation

// Validate that dimension combinations make business sense
const validateCombination = async (segments) => {
  return await fetch('/financial-dimensions/lookups/validate-combination', {
    method: 'POST',
    body: JSON.stringify({
      segments: segments,
      validation_rules: [
        "department_cost_center_consistency",
        "customer_region_alignment"
      ]
    })
  });
};

Performance Considerations

Caching Strategy

// Client-side caching for dimension metadata
const dimensionMetadataCache = {
  cache: new Map(),
  TTL: 60 * 60 * 1000, // 1 hour
  
  async get(dimensionId) {
    const cached = this.cache.get(dimensionId);
    if (cached && Date.now() - cached.timestamp < this.TTL) {
      return cached.data;
    }
    
    const data = await fetch(`/financial-dimensions/dimension-attributes/${dimensionId}`);
    this.cache.set(dimensionId, { data, timestamp: Date.now() });
    return data;
  }
};

// Value lookup caching for frequent searches
const valueLookupCache = new Map();
const getCachedValues = debounce(async (dimensionId, searchTerm) => {
  const cacheKey = `${dimensionId}:${searchTerm}`;
  if (!valueLookupCache.has(cacheKey)) {
    const values = await searchDimensionValues(dimensionId, searchTerm);
    valueLookupCache.set(cacheKey, values);
    // Clear cache after 5 minutes
    setTimeout(() => valueLookupCache.delete(cacheKey), 5 * 60 * 1000);
  }
  return valueLookupCache.get(cacheKey);
}, 200);

Bulk Operations

// Efficient bulk dimension value creation
const createBulkDimensionValues = async (dimensionId, values) => {
  return await fetch(`/financial-dimensions/dimension-attributes/${dimensionId}/values/bulk`, {
    method: 'POST',
    body: JSON.stringify({
      values: values,
      batch_size: 100
    })
  });
};

// Bulk dimension set creation for data migration
const createBulkDimensionSets = async (dimensionSets) => {
  return await fetch('/financial-dimensions/dimension-value-sets/bulk', {
    method: 'POST',
    body: JSON.stringify({
      dimension_sets: dimensionSets,
      enable_deduplication: true
    })
  });
};

Security & Data Governance

Dimension Access Control

// Role-based dimension access
const checkDimensionAccess = async (dimensionId, operation) => {
  return await fetch(`/financial-dimensions/dimension-attributes/${dimensionId}/access`, {
    method: 'POST',
    body: JSON.stringify({
      operation: operation, // 'read', 'write', 'admin'
      user_context: getCurrentUserContext()
    })
  });
};

Data Privacy & Masking

// PII-sensitive dimensions (like Customer) may be masked
const getDimensionValuesWithPrivacy = async (dimensionId, privacyLevel) => {
  return await fetch(`/financial-dimensions/dimension-attributes/${dimensionId}/values`, {
    headers: {
      'X-Privacy-Level': privacyLevel, // 'full', 'masked', 'anonymized'
      'X-Data-Purpose': 'financial-reporting'
    }
  });
};

Testing

Dimension Lifecycle Testing

# Create dimension
POST /financial-dimensions/dimension-attributes
{
  "name": "TestDepartment",
  "type": "CustomList"
}

# Add values
POST /financial-dimensions/dimension-attributes/{id}/values
{
  "value": "TEST_DEPT",
  "description": "Test Department"
}

# Activate dimension
PATCH /financial-dimensions/dimension-attributes/{id}/activate

# Search values
GET /financial-dimensions/lookups/dimension-attributes/{id}/values?search=TEST

# Validate values
POST /financial-dimensions/lookups/validate-dimension-values
{
  "{dimension-id}": "TEST_DEPT"
}

# Create dimension set
POST /financial-dimensions/dimension-value-sets/get-or-create
{
  "dimension_segments": [...]
}

# Suspend value
PATCH /financial-dimensions/dimension-attributes/{id}/values/{value-id}/suspend

# Deactivate dimension
PATCH /financial-dimensions/dimension-attributes/{id}/deactivate

Related Documentation

Core Documentation

• Financial Dimensions Domain Documentation - Business logic and rules
• Dimension Architecture Concepts - System design
• Master Data Integration Guide - Setup instructions

Integration Documentation

• General Ledger API - Primary consumer of dimension services
• Cross-Module Integration - Integration patterns
• Default Dimensions Workflow - Master data integration

---

Last Updated: [Current Date] | Version: 1.0 | Status: Planning Phase

Development Priority: Foundation for all finance module dimensional capabilities Dependencies: Core infrastructure for General Ledger, AR, and AP modules Integration Points: All finance modules, CRM, Inventory modules