Overview

System Prototypes are a preliminary version of a system, serving as a proof of concept or a model for further development.

Overview

System Prototypes provide a standardized way to:

• Define the structure of your data systems
• Configure default settings and parameters
• Establish best practices for system development

Enabling System Prototypes

Before you can use System Prototypes, you need to enable them in your platform configuration. This involves updating your YAML configuration and setting up appropriate permissions.

YAML Configuration

Add the following configuration to your app-config.yaml file to enable System Prototypes:

builder:
  ui:
    prototypePage:
      enabled: true

Permissions

In order to view the "Backlog" section, assign the permission builder.system-prototype.edit to one of the roles

System Prototype Template

You have to define a template for a System Prototype. Check System Prototypes templates for more information.

System Prototype Type

You have to define a type for a System Prototype, so it will be available in the practice shape. Check System Prototypes type for more information.

Key Components

Parameters Structure

Parameters can be defined with the following properties:

Property	Description	Required	Type	Default
name	Parameter name	Yes	string	-
type	Data type of the parameter	Yes	'string', 'number', 'boolean', 'object', or 'array'	-
description	Description of the parameter	No	string	-
default	Default value for the parameter	No	any	-
required	Whether the parameter is required	No	boolean	false

Troubleshooting

Error	Cause	Solution
Duplicate Name Error	A prototype with the same name already exists in the platform	Choose a different, unique name for your prototype
Catalog Sync Issues	The entity provider is not running or the refresh endpoint is not responding	Verify the entity provider status and check the refresh endpoint
Parameter Validation Error	Required parameters are missing or have incorrect types	Ensure all required parameters are provided and match their defined types
Template Not Found	The specified template does not exist or is not accessible	Verify the template name and ensure you have access to it
Invalid Prototype Type	The specified prototype type is not recognized	Check the prototype type name and ensure it exists in the platform
Permission Denied	Insufficient permissions to perform the operation	Verify your access rights and contact your administrator if needed

API Operations

Get System Prototypes

GET /api/v2/system-prototypes

Retrieves all system prototypes with optional filtering.

Query Parameters:

• resourceTypeId (optional): Filter by resource type ID (array)
• taxonomyRef (optional): Filter by taxonomy reference (array)

Response: 200 OK

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "domain": "string",
      "owner": "string",
      "status": "string",
      "systemPrototypeType": "string"
    }
  ],
  "total": "number"
}

Delete System Prototype

DELETE /api/v2/system-prototypes/{name}

Removes a system prototype by name.

Path Parameters:

• name: The name of the system prototype to delete

Response: 204 No Content

Create Business Concept

POST /api/system_prototype/business_concepts

Creates a new business concept in the system.

Headers:

• Content-Type: application/json
• Authorization: Bearer <token>

Request Body:

{
  "name": "string",
  "domain": "string"
}

Response: 201 Created

{
  "id": "string",
  "name": "string",
  "status": "CREATED"
}

Create Success Metric

POST /api/system_prototype/success_metrics

Creates a new success metric in the system.

Headers:

• Content-Type: application/json
• Authorization: Bearer <token>

Request Body:

{
  "name": "string",
  "description": "string"
}

Response: 201 Created

{
  "id": "string",
  "name": "string",
  "status": "CREATED"
}

Create Key Result

POST /api/system_prototype/key_results

Creates a new key result in the system.

Headers:

• Content-Type: application/json
• Authorization: Bearer <token>

Request Body:

{
  "name": "string",
  "description": "string"
}

Response: 201 Created

{
  "id": "string",
  "name": "string",
  "status": "CREATED"
}

Additional notes:

1. All endpoints require authentication via Bearer token
2. After create/update/delete operations, the system automatically triggers a catalog refresh
3. The system handles duplicate name errors with a 409 Conflict response
4. The database schema matches the documentation's structure
5. The API is integrated with the Backstage Catalog through the `SystemPrototypeEntityProvider

Error Handling

The system handles various error conditions:

1. Duplicate Names: Prevents creation of prototypes with existing names
2. Invalid Parameters: Validates parameter types and requirements
3. Database Constraints: Handles database-level unique constraint violations

Security

• All API operations require authentication
• Token-based authentication is used for API requests
• Access control is enforced at the API level