Dimension values

File: /docs/api/financial-dimensions/dimension-values.api.md
Module: FinancialDimensions
Base URL: /financial-dimensions/dimension-attributes/{dimensionAttributeId}/values

Overview

The Dimension Values API provides functionality for managing individual dimension values within CustomList dimension attributes. This API enables create, read, update, delete, and lifecycle management operations for dimension values that serve as the selectable options within custom financial dimensions.

This API operates as a nested resource under dimension attributes and follows RESTful conventions with CQRS patterns for command and query separation.

Important:

• All JSON requests and responses use snake_case naming convention
• This API only applies to CustomList type dimension attributes
• DynamicEntity dimensions get their values from backing entities and cannot be managed through this API

Core CRUD Operations

Create Dimension Value

POST /financial-dimensions/dimension-attributes/{dimensionAttributeId}/values

Creates a new dimension value for a CustomList dimension attribute.

Path Parameters:

• dimensionAttributeId (Guid): The parent dimension attribute identifier

Request Body:

{
  "value": "FINANCE",
  "description": "Finance Department - Accounting and Financial Planning",
  "group_dimension": "Support"
}

Request Properties:

Property	Type	Required	Description	Validation Rules
value	string	Yes	The dimension value code	1-100 characters, unique within dimension
description	string	No	Human-readable description	Max 500 characters
group_dimension	string	No	Group category for organization	Max 100 characters

Response:

{
  "id": "660e8400-e29b-41d4-a716-446655440003",
  "value": "FINANCE",
  "display_value": "FINANCE",
  "name": "Finance Department - Accounting and Financial Planning",
  "is_suspended": false,
  "is_blocked_for_manual_entry": false,
  "group_dimension": "Support",
  "entity_instance": null
}

HTTP Status Codes:

• 201 Created - Value created successfully (includes Location header)
• 400 Bad Request - Invalid request data or validation errors
• 404 Not Found - Parent dimension attribute not found
• 409 Conflict - Value already exists within the dimension

---

Retrieve Specific Dimension Value

GET /financial-dimensions/dimension-attributes/{dimensionAttributeId}/values/{id}

Retrieves detailed information for a specific dimension value.

Path Parameters:

• dimensionAttributeId (Guid): The parent dimension attribute identifier
• id (Guid): The dimension value identifier

Response:

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "value": "SALES",
  "display_value": "SALES",
  "name": "Sales Department",
  "is_suspended": false,
  "is_blocked_for_manual_entry": false,
  "group_dimension": "Revenue",
  "entity_instance": null
}

Response Properties:

Property	Type	Description
id	Guid	Unique identifier for the dimension value
value	string	The dimension value code
display_value	string	Display representation (usually same as value)
name	string	Human-readable description/name
is_suspended	boolean	Whether the value is currently suspended
is_blocked_for_manual_entry	boolean	Whether value can be manually entered
group_dimension	string	Group category for organization
entity_instance	Guid?	Reference to backing entity (null for CustomList)

HTTP Status Codes:

• 200 OK - Success
• 404 Not Found - Dimension attribute or value not found

---

Update Dimension Value

PUT /financial-dimensions/dimension-attributes/{dimensionAttributeId}/values/{id}

Updates an existing dimension value for CustomList dimensions only.

Path Parameters:

• dimensionAttributeId (Guid): The parent dimension attribute identifier
• id (Guid): The dimension value identifier

Request Body:

{
  "value": "FINANCE_UPDATED",
  "description": "Finance Department - Updated Description",
  "group_dimension": "Corporate"
}

Request Properties:

Property	Type	Required	Description	Validation Rules
value	string	Yes	Updated dimension value code	1-100 characters, unique within dimension
description	string	No	Updated description	Max 500 characters
group_dimension	string	No	Updated group category	Max 100 characters

Response:

• 204 No Content - Update successful

HTTP Status Codes:

• 204 No Content - Update successful
• 400 Bad Request - Invalid request data or not a CustomList dimension
• 404 Not Found - Dimension attribute or value not found
• 409 Conflict - Updated value conflicts with existing value

---

Delete Dimension Value

DELETE /financial-dimensions/dimension-attributes/{dimensionAttributeId}/values/{id}

Deletes a dimension value from a CustomList dimension attribute.

Path Parameters:

• dimensionAttributeId (Guid): The parent dimension attribute identifier
• id (Guid): The dimension value identifier

Request Body: No body required

Response:

• 204 No Content - Deletion successful

HTTP Status Codes:

• 204 No Content - Deletion successful
• 400 Bad Request - Cannot delete (referenced by existing data or not CustomList)
• 404 Not Found - Dimension attribute or value not found

Business Rules:

• Values cannot be deleted if referenced by existing financial transactions
• Values cannot be deleted if used in dimension combinations
• Only applies to CustomList dimensions

---

Lifecycle Management

Suspend Dimension Value

PATCH /financial-dimensions/dimension-attributes/{dimensionAttributeId}/values/{id}/suspend

Suspends a dimension value, preventing its use in new transactions while preserving historical data.

Path Parameters:

• dimensionAttributeId (Guid): The parent dimension attribute identifier
• id (Guid): The dimension value identifier

Request Body: No body required

Response:

• 204 No Content - Suspension successful

HTTP Status Codes:

• 204 No Content - Suspension successful
• 404 Not Found - Dimension attribute or value not found

Business Impact:

• Suspended values cannot be selected in new financial transactions
• Existing transactions with suspended values remain valid
• Suspended values appear with visual indicators in user interfaces

---

Activate Dimension Value

PATCH /financial-dimensions/dimension-attributes/{dimensionAttributeId}/values/{id}/activate

Activates a previously suspended dimension value, making it available for use again.

Path Parameters:

• dimensionAttributeId (Guid): The parent dimension attribute identifier
• id (Guid): The dimension value identifier

Request Body: No body required

Response:

• 204 No Content - Activation successful

HTTP Status Codes:

• 204 No Content - Activation successful
• 404 Not Found - Dimension attribute or value not found

Business Impact:

• Activated values become available for selection in new transactions
• Values return to normal operational status
• User interfaces will show values as selectable options

---

Business Rules and Constraints

CustomList Dimension Restrictions

1. Value Uniqueness: Values must be unique within their parent dimension attribute
2. Manual Management: Only CustomList dimensions support direct value management through this API
3. Lifecycle Dependency: Values cannot be deleted if referenced by existing financial data

DynamicEntity Dimension Behavior

For DynamicEntity type dimensions:

• Values are automatically sourced from backing entities (Customer, Vendor, etc.)
• This API will return 400 Bad Request for create, update, delete operations
• Values are managed through the respective master data systems
• Suspension/activation may be controlled through backing entity status

MainAccount Dimension Behavior

For MainAccount type dimensions:

• Values come from the Chart of Accounts
• This API will return 400 Bad Request for all modification operations
• Values are managed through the General Ledger Chart of Accounts functionality

Integration Patterns

Financial Transaction Integration

When dimension values are used in financial transactions:

1. Validation: Transaction processing validates dimension values are active
2. Reference Integrity: System prevents deletion of values referenced by transactions
3. Historical Preservation: Suspended values maintain transaction history integrity

Master Data Integration

For backing entity dimensions:

• Customer/Vendor master data changes automatically reflect in dimension values
• Status changes in master data can trigger dimension value suspension
• Value resolution services bridge between string values and dimension IDs

Reporting Integration

Dimension values support financial reporting through:

• Group Dimensions: Enable hierarchical report organization
• Display Values: Provide user-friendly labels in reports
• Status Filtering: Allow reports to include/exclude suspended values

---

Error Handling

Standard Error Response Format

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "value": [
      "Value 'SALES' already exists in this dimension"
    ]
  },
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Common Error Scenarios

Scenario	HTTP Status	Description
Duplicate value in dimension	409 Conflict	Value already exists
Invalid dimension type	400 Bad Request	Operation not supported for dimension type
Value in use	400 Bad Request	Cannot delete/modify value referenced by transactions
Parent dimension not found	404 Not Found	Dimension attribute doesn't exist
Value not found	404 Not Found	Dimension value doesn't exist
Validation failure	400 Bad Request	Request data doesn't meet validation rules

Dimension Type Error Messages

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "title": "Operation not supported",
  "status": 400,
  "detail": "Values can only be added to CustomList dimensions.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

---

Performance Considerations

Caching Strategy

• Value Lists: Dimension values are cached for 1 hour after retrieval
• Validation Results: Value existence checks are cached for 30 minutes
• Group Hierarchies: Group dimension structures cached for 2 hours

Query Optimization

• Use parent dimension attribute filtering when querying multiple values
• Consider pagination for dimensions with large value sets (>100 values)
• Leverage group_dimension for hierarchical filtering in reports

Rate Limiting

• Standard rate limits: 1000 requests per hour per user
• Bulk operations recommended for creating multiple values
• Consider batch validation for transaction processing scenarios

---

Usage Examples

Creating Department Dimension Values

# Create Sales Department
curl -X POST \
  /financial-dimensions/dimension-attributes/550e8400-e29b-41d4-a716-446655440000/values \
  -H "Content-Type: application/json" \
  -d '{
    "value": "SALES",
    "description": "Sales and Marketing Department",
    "group_dimension": "Revenue"
  }'

# Create Finance Department  
curl -X POST \
  /financial-dimensions/dimension-attributes/550e8400-e29b-41d4-a716-446655440000/values \
  -H "Content-Type: application/json" \
  -d '{
    "value": "FINANCE", 
    "description": "Finance and Accounting Department",
    "group_dimension": "Support"
  }'

Suspending a Department Value

# Suspend the SALES department (e.g., during reorganization)
curl -X PATCH \
  /financial-dimensions/dimension-attributes/550e8400-e29b-41d4-a716-446655440000/values/660e8400-e29b-41d4-a716-446655440001/suspend

Updating Department Description

# Update Finance department description
curl -X PUT \
  /financial-dimensions/dimension-attributes/550e8400-e29b-41d4-a716-446655440000/values/660e8400-e29b-41d4-a716-446655440003 \
  -H "Content-Type: application/json" \
  -d '{
    "value": "FINANCE",
    "description": "Finance, Accounting, and Treasury Department", 
    "group_dimension": "Corporate"
  }'

---

Domain Events Generated

The Dimension Values API generates domain events as part of the event-driven architecture:

DimensionValueCreated

When: New dimension value is successfully created
Purpose: Notifies other modules of new selectable dimension option
Payload: DimensionAttributeId, ValueId, Value, Description, CreatedBy

DimensionValueUpdated

When: Dimension value properties are modified
Purpose: Updates dependent caches and UI elements
Payload: DimensionAttributeId, ValueId, ChangedProperties, UpdatedBy

DimensionValueSuspended

When: Dimension value is suspended
Purpose: Triggers validation rule updates and UI state changes
Payload: DimensionAttributeId, ValueId, SuspendedBy, Reason

DimensionValueActivated

When: Dimension value is reactivated
Purpose: Restores value availability in transaction processing
Payload: DimensionAttributeId, ValueId, ActivatedBy

DimensionValueDeleted

When: Dimension value is permanently deleted
Purpose: Triggers cleanup in dependent systems
Payload: DimensionAttributeId, ValueId, DeletedBy

---

API Version: v1.0
Last Updated: September 11, 2025
Status: Active Development
Dependencies: FinancialDimensions.Domain, Dimension Attributes API

---

Related APIs

• Dimension Attributes API - Parent dimension attribute management
• Dimension Attribute Value Sets API - Default dimension collections
• General Ledger API - Consumer of dimension values in transactions