Working with Business Areas

This guide explains how to work with business areas in Pretectum using the API. You will learn how to retrieve the business areas your application has access to and use them effectively in your data operations.

Overview

Business areas are the top-level organizational units in Pretectum that categorize your master data. They provide a logical structure for organizing different types of data within your organization:

Customer: Customer records, contacts, and related data
Product: Product catalog, inventory, and specifications
Supplier: Vendor and supplier information
Employee: Human resources and personnel data

Each business area contains schemas (data structures) and datasets (collections of records) that further organize your data.

Why Business Areas Matter

Understanding your business areas is essential for:

Scoped Searches: Filter search results to specific data categories
Access Control: Different applications may have access to different business areas
Data Organization: Understand the structure of your master data
Performance: Searching within a specific business area is faster than searching across all data

Before You Begin

To use the Business Areas API, you need:

Create an API Key

In the Pretectum app, go to Configuration → API Keys and create a key. It is shown once, at creation, so copy it then. See API Keys.

Verify Permissions

Ensure your application client has been granted access to the business areas permission.

Retrieving Business Areas

Use the List Business Areas endpoint to get all business areas your application can access.

Basic Request

curl -X GET "https://api.pretectum.io/v1/my/businessareas" \
  -H "Authorization: pre_your_api_key" \
  -H "Accept: application/json"

async function getBusinessAreas(apiKey) {
  const response = await fetch('https://api.pretectum.io/v1/my/businessareas', {
    headers: {
      'Authorization': apiKey,
      'Accept': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch business areas: ${response.statusText}`);
  }

  return response.json();
}

// Usage
const apiKey = 'pre_your_api_key';
const businessAreas = await getBusinessAreas(apiKey);
console.log('Available business areas:', businessAreas);

import requests

def get_business_areas(api_key):
    response = requests.get(
        'https://api.pretectum.io/v1/my/businessareas',
        headers={
            'Authorization': api_key,
            'Accept': 'application/json'
        }
    )
    response.raise_for_status()
    return response.json()

# Usage
api_key = 'pre_your_api_key'
business_areas = get_business_areas(api_key)
print('Available business areas:', business_areas)

Understanding the Response

The API returns an array of business area objects:

[
  {
    "businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
    "name": "Customer",
    "description": "Customer master data including individuals and businesses",
    "active": true,
    "createdBy": "admin",
    "updatedBy": "admin",
    "createdDate": "2024-01-15T10:30:00Z",
    "updatedDate": "2024-06-01T14:22:00Z",
    "version": 3
  },
  {
    "businessAreaId": "20240115103500456b2c3d4e5f67890123456789012345",
    "name": "Product",
    "description": "Product catalog and inventory master data",
    "active": true,
    "createdBy": "admin",
    "updatedBy": "product_manager",
    "createdDate": "2024-01-15T10:35:00Z",
    "updatedDate": "2024-08-15T09:45:00Z",
    "version": 5
  }
]

Field	Description
`businessAreaId`	Unique identifier for the business area
`name`	Display name used for filtering in search operations
`description`	Explanation of the business area’s purpose
`active`	Whether the business area is currently active
`createdBy`	User who created the business area
`updatedBy`	User who last modified the business area
`createdDate`	When the business area was created
`updatedDate`	When the business area was last modified
`version`	Version number for tracking changes

Using Business Areas for Search

Once you have the list of business areas, use the name field to filter your data object searches.

Searching Within a Business Area

# Get business areas
curl -X GET "https://api.pretectum.io/v1/my/businessareas" \
  -H "Authorization: pre_your_api_key"

# Search within the "Customer" business area
curl -X GET "https://api.pretectum.io/v1/dataobjects/search?query=John&businessArea=Customer" \
  -H "Authorization: pre_your_api_key"

async function searchInBusinessArea(apiKey, query, businessAreaName) {
  const params = new URLSearchParams({
    query: query,
    businessArea: businessAreaName
  });

  const response = await fetch(
    `https://api.pretectum.io/v1/dataobjects/search?${params}`,
    {
      headers: { 'Authorization': apiKey }
    }
  );

  return response.json();
}

// Search for "John" in the Customer business area
const results = await searchInBusinessArea(apiKey, 'John', 'Customer');
console.log(`Found ${results.total} customers matching "John"`);

def search_in_business_area(api_key, query, business_area_name):
    response = requests.get(
        'https://api.pretectum.io/v1/dataobjects/search',
        params={
            'query': query,
            'businessArea': business_area_name
        },
        headers={'Authorization': api_key}
    )
    response.raise_for_status()
    return response.json()

# Search for "John" in the Customer business area
results = search_in_business_area(api_key, 'John', 'Customer')
print(f"Found {results['total']} customers matching 'John'")

Complete Client Implementation

Here is a complete implementation that handles authentication, business area retrieval, and searching:

const API_BASE = 'https://api.pretectum.io';

class PretectumClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.businessAreas = null;
  }

  async getBusinessAreas(forceRefresh = false) {
    if (this.businessAreas && !forceRefresh) {
      return this.businessAreas;
    }

    const response = await fetch(`${API_BASE}/v1/my/businessareas`, {
      headers: {
        'Authorization': this.apiKey,
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch business areas: ${response.statusText}`);
    }

    this.businessAreas = await response.json();
    return this.businessAreas;
  }

  async getActiveBusinessAreas() {
    const areas = await this.getBusinessAreas();
    return areas.filter(area => area.active);
  }

  async getBusinessAreaNames() {
    const areas = await this.getActiveBusinessAreas();
    return areas.map(area => area.name);
  }

  async hasAccessTo(businessAreaName) {
    const areas = await this.getBusinessAreas();
    return areas.some(
      area => area.name === businessAreaName && area.active
    );
  }

  async search(query, options = {}) {
    // Validate business area if provided
    if (options.businessArea) {
      const hasAccess = await this.hasAccessTo(options.businessArea);
      if (!hasAccess) {
        throw new Error(`No access to business area: ${options.businessArea}`);
      }
    }

    const params = new URLSearchParams({ query, ...options });
    const response = await fetch(
      `${API_BASE}/dataobjects/search?${params}`,
      {
        headers: { 'Authorization': this.apiKey }
      }
    );

    if (!response.ok) {
      throw new Error(`Search failed: ${response.statusText}`);
    }

    return response.json();
  }

  async searchAllBusinessAreas(query, options = {}) {
    const areas = await this.getActiveBusinessAreas();
    const results = {};

    for (const area of areas) {
      const searchResults = await this.search(query, {
        ...options,
        businessArea: area.name
      });
      results[area.name] = searchResults;
    }

    return results;
  }
}

// Usage
const client = new PretectumClient(process.env.PRETECTUM_API_KEY);

// Get available business areas
const businessAreas = await client.getBusinessAreas();
console.log('Available business areas:');
businessAreas.forEach(area => {
  console.log(`  - ${area.name}: ${area.description}`);
});

// Get just the names for a dropdown
const areaNames = await client.getBusinessAreaNames();
console.log('Business area names:', areaNames);

// Search within a specific business area
const results = await client.search('John', { businessArea: 'Customer' });
console.log(`Found ${results.total} customers`);

// Search across all business areas
const allResults = await client.searchAllBusinessAreas('Smith');
for (const [areaName, data] of Object.entries(allResults)) {
  console.log(`${areaName}: ${data.total} results`);
}

import os
import requests
from typing import Optional, Dict, List, Any

class PretectumClient:
    API_BASE = 'https://api.pretectum.io'

    def __init__(self, api_key: str):
        self.api_key = api_key
        self._business_areas: Optional[List[Dict]] = None

    def get_business_areas(self, force_refresh: bool = False) -> List[Dict]:
        if self._business_areas and not force_refresh:
            return self._business_areas

        response = requests.get(
            f'{self.API_BASE}/v1/my/businessareas',
            headers={
                'Authorization': self.api_key,
                'Accept': 'application/json'
            }
        )
        response.raise_for_status()

        self._business_areas = response.json()
        return self._business_areas

    def get_active_business_areas(self) -> List[Dict]:
        areas = self.get_business_areas()
        return [area for area in areas if area.get('active', False)]

    def get_business_area_names(self) -> List[str]:
        areas = self.get_active_business_areas()
        return [area['name'] for area in areas]

    def has_access_to(self, business_area_name: str) -> bool:
        areas = self.get_business_areas()
        return any(
            area['name'] == business_area_name and area.get('active', False)
            for area in areas
        )

    def search(self, query: str, **options) -> Dict[str, Any]:
        # Validate business area if provided
        if 'businessArea' in options:
            if not self.has_access_to(options['businessArea']):
                raise ValueError(f"No access to business area: {options['businessArea']}")

        params = {'query': query, **options}
        response = requests.get(
            f'{self.API_BASE}/dataobjects/search',
            params=params,
            headers={'Authorization': self.api_key}
        )
        response.raise_for_status()

        return response.json()

    def search_all_business_areas(self, query: str, **options) -> Dict[str, Dict]:
        areas = self.get_active_business_areas()
        results = {}

        for area in areas:
            search_results = self.search(query, businessArea=area['name'], **options)
            results[area['name']] = search_results

        return results


# Usage
client = PretectumClient(os.environ['PRETECTUM_API_KEY'])

# Get available business areas
business_areas = client.get_business_areas()
print('Available business areas:')
for area in business_areas:
    print(f"  - {area['name']}: {area['description']}")

# Get just the names for a dropdown
area_names = client.get_business_area_names()
print('Business area names:', area_names)

# Search within a specific business area
results = client.search('John', businessArea='Customer')
print(f"Found {results['total']} customers")

# Search across all business areas
all_results = client.search_all_business_areas('Smith')
for area_name, data in all_results.items():
    print(f"{area_name}: {data['total']} results")

Building a Business Area Selector

Create a user interface component that lets users select a business area for filtering:

import { useState, useEffect } from 'react';

function BusinessAreaSelector({ client, onSelect }) {
  const [businessAreas, setBusinessAreas] = useState([]);
  const [selected, setSelected] = useState('all');
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadBusinessAreas() {
      try {
        const areas = await client.getActiveBusinessAreas();
        setBusinessAreas(areas);
      } catch (error) {
        console.error('Failed to load business areas:', error);
      } finally {
        setLoading(false);
      }
    }
    loadBusinessAreas();
  }, [client]);

  const handleChange = (event) => {
    const value = event.target.value;
    setSelected(value);
    onSelect(value === 'all' ? null : value);
  };

  if (loading) return <span>Loading...</span>;

  return (
    <select value={selected} onChange={handleChange}>
      <option value="all">All Business Areas</option>
      {businessAreas.map(area => (
        <option key={area.businessAreaId} value={area.name}>
          {area.name}
        </option>
      ))}
    </select>
  );
}

import os

from flask import Flask, render_template, jsonify

app = Flask(__name__)
client = PretectumClient(os.environ['PRETECTUM_API_KEY'])

@app.route('/api/business-areas')
def get_business_areas():
    """API endpoint to get business areas for frontend dropdown."""
    try:
        areas = client.get_active_business_areas()
        return jsonify([
            {
                'id': area['businessAreaId'],
                'name': area['name'],
                'description': area['description']
            }
            for area in areas
        ])
    except Exception as e:
        return jsonify({'error': str(e)}), 500

@app.route('/api/search')
def search():
    """Search endpoint that accepts business area filter."""
    from flask import request

    query = request.args.get('query', '')
    business_area = request.args.get('businessArea')

    try:
        options = {}
        if business_area and business_area != 'all':
            options['businessArea'] = business_area

        results = client.search(query, **options)
        return jsonify(results)
    except Exception as e:
        return jsonify({'error': str(e)}), 500

Error Handling

Handle common errors when working with business areas:

async function safeGetBusinessAreas(client) {
  try {
    return await client.getBusinessAreas();
  } catch (error) {
    if (error.message.includes('401')) {
      // Token expired, re-authenticate and retry
      await client.authenticate();
      return await client.getBusinessAreas();
    }
    if (error.message.includes('403')) {
      console.error('No permission to access business areas');
      return [];
    }
    throw error;
  }
}

def safe_get_business_areas(client):
    try:
        return client.get_business_areas()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            # Token expired, re-authenticate and retry
            client.authenticate()
            return client.get_business_areas()
        elif e.response.status_code == 403:
            print('No permission to access business areas')
            return []
        raise

Best Practices

Cache Business Areas

Business areas change infrequently. Cache the response locally and refresh periodically rather than fetching on every request:

// Refresh every 5 minutes
const CACHE_TTL = 5 * 60 * 1000;
let cachedAt = 0;

async function getCachedBusinessAreas() {
  if (Date.now() - cachedAt > CACHE_TTL) {
    await client.getBusinessAreas(true);
    cachedAt = Date.now();
  }
  return client.businessAreas;
}

Filter by Active Status

Only show active business areas in user-facing interfaces:

active_areas = [
    area for area in business_areas
    if area.get('active', False)
]

Validate Before Search

Validate that the user has access to a business area before attempting to search:

if (businessArea && !await client.hasAccessTo(businessArea)) {
  throw new Error('Access denied to this business area');
}

Use Names, Not IDs

When filtering searches, use the name field, not the businessAreaId:

# Correct - use name
?businessArea=Customer

# Incorrect - don't use ID
?businessArea=20240115103000123a1b2c3d4e5f6789012345678901234

Next Steps

API Reference

View the complete Business Areas API reference

Search Data Objects

Learn how to search within business areas

Authentication

Create and manage the keys that authenticate your calls

Search API Reference

Complete search API documentation

Getting Started

Business Areas

Schemas

Datasets

Data Objects

AI Tools

Working with Business Areas

Overview

Why Business Areas Matter

Before You Begin

Retrieving Business Areas

Basic Request

Understanding the Response

Using Business Areas for Search

Searching Within a Business Area

Complete Client Implementation

Building a Business Area Selector

Error Handling

Best Practices

Next Steps

API Reference

Search Data Objects

Authentication

Search API Reference

​Overview

​Why Business Areas Matter

​Before You Begin

​Retrieving Business Areas

​Basic Request

​Understanding the Response

​Using Business Areas for Search

​Searching Within a Business Area

​Complete Client Implementation

​Building a Business Area Selector

​Error Handling

​Best Practices

​Next Steps

API Reference

Search Data Objects

Authentication

Search API Reference

Overview

Why Business Areas Matter

Before You Begin

Retrieving Business Areas

Basic Request

Understanding the Response

Using Business Areas for Search

Searching Within a Business Area

Complete Client Implementation

Building a Business Area Selector

Error Handling

Best Practices

Next Steps