Examples & Troubleshooting
Practical examples and common troubleshooting scenarios for Backbase
Examples & Troubleshooting
This section provides practical examples and solutions to common issues when working with Backbase.
Complete Examples
E-commerce Product Catalog
Example implementation of a product catalog system.
Entity Definitions
{
"code": "category",
"name": "Product Category",
"description": "Product categorization",
"fields": [
{
"code": "name",
"name": "Category Name",
"fieldType": "TEXT",
"isRequired": true,
"isSearchable": true
},
{
"code": "description",
"name": "Description",
"fieldType": "TEXT",
"isSearchable": true
},
{
"code": "parent",
"name": "Parent Category",
"fieldType": "REFERENCE",
"reference": {
"entityCode": "category",
"displayField": "name"
}
}
]
}
{
"code": "product",
"name": "Product",
"description": "Product catalog item",
"isTranslatable": true,
"isAuditable": true,
"fields": [
{
"code": "name",
"name": "Product Name",
"fieldType": "TEXT",
"isRequired": true,
"isTranslatable": true,
"isSearchable": true
},
{
"code": "description",
"name": "Description",
"fieldType": "TEXT",
"isTranslatable": true,
"isSearchable": true
},
{
"code": "sku",
"name": "SKU",
"fieldType": "TEXT",
"isRequired": true,
"isUnique": true
},
{
"code": "price",
"name": "Price",
"fieldType": "AMOUNT",
"isRequired": true
},
{
"code": "category",
"name": "Category",
"fieldType": "REFERENCE",
"isRequired": true,
"reference": {
"entityCode": "category",
"displayField": "name"
}
},
{
"code": "status",
"name": "Status",
"fieldType": "ENUM",
"isRequired": true,
"defaultValue": "draft",
"enum": {
"values": ["draft", "active", "discontinued"]
}
},
{
"code": "tags",
"name": "Tags",
"fieldType": "TEXT",
"isSearchable": true
},
{
"code": "specifications",
"name": "Technical Specifications",
"fieldType": "OBJECT"
}
]
}Sample Queries
# Get products with category information
query {
productList(
filter: {
status: "active"
price_gte: 100
}
order: { name: ASC }
limit: 10
) {
id
name
sku
price
category {
id
name
}
specifications
}
}
# Search products by text
query {
productList(
filter: {
search: "laptop gaming"
status: "active"
}
) {
id
name
price
tags
}
}
# Get category hierarchy
query {
categoryList {
id
name
parent {
id
name
parent {
id
name
}
}
}
}Customer Management System
Example showing customer and order management.
Entities
{
"code": "customer",
"name": "Customer",
"isAuditable": true,
"fields": [
{
"code": "email",
"name": "Email",
"fieldType": "TEXT",
"isRequired": true,
"isUnique": true
},
{
"code": "firstName",
"name": "First Name",
"fieldType": "TEXT",
"isRequired": true
},
{
"code": "lastName",
"name": "Last Name",
"fieldType": "TEXT",
"isRequired": true
},
{
"code": "phone",
"name": "Phone Number",
"fieldType": "TEXT"
},
{
"code": "status",
"name": "Status",
"fieldType": "ENUM",
"defaultValue": "active",
"enum": {
"values": ["active", "inactive", "suspended"]
}
},
{
"code": "metadata",
"name": "Customer Metadata",
"fieldType": "OBJECT"
}
]
}
{
"code": "order",
"name": "Order",
"isAuditable": true,
"fields": [
{
"code": "orderNumber",
"name": "Order Number",
"fieldType": "TEXT",
"isRequired": true,
"isUnique": true
},
{
"code": "customer",
"name": "Customer",
"fieldType": "REFERENCE",
"isRequired": true,
"reference": {
"entityCode": "customer",
"displayField": "email"
}
},
{
"code": "total",
"name": "Total Amount",
"fieldType": "AMOUNT",
"isRequired": true
},
{
"code": "status",
"name": "Order Status",
"fieldType": "ENUM",
"defaultValue": "pending",
"enum": {
"values": ["pending", "confirmed", "shipped", "delivered", "cancelled"]
}
},
{
"code": "orderDate",
"name": "Order Date",
"fieldType": "DATETIME",
"isRequired": true,
"defaultValue": "{{now}}"
}
]
}Sample Operations
Create customer:
```json
{
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890",
"metadata": {
"source": "website",
"newsletter": true
}
}Create order:
{
"orderNumber": "ORD-2024-001",
"customer": "customer_id",
"total": 299.99,
"status": "pending"
}Get customer with recent orders:
query {
customerList(filter: { status: "active" }) {
id
email
firstName
lastName
orders: orderList(
filter: { customer: "{{id}}" }
order: { orderDate: DESC }
limit: 5
) {
id
orderNumber
total
status
orderDate
}
}
}Troubleshooting Guide
Common Issues
1. GraphQL Schema Not Generated
Problem: After creating entities, the GraphQL schema doesn't include new types.
Solution:
- Ensure the entity is properly saved
- Check application context is correct
- Restart the GraphQL service if needed
Verify entity exists:
```json
{
"entities": [
{
"id": "entity_id",
"code": "product",
"name": "Product",
"fields": [
{ "code": "name", "fieldType": "TEXT" }
]
}
]
}2. Reference Field Validation Errors
Problem: Reference fields fail with "entity not found" errors.
Causes & Solutions:
Check if referenced entity exists:
```json
{
"entities": [
{
"id": "category_entity_id",
"code": "category"
}
]
}Verify reference configuration:
{
"fields": [
{
"code": "category",
"fieldType": "REFERENCE",
"reference": {
"entityCode": "category",
"displayField": "name"
}
}
]
}
#### 3. Unique Constraint Violations
**Problem**: Creating entities fails due to duplicate values.
**Debug Steps**:
```graphql
# Check existing values
query {
productList(filter: { sku: "LAPTOP-001" }) {
id
sku
}
}
Find all unique fields:
```json
{
"fields": [
{
"code": "sku",
"isUnique": true,
"fieldType": "TEXT"
}
]
}4. Translation Issues
Problem: Translated content not appearing correctly.
Solutions:
Verify entity is translatable:
```json
{
"entity": {
"isTranslatable": true,
"fields": [
{
"code": "name",
"isTranslatable": true
}
]
}
}Check language-specific query:
query {
productList(language: "es") {
id
name # Should return Spanish translation
}
}Create product with translations:
{
"name": "English Name",
"translations": {
"es": { "name": "Nombre en Español" },
"fr": { "name": "Nom en Français" }
}
}
#### 5. Permission and Access Issues
**Problem**: Queries fail with permission errors.
**Debug**:
```graphql
Check current user context:
```json
{
"user": {
"id": "user_id",
"permissions": ["read", "write"]
}
}Use anonymous mode if appropriate:
query {
productList # Set anonymous: true in connector
}6. Performance Issues
Problem: Queries are slow with large datasets.
Solutions:
Add appropriate indexes:
```json
{
"entityId": "product_entity_id",
"name": "status_category_index",
"fields": ["status", "category"],
"unique": false
}Use pagination:
query {
productList(
limit: 50
offset: 100
) {
id
name
}
}Request only needed fields:
query {
productList {
id
name
# Don't fetch unnecessary fields
}
}Debugging Tools
Entity Inspection
Entity inspection response:
```json
{
"entities": [
{
"id": "entity_id",
"code": "product",
"name": "Product",
"isTranslatable": true,
"isAuditable": true,
"fields": [
{
"id": "field_id",
"code": "name",
"name": "Product Name",
"fieldType": "TEXT",
"isRequired": true,
"isUnique": false,
"isTranslatable": true
},
{
"id": "field_id_2",
"code": "category",
"name": "Category",
"fieldType": "REFERENCE",
"reference": {
"entityCode": "category",
"displayField": "name"
}
}
],
"indexes": [
{
"id": "index_id",
"name": "name_index",
"fields": ["name"],
"unique": false
}
]
}
]
}Schema Validation
query ValidateSchema {
__schema {
types(includeDeprecated: false) {
name
kind
fields {
name
type {
name
}
}
}
}
}Audit Trail Review
Audit trail response:
```json
{
"auditEntries": [
{
"id": "audit_id",
"operation": "CREATE",
"entityId": "product_entity_id",
"recordId": "product_123",
"changes": {
"name": { "new": "Laptop" },
"price": { "new": 999.99 }
},
"userId": "user_id",
"createdAt": "2024-01-15T10:30:00Z"
}
]
}
### Error Codes Reference
| Code | Description | Solution |
|------|-------------|----------|
| `ENTITY_NOT_FOUND` | Referenced entity doesn't exist | Check entity code and app context |
| `FIELD_VALIDATION_ERROR` | Field value fails validation | Check field type and constraints |
| `UNIQUE_CONSTRAINT_VIOLATION` | Duplicate value for unique field | Use different value or check existing data |
| `REFERENCE_INVALID` | Reference points to non-existent record | Verify referenced record exists |
| `TRANSLATION_ERROR` | Translation operation failed | Check language code and translatable fields |
| `PERMISSION_DENIED` | User lacks required permissions | Verify user roles and entity permissions |
| `SCHEMA_GENERATION_ERROR` | GraphQL schema creation failed | Check entity definitions and restart service |
### Best Practices
1. **Entity Design**
- Use descriptive entity and field codes
- Plan your reference relationships carefully
- Consider translation needs early
- Enable auditing for important entities
2. **Performance**
- Create indexes for frequently queried fields
- Use pagination for large datasets
- Request only necessary fields in queries
- Consider caching for read-heavy operations
3. **Data Integrity**
- Use unique constraints appropriately
- Validate references before creation
- Implement business logic in workflows
- Regular backup and validation checks
4. **Monitoring**
- Monitor query performance
- Track API usage patterns
- Review audit logs regularly
- Set up alerts for errors