dimension_management

Dimensions in nullplatform are user-defined key-value tags that can be attached to scopes. They are used to group resources semantically (e.g., environment=production, region=us-east) and apply configurations to multiple scopes at once.

Key benefits:

• Apply parameter values to multiple scopes using dimensions instead of individual scopes
• Use dimensions in approval policies (e.g., require approval for all production deployments)
• Group scopes by business semantics (environment, region, team, etc.)

Precedence: When a scope has a dimension assigned, parameter values follow: Scope > Dimension > Application

Listing dimensions

To list dimensions at a specific NRN level:

Api Call:

Method: GET
Endpoint: /dimension?nrn=<nrn>

Np Cli:

np dimension list --nrn <nrn>

Example NRNs:

• Organization level: organization=123
• Account level: organization=123:account=456
• Namespace level: organization=123:account=456:namespace=789

This returns all dimensions defined at that level and inherited from parent levels.

Reading a specific dimension

To get details about a specific dimension:

Api Call:

Method: GET
Endpoint: /dimension/:id

Np Cli:

np dimension read --id <dimension_id>

This shows:

• Dimension name and slug
• NRN where it's defined
• Associated dimension values
• Order (for UI display)

Creating a dimension

Dimensions are typically created at organization or account level. Common dimensions include: environment, region, team, country.

Api Call:

Method: POST
Endpoint: /dimension
Body: '{
  "nrn": "<nrn>",
  "name": "Environment",
  "order": 1
}'

Np Cli:

np dimension create --body '{
  "nrn": "<nrn>",
  "name": "Environment",
  "order": 1
}'

Important notes:

• Dimensions require ops permissions to create
• You cannot have the same dimension in parent-child NRN levels
• You can have the same dimension in sibling NRN levels
• The order field controls display order in the UI

Listing dimension values

To list all values for a specific dimension:

Api Call:

Method: GET
Endpoint: /dimension/:dimensionId/value?nrn=<nrn>

Np Cli:

np dimension value list --dimensionId <dimension_id> --nrn <nrn>

Reading a specific dimension value

Api Call:

Method: GET
Endpoint: /dimension/:dimensionId/value/:id

Np Cli:

np dimension value read --dimensionId <dimension_id> --id <dimension_value_id>

Creating dimension values

After creating a dimension, you need to create values for it (e.g., production, staging, development).

Api Call:

Method: POST
Endpoint: /dimension/:dimensionId/value
Body: '{
  "nrn": "<nrn>",
  "name": "Production"
}'

Np Cli:

np dimension value create --dimensionId <dimension_id> --body '{
  "nrn": "<nrn>",
  "name": "Production"
}'

You can create dimension values at lower NRN levels than the dimension itself. For example:

• Dimension "Environment" created at organization=1
• Value "Production" created at organization=1:account=2
• Value "Development" created at organization=1:account=3

Assigning dimensions to scopes

When creating or updating a scope, you assign dimension values to it:

Api Call:

Method: POST
Endpoint: /scope
Body: '{
  "name": "Production US",
  "application_id": <application_id>,
  "dimensions": {
    "environment": "production",
    "region": "us-east"
  }
}'

Np Cli:

np scope create --body '{
  "name": "Production US",
  "application_id": <application_id>,
  "dimensions": {
    "environment": "production",
    "region": "us-east"
  }
}'

To see which dimensions are assigned to a scope:

np scope read --id <scope_id>

Common dimension examples

Example 1: Environment dimension

Create an "Environment" dimension with production, staging, and development values:

# Step 1: Create the dimension
np dimension create --body '{
  "nrn": "organization=123:account=456",
  "name": "Environment",
  "order": 1
}'
# This returns a dimension with id, for example: dimension_id = 100

# Step 2: Create values
np dimension value create --dimensionId 100 --body '{
  "nrn": "organization=123:account=456",
  "name": "Production"
}'

np dimension value create --dimensionId 100 --body '{
  "nrn": "organization=123:account=456",
  "name": "Staging"
}'

np dimension value create --dimensionId 100 --body '{
  "nrn": "organization=123:account=456",
  "name": "Development"
}'

Example 2: Region dimension

Create a "Region" dimension for geographic distribution:

# Step 1: Create the dimension
np dimension create --body '{
  "nrn": "organization=123:account=456",
  "name": "Region",
  "order": 2
}'
# This returns dimension_id = 101

# Step 2: Create values
np dimension value create --dimensionId 101 --body '{
  "nrn": "organization=123:account=456",
  "name": "US East"
}'

np dimension value create --dimensionId 101 --body '{
  "nrn": "organization=123:account=456",
  "name": "EU West"
}'

Using dimensions with parameters

Once scopes have dimensions assigned, you can set parameter values at the dimension level:

# Step 1: Create a parameter
np parameter create --body '{
  "nrn": "<application_nrn>",
  "name": "DB_HOST",
  "type": "env"
}'
# This returns parameter_id

# Step 2: Set value for production dimension
np parameter value create --id <parameter_id> --body '{
  "dimension_id": <production_dimension_value_id>,
  "value": "prod-db.example.com"
}'

# Step 3: Set value for staging dimension
np parameter value create --id <parameter_id> --body '{
  "dimension_id": <staging_dimension_value_id>,
  "value": "staging-db.example.com"
}'

Now all scopes with environment=production will get DB_HOST=prod-db.example.com, and all scopes with environment=staging will get DB_HOST=staging-db.example.com.

Important notes

• API uses /dimension/:dimensionId/value endpoints - dimensionId is required in the path
• Dimensions are user-defined - nullplatform doesn't provide default dimensions
• Requires ops permissions - creating/modifying dimensions requires an ops role
• Keep dimensions minimal - too many dimensions hurt developer experience
• Dimension values can be at different NRN levels - flexibility for org structure
• Dimensions work with parameters, approvals, and services - powerful for configuration management
• Cannot have same dimension in parent-child hierarchy - but OK in sibling branches