Skip to main content

LEGO Developer Documentation

This comprehensive guide covers all available LEGO components and how to use them effectively in your SaaS solution development.

Table of Contents​

LEGO Contribution Guidelines​

Why Contribute a LEGO?​

The LEGO ecosystem thrives on a give and take philosophy. Any LEGO in the marketplace is free of charge and can be reused across projects to speed up development. The ecosystem only survives if:

  • Existing LEGOs are maintained and bug-fixed
  • New "state of the art" reusable LEGOs are added
  • Developers have more choices, reducing development costs further

Bonus: Once you successfully contribute a LEGO, the LEGO team becomes responsible for maintaining and improving it in the future. This means your project is off the hook for maintenance!

Prerequisites for Contribution​

Before contributing, ensure your LEGO meets these criteria:

  1. Reusable and Abstract: Developed as a module that can be used in a wide variety of use cases
  2. Orchestrated: Works with other LEGOs to become more useful and attractive for developers to adopt
  3. Stable and Well-Written: Thoroughly unit tested with proper code and documentation
  4. Example Code: Includes configuration and bootstrap examples for applications

Contribution Steps​

Contributing a LEGO is as easy as any regular Open Source contribution:

  1. Clone the Repository

    git clone https://EA-Sq7-Oceania@dev.azure.com/EA-Sq7-Oceania/Modular-Platform/_git/Modular-Platform

    Note: If you don't have permissions to clone the repository, please contact the LEGO Support Team.

  2. Create a Feature Branch

    git checkout -b feature/my-lego

  3. Add Your LEGO Artifacts:

    • Java source code
    • Unit and integration test code
    • Example project using the LEGO
    • Markdown documentation
    • Changes to the LEGO OpenAPI YAML (when offering REST APIs)

  4. Submit Pull Request

    • Create a PR to the "develop" branch
    • The LEGO team will review and get in touch if needed

1. Tenant Configuration LEGO​

Overview​

The Tenant Configuration LEGO manages tenant-specific properties centrally and allows runtime changes without redeployments or restarts.

Key Features​

  • ✅ Centralized Configuration: Manage tenant-specific properties centrally
  • ✅ Runtime Changes: Modify configurations without redeployments or restarts
  • ✅ Binary Content Support: Store and manage images and other binary content on cloud providers
  • ✅ Event-Driven: Receive events when tenants are created, updated, or deleted
  • ✅ Infrastructure Setup: Enable automatic setup/removal of tenant-specific resources

Configuration​

Minimal Setup​

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-config-core</artifactId>
    <version>${lego.version}</version>
</dependency>

Azure Blob Storage Support​

For storing configuration properties in Azure Blob:

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-config-azureblob</artifactId>
    <version>${lego.version}</version>
</dependency>

Application Properties:

lego:
  config:
    azure:
      blobconnection: ${AZURE_BLOB_CONNECTION_STRING}
      blobContainerId: ${AZURE_CONTAINER_ID}

REST API Support​

For REST API functionality:

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-config-rest</artifactId>
    <version>${lego.version}</version>
</dependency>

Application Properties:

lego:
  api:
    urlBase: /api/1

Tenant Event Handling​

Implement the TenantChangedHandler to respond to tenant lifecycle events. This is useful, if you want to setup tenant specific infrastructure or configure resources that are required by the tenant.

@Component
public class AzureAISearchIndexSetupHandler implements TenantChangedHandler {

    @Override
    public void onCreated(TenantInfo tenant) {
        // Set up a new Azure AI Search Index for the new tenant
        log.info("Setting up resources for tenant: {}", tenant.getId());
        // Your setup logic here
    }
    
    @Override
    public void onChanged(TenantInfo updatedTenant, TenantInfo oldTenantInfo) {
        // Update the AI Search Index if the tenant has changed. 
        log.info("Updating resources for tenant: {}", updatedTenant.getId());
        // Your update logic here
    }
    
    @Override
    public void onRemoved(TenantInfo removedTenant) {
        // Remove the Azure AI Search Index for the tenant in order to avoid unnecessary costs
        log.info("Cleaning up resources for tenant: {}", removedTenant.getId());
        // Your cleanup logic here
    }
}

Programmatic Tenant Management​

Create, update, and delete tenants programmatically:

import com.bosch.bd.lego.api.tenant.TenantService;
import com.bosch.bd.lego.api.tenant.TenantInfo;
import com.bosch.bd.lego.api.common.I18NText;

@Service
public class TenantManagementService {
    
    @Autowired
    private TenantService tenantService;
    
    public void createTenant(String tenantId, String name, String description) {
        TenantInfo tenant = TenantInfo.builder()
            .id(tenantId)
            .name(I18NText.builder().en(name).build())
            .description(I18NText.builder().en(description).build())
            .owningEntity("PS/EBT")
            .build();
            
        tenantService.createOrUpdate(tenant);
    }
    
    public List<TenantInfo> getAllTenants() {
        return tenantService.getAllTenants();
    }
}

Creating a new simple tenant via REST​

{
  "id": "(solutionId)-saas-(customerId)",
  "name": {
    "en": "Some cool name for the tenant"
  },
  "description": {
    "en": "Some cool description for the tenant"
  },
  "owningEntity": "BD",
  "supportEmail": "saravanan.natarajan2@bosch.com",
  "legos": []
 }

For more details, check the REST API documentation.

2. SSO LEGO​

Overview​

The SSO (Single Sign-On) LEGO provides comprehensive identity and access management using Keycloak.

Key Features​

  • 🔐 API Security: Secures REST API endpoints with JWT-based authentication
  • 👤 User Profile API: Provides user security context with basic and application-specific attributes
  • 👥 User Management: Invite users to applications with specific roles
  • 🔍 User Search: Search and manage users with access to applications
  • 🏢 Tenant Isolation: Multi-tenant user and role management

Configuration​

Minimal Setup​

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-sso-spring-security</artifactId>
    <version>${lego.version}</version>
</dependency>
<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-sso-keycloak</artifactId>
    <version>${lego.version}</version>
</dependency>

Application Properties​

spring:
  security:
    resourceserver:
      jwt:
        issuers:
          - https://p61.authz.bosch.com/auth/realms/myrealm
          
lego:
  sso:
    cors:
      allowedOrigins: 
    identity:

API Examples​

Get Current User Profile​

curl -X GET "https://your-app.com/api/1/legos/sso/identities/users/me" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

List All Users in Tenant​

curl -X GET "https://your-app.com/api/1/legos/sso/identities/users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create User Invitation​

curl -X PUT "https://your-app.com/api/1/legos/sso/invitations" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "roles": ["APPLICATION_USER"],
    "message": "Welcome to our platform!"
  }'

Configuring the SSO Lego via JSON​

{
	"type": "sso",
   "id": "my-sso",
   "enabled": true,
   "externalRoleMgmtEnabled": false,
   "invitationExpiryInDays": 3,
   "invitationSubject": "Invitation to our cool Solution"
}

3. Workflow LEGO​

Overview​

The Workflow LEGO enables you to create approval workflows and state machines, modeling business logic that can be easily adapted to different customer/tenant needs.

Key Features​

  • 🔄 Approval Workflows: Create human approval workflows
  • 🎯 State Machines: Implement pure state machines for business logic
  • 🏢 Multi-tenant: Adapt workflows to different customer/tenant needs
  • 📊 Workflow Management: Track and manage workflow instances
  • 🔧 Customizable: Define custom fields and business rules

Configuration​

Dependencies​

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-workflow-all</artifactId>
    <version>${lego.version}</version>
</dependency>
<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-workflow-rest</artifactId>
    <version>${lego.version}</version>
</dependency>

API Examples​

Create New Workflow​

curl -X POST "https://your-app.com/api/1/legos/workflows" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legoId": "lego-workflow",
    "customFields": {
      "requestType": "approval",
      "priority": "high",
      "description": "Budget approval request"
    }
  }'

Search Todo Workflows​

curl -X GET "https://your-app.com/api/1/legos/workflows/search/todo?pageIndex=0&pageSize=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Customizing Workflows​

Workflows can be customized with custom fields and business rules to match your specific requirements.

Configuring the Workflow Lego via JSON​

{
      "type": "workflow",
      "id": "myworkflow",
      "enabled": true,
      "workflow": {
        "uri": "Workflow Name as specified in the workflow XML, i.e. HolidayApproval",
        "content": {
          "type": "external",
          "path": "path/to/workflow.xml",
          "binary": false,
          "type": "external"
        }
      },
      "searchFilters": [
        {
          "key": "workflowTypes",
          "label": {
            "en": "Workflow Types",
            "de": null
          },
          "scope": "workflowname",
          "type": "CHOICE",
          "choices": [
            "Holiday Approval",
            "Medical Approval"
          ]
        },
        {
          "key": "completed",
          "label": {
            "en": "Completed Workflows",
            "de": "Beendete Workflows"
          },
          "scope" : "workflowcompleted"
        },
        {
          "customFieldKey": "lastname",
          "variable": false,
          "operator": "like",
          "key": "associate",
          "label": {
            "en": "Associate Lastname",
            "de": "Mitarbeiter Nachname"
          },
          "scope": "customfield",
          "type" : "TEXTINPUT"
        }
      ],
      "requestDefinition": {
        "allowedRoles": [
          "SD_USER"
        ],
        "label": {
          "en": "Apply Leave",
          "de": null
        }
      },
      "fieldDefinitions": [
        {
          "key": "remarks",
          "label": {
            "en": "Remarks",
            "de": null
          },
          "description": null,
          "editable": false,
          "showInInbox": false,
          "showIfExpression": "true",
          "maxValues": 1,
          "showInDetails": true,
          "expression": null,
          "type": "TEXT",
          "horizontalHeaders": [],
          "verticalHeaders": [],
          "choices": [],
          "required": false,
          "inputField": true,
          "variable": true
        },
        {
          "key": "notifyMe",
          "label": {
            "en": "Notify me once approved or rejected",
            "de": null
          },
          "description": null,
          "editable": false,
          "showInInbox": false,
          "showIfExpression": "true",
          "maxValues": 1,
          "showInDetails": false,
          "expression": null,
          "type": "CHECKBOX",
          "horizontalHeaders": [],
          "verticalHeaders": [],
          "choices": [],
          "required": false,
          "inputField": true,
          "variable": true
        },
        {
          "key": "startDate",
          "label": {
            "en": "Start Date",
            "de": null
          },
          "description": null,
          "editable": false,
          "showInInbox": false,
          "showIfExpression": "true",
          "maxValues": 1,
          "showInDetails": true,
          "expression": null,
          "type": "DATE",
          "horizontalHeaders": [],
          "verticalHeaders": [],
          "choices": [],
          "required": true,
          "inputField": true,
          "variable": true
        },
        {
          "key": "endDate",
          "label": {
            "en": "End Date",
            "de": null
          },
          "description": null,
          "editable": false,
          "showInInbox": false,
          "showIfExpression": "true",
          "maxValues": 1,
          "showInDetails": true,
          "expression": null,
          "type": "DATE",
          "horizontalHeaders": [],
          "verticalHeaders": [],
          "choices": [],
          "required": true,
          "inputField": true,
          "variable": true
        },
        {
          "key": "leaveType",
          "label": {
            "en": "Leave Type",
            "de": null
          },
          "description": null,
          "editable": false,
          "showInInbox": true,
          "showIfExpression": "true",
          "maxValues": 1,
          "showInDetails": true,
          "expression": null,
          "type": "CHOICE",
          "horizontalHeaders": [],
          "verticalHeaders": [],
          "choices": [
            {
              "label": {
                "en": "Annual",
                "de": null
              },
              "value": "Annual"
            },
            {
              "label": {
                "en": "Medical",
                "de": null
              },
              "value": "Medical"
            }
          ],
          "required": true,
          "inputField": true,
          "variable": true
        }    
  }

4. Data Ingestion LEGO​

Overview​

The Data Ingestion LEGO allows external clients to securely send data to your solution for further processing.

Key Features​

  • 🔑 API Key Management: Issue API keys to third-party systems
  • 📨 Message Processing: Process received messages securely
  • 🔌 HTTP Adapter: Receive messages via HTTP
  • 🔄 Workflow Router: Start workflows for incoming messages
  • 🛡️ Security: Secure data transmission

Configuration​

Basic Dependencies​

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-dataingestion-rest</artifactId>
    <version>${lego.version}</version>
</dependency>
<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-dataingestion-adapter-http</artifactId>
    <version>${lego.version}</version>
</dependency>

Routers​

Workflow Router​
<dependency>
   <groupId>com.bosch.bd.lego</groupId>
   <artifactId>lego-dataingestion-router-workflow</artifactId>
   <version>${lego.version}</version>
</dependency>
InfluxDB Router​
<dependency>
   <groupId>com.bosch.bd.lego</groupId>
   <artifactId>lego-dataingestion-router-influxdb</artifactId>
   <version>${lego.version}</version>
</dependency>

Configurating Data Ingestion Lego via JSON​

{
	"id" : "liftmanager-gateway",
	"apiKeyValidityInMonths" : 12,
   "type" : "dataingestion",
	"router" : { // routes data automatically to InfluxDB and converting it to Vorto standardized data structure
		"retentionTimeInDays" : 90,
		"key" : "influx",
    	"type" : "influx",
		"mappingSpecification" : {
			"path" : "mappings/mappingspec.json",
			"binary" : false,
			"type" : "external"
		}
	},
	"enabled" : true
}

5. Usage LEGO​

Overview​

The Usage LEGO defines solution usage and cost profiles, enabling your SaaS solution to track data usage and costs per tenant.

Key Features​

  • 📊 Usage Monitoring: Track API calls and workflow instances
  • 💰 Cost Calculation: Automatically calculate costs per tenant
  • 📈 Usage Analytics: Monitor usage patterns and trends
  • 🏢 Multi-tenant Billing: Separate billing per tenant

Configuration​

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-usage-core</artifactId>
    <version>${lego.version}</version>
</dependency>
<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-usage-rest</artifactId>
    <version>${lego.version}</version>
</dependency>

Configurating Usage Lego via JSON​

{
      "type": "usage",
      "id": "myusage",
      "enabled": true,
      "metrics": [
        {
          "metric": "API_CALLS",
          "costPerUnit": 0.3,
          "unit": "EUR"
        },
        {
          "metric": "TIMESERIES_DATA_STORAGE_MB",
          "costPerUnit": 0.5,
          "unit": "EUR"
        },
        {
          "metric": "USERS_MANAGED",
          "costPerUnit": 0.15,
          "unit": "EUR"
        },
        {
          "metric": "EMAILS_SENT",
          "costPerUnit": 0.15,
          "unit": "EUR"
        },
        {
          "metric": "DOCUMENTS_MANAGED",
          "costPerUnit": 0.15,
          "unit": "EUR"
        },
        {
          "metric": "DOCUMENTS_STORAGE_MB",
          "costPerUnit": 0.15,
          "unit": "EUR"
        },
        {
          "metric": "AI_TOKENS_CONSUMED",
          "costPerUnit": 0.15,
          "unit": "EUR"
        },
        {
          "metric": "WORKFLOW_INSTANCES",
          "costPerUnit": 0.15,
          "unit": "EUR"
        }
      ]
    }

6. Application Info LEGO​

Overview​

The Application Info LEGO manages warnings and general information about your application, notifying users about events without requiring redeployment.

Key Features​

  • 📢 User Notifications: Inform users about application events
  • 🔄 Runtime Updates: Update information without redeployment
  • ⚠️ Warning System: Display warnings and maintenance notices
  • 📝 Release Notes: Share new features and updates

API Examples​

Update Application Info​

curl -X PUT "https://your-app.com/api/1/legos/appinfo" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "warnings": [
      {
        "id": "maintenance-notice",
        "title": {
          "en": "Scheduled Maintenance"
        },
        "message": {
          "en": "System will be unavailable on Sunday from 2-4 AM"
        },
        "severity": "WARNING",
        "active": true
      }
    ],
    "generalInfo": [
      {
        "id": "new-feature",
        "title": {
          "en": "New Feature Available"
        },
        "message": {
          "en": "Document search functionality is now available!"
        },
        "active": true
      }
    ]
  }'

7. Notification LEGO​

Overview​

The Notification LEGO allows your solution to notify users via different channels, primarily email.

Key Features​

  • 📧 Email Notifications: Send emails via SMTP or Bosch TMS Mailjet
  • 🎯 Targeted Notifications: Send notifications to specific users or groups
  • 📝 Template Support: Use templates for consistent messaging
  • 📊 Delivery Tracking: Track notification delivery status

Configuration​

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-notification-core</artifactId>
    <version>${lego.version}</version>
</dependency>
<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-notification-email</artifactId>
    <version>${lego.version}</version>
</dependency>

8. AI Chatbot LEGO​

Overview​

The AI Chatbot LEGO enables integration with AI models like OpenAI GPT to provide human-like responses and data search capabilities.

Key Features​

  • 🤖 AI Integration: Connect with OpenAI GPT and other AI models
  • 🔍 Data Search: Search through your data with natural language
  • 💬 Human-like Responses: Generate conversational responses
  • 🧠 Context Awareness: Maintain conversation context

Configuration​

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-ai-chatbot</artifactId>
    <version>${lego.version}</version>
</dependency>

9. Document Manager LEGO​

Overview​

The Document Manager LEGO provides comprehensive document management capabilities including upload, search, and download functionality.

Key Features​

  • 📤 Document Upload: Upload various document types
  • 🔍 Advanced Search: Search by metadata and free-text
  • 📥 Document Download: Download documents securely
  • 🏷️ Metadata Management: Add and search by document metadata
  • 📊 Document Analytics: Track document usage and access

Configuration​

<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-docmanager-core</artifactId>
    <version>${lego.version}</version>
</dependency>
<dependency>
    <groupId>com.bosch.bd.lego</groupId>
    <artifactId>lego-docmanager-rest</artifactId>
    <version>${lego.version}</version>
</dependency>

API Examples​

Upload Documents​

curl -X POST "https://your-app.com/api/1/legos/docmanager/documents" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "files=@document.pdf"

Search Documents​

curl -X PUT "https://your-app.com/api/1/legos/docmanager/documents" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "invoice",
    "filters": {
      "documentType": "invoice",
      "dateRange": {
        "from": "2024-01-01",
        "to": "2024-12-31"
      }
    },
    "pageIndex": 0,
    "pageSize": 20
  }'

Download Document​

curl -X GET "https://your-app.com/api/1/legos/docmanager/documents/download?uri=document-uri" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --output downloaded-document.pdf

Getting Help​

For questions, issues, or contributions: