{ "openapi": "3.0.0", "paths": { "/status": { "get": { "description": "Retrieves the current health status of the application including uptime and timestamp", "operationId": "AppController_status", "parameters": [], "responses": { "200": { "description": "Health check passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckDto" } } } }, "500": { "description": "Health check failed" } }, "summary": "Check application health status", "tags": [ "Health" ] } }, "/task": { "post": { "description": "Creates a new data synchronization task and starts processing it asynchronously", "operationId": "TaskController_createTask", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigDto" } } } }, "responses": { "201": { "description": "Task created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaskResponseDto" } } } }, "400": { "description": "Invalid request data" }, "500": { "description": "Error creating task" } }, "summary": "Create a new data sync task", "tags": [ "Task" ] } }, "/task/{id}": { "get": { "description": "Retrieves the status of a specific task by its ID", "operationId": "TaskController_getTaskStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The ID of the task whose status should be queried", "schema": { "example": "27e0c243-e736-42d9-8f7b-4c988c0fa4f0", "type": "string" } } ], "responses": { "200": { "description": "Task status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusDto" } } } }, "404": { "description": "Task not found" }, "500": { "description": "Error retrieving task status" } }, "summary": "Check task status", "tags": [ "Task" ] } }, "/task/cleanupLogs": { "post": { "description": "Cleans up log entries from completed tasks based on the specified retention settings", "operationId": "TaskController_cleanupLogs", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CleanupLogsTypeDto" } } } }, "responses": { "200": { "description": "Task logs cleaned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CleanupLogsResultDto" } } } }, "500": { "description": "Error cleaning up logs" } }, "summary": "Cleanup task logs", "tags": [ "Task" ] } } }, "info": { "title": "SAP Public Cloud Connector", "description": "With this connector, you can sync data between SAP and database systems", "version": "1.0", "contact": { "name": "Contact us - One Unity GmbH", "url": "https://one-unity.de", "email": "info@one-unity.de" }, "license": { "name": "Closed source licensed", "url": "https://one-unity.de/license" } }, "tags": [], "servers": [ { "url": "http://localhost:3000", "description": "Local development server" } ], "components": { "securitySchemes": { "basic": { "type": "http", "scheme": "basic", "description": "Basic authentication", "name": "Authorization", "in": "header" } }, "schemas": { "HealthCheckDto": { "type": "object", "properties": { "status": { "type": "string", "description": "Current status of the system", "example": "ok", "enum": [ "ok" ] }, "uptime": { "type": "number", "description": "Time in seconds that the system has been running since the last start", "minimum": 0, "example": 141.599348343 }, "timestamp": { "type": "string", "description": "Timestamp of the status query in ISO 8601 format (UTC)", "format": "date-time", "example": "2025-03-07T15:14:57.060Z" } }, "required": [ "status", "uptime", "timestamp" ] }, "ServerDatabasePoolOptionsDto": { "type": "object", "properties": { "max": { "type": "number", "description": "Maximum number of simultaneous open connections in the pool", "example": 10 }, "min": { "type": "number", "description": "Minimum number of connections maintained in the pool", "example": 1 }, "idleTimeoutMillis": { "type": "number", "description": "Time in milliseconds after which an inactive connection is removed from the pool", "example": 30000 } } }, "ServerDatabaseConnectionOptionsDto": { "type": "object", "properties": { "encrypt": { "type": "boolean", "description": "Boolean value indicating whether the connection should be encrypted", "default": true, "example": true }, "enableArithAbort": { "type": "boolean", "description": "Determines whether the query should be aborted on arithmetic errors (e.g., division by zero)", "default": true, "example": true }, "trustServerCertificate": { "type": "boolean", "description": "When true, the server certificate is accepted without verification. This can be useful in test environments", "default": false, "example": false }, "connectionTimeout": { "type": "number", "description": "Maximum time in milliseconds to attempt establishing a connection before it times out", "example": 30000 }, "requestTimeout": { "type": "number", "description": "Maximum time in milliseconds to wait for query execution", "example": 30000 }, "pool": { "description": "Connection pool settings", "allOf": [ { "$ref": "#/components/schemas/ServerDatabasePoolOptionsDto" } ] } } }, "ServerDatabaseConnectionDto": { "type": "object", "properties": { "type": { "type": "string", "description": "Database type for server-based connections", "enum": [ "mariadb", "mysql", "mssql" ] }, "table": { "type": "string", "description": "Specifies the table within the database to access", "example": "CostCenters" }, "clear": { "type": "boolean", "description": "Boolean value indicating whether to clear the table before loading or processing data", "default": false }, "schema": { "type": "string", "description": "The database schema where the table is located. Typically 'dbo' (Database Owner) by default", "example": "dbo" }, "whereClause": { "type": "string", "description": "Filter expression used as WHERE clause in SQL queries to restrict records", "example": "ControllingArea = 'CA001'" }, "limit": { "type": "number", "description": "Sets the maximum number of records to query from the database", "example": 100 }, "rawQuery": { "type": "string", "description": "Complete raw SQL query that can be sent directly to the database. This overrides automatic query generation based on other parameters", "example": "SELECT * FROM CostCenters WHERE ControllingArea = 'CA001'" }, "host": { "type": "string", "description": "Hostname or IP address of the database server", "example": "db.example.com" }, "port": { "type": "number", "description": "Port number on which the database server is listening", "example": 1433 }, "username": { "type": "string", "description": "Username for database authentication", "example": "db_user" }, "password": { "type": "string", "description": "Password for database authentication", "example": "db_password" }, "database": { "type": "string", "description": "The name of the database to connect to", "example": "ptpData" }, "options": { "description": "Additional database connection options for configuring encryption, timeouts, and connection pooling", "allOf": [ { "$ref": "#/components/schemas/ServerDatabaseConnectionOptionsDto" } ] } }, "required": [ "type", "table", "host", "port", "username", "password", "database" ] }, "FileBasedDatabaseConnectionDto": { "type": "object", "properties": { "type": { "type": "string", "description": "Database type for file-based connections", "enum": [ "sqlite" ] }, "table": { "type": "string", "description": "Specifies the table within the database to access", "example": "CostCenters" }, "clear": { "type": "boolean", "description": "Boolean value indicating whether to clear the table before loading or processing data", "default": false }, "schema": { "type": "string", "description": "The database schema where the table is located. Typically 'dbo' (Database Owner) by default", "example": "dbo" }, "whereClause": { "type": "string", "description": "Filter expression used as WHERE clause in SQL queries to restrict records", "example": "ControllingArea = 'CA001'" }, "limit": { "type": "number", "description": "Sets the maximum number of records to query from the database", "example": 100 }, "rawQuery": { "type": "string", "description": "Complete raw SQL query that can be sent directly to the database. This overrides automatic query generation based on other parameters", "example": "SELECT * FROM CostCenters WHERE ControllingArea = 'CA001'" }, "filename": { "type": "string", "description": "Path to the SQLite database file", "example": "./data/database.sqlite" } }, "required": [ "type", "table", "filename" ] }, "ErrorSummaryConfigurationDto": { "type": "object", "properties": { "customer": { "type": "string", "description": "Name of the customer for whom the error occurred", "example": "One Unity" }, "system": { "type": "string", "description": "Name of the system where the error occurred", "example": "SAP Production System" }, "product": { "type": "string", "description": "Name of the product or application that generated the error", "example": "SAP Public Cloud Connector" }, "description": { "type": "string", "description": "Detailed description of the error that occurred", "example": "Database connection timeout during data synchronization" }, "priority": { "type": "string", "description": "Priority level of the error for support escalation", "example": "High" }, "customerEmail": { "type": "string", "description": "Email address of the customer contact for error notifications", "format": "email", "example": "admin@one-unity.de" } }, "required": [ "customer", "system", "product", "description", "priority", "customerEmail" ] }, "LogOptionsDto": { "type": "object", "properties": { "level": { "type": "string", "description": "Logging level that determines which types of messages are recorded", "enum": [ "silly", "debug", "info", "warn", "error" ], "example": "info" }, "enableConsoleLogging": { "type": "boolean", "description": "Boolean flag to enable or disable logging output to the console", "example": true }, "file": { "type": "boolean", "description": "Boolean flag to enable or disable logging to files on disk", "example": true }, "directory": { "type": "string", "description": "Directory path where log files will be stored. If not specified, uses the default system logs directory", "example": "./logs" }, "keepFilesForDays": { "type": "number", "description": "Number of days to retain log files before automatic deletion. Helps manage disk space usage", "minimum": 1, "example": 30 }, "errorSummary": { "description": "Configuration for error summary notifications sent to customers when critical errors occur", "allOf": [ { "$ref": "#/components/schemas/ErrorSummaryConfigurationDto" } ] } }, "required": [ "level", "enableConsoleLogging", "file" ] }, "SapCertificateAuthenticationDto": { "type": "object", "properties": { "clientCrtPath": { "type": "string", "description": "Path to the client certificate file", "example": "./path/to/client-cert.pem" }, "clientKeyPath": { "type": "string", "description": "Path to the client private key file", "example": "./path/to/client-key.pem" }, "caCrtPath": { "type": "string", "description": "Path to the CA certificate file", "example": "./path/to/ca-cert.pem" } }, "required": [ "clientCrtPath", "clientKeyPath", "caCrtPath" ] }, "SapCredentialsAuthenticationDto": { "type": "object", "properties": { "username": { "type": "string", "description": "SAP API username", "example": "sap_user" }, "password": { "type": "string", "description": "SAP API password", "example": "sap_password" } }, "required": [ "username", "password" ] }, "SapConnectionDto": { "type": "object", "properties": { "baseUrl": { "type": "string", "description": "Base URL of the SAP API. Serves as the foundation to which additional path specifications (e.g., endpoint and query parameters) are appended", "example": "https://sap-api.example.com" }, "authentication": { "description": "Authentication method used for accessing the SAP Cloud API. Can be either username/password for Basic authentication or certificate-based authentication. Note: Values specified here override authentication stored in .env file", "oneOf": [ { "$ref": "#/components/schemas/SapCertificateAuthenticationDto" }, { "$ref": "#/components/schemas/SapCredentialsAuthenticationDto" } ] }, "endpoint": { "type": "string", "description": "Specific path within the API through which the desired resources are accessed. This path is appended to the base URL", "example": "/odata4/sap/api_cost_center/srvd_a2x/sap/costcenter/0001/A_CostCenterText_2" }, "queryParams": { "type": "object", "description": "Additional query parameters to further specify the API request. Common parameters include $select (comma-separated list of fields), $expand (related records to retrieve, '*' for all), and $top (limits number of returned records)", "additionalProperties": { "type": "string" }, "example": { "$select": "Language,ControllingArea,CostCenter,ValidityEndDate,CostCenterName,CostCenterDescription", "$expand": "*" } } }, "required": [ "baseUrl", "endpoint" ] }, "TrimTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that removes whitespace from the beginning and end of a string", "enum": [ "trim" ] } }, "required": [ "transformerType" ] }, "TakeTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that takes the first specified number of characters from a string", "enum": [ "take" ] }, "take": { "type": "number", "description": "Number of characters to take from the beginning of the string", "minimum": 0, "example": 5 } }, "required": [ "transformerType", "take" ] }, "SubstringTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that extracts a substring from a string", "enum": [ "substring" ] }, "start": { "type": "number", "description": "Start index of the substring. Negative values count from the end of the string", "example": 0 }, "end": { "type": "number", "description": "End index of the substring (not inclusive). Negative values count from the end of the string. If not provided, extracts to the end of the string", "example": 10 } }, "required": [ "transformerType", "start" ] }, "ReplaceTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that replaces all occurrences of a string with another string", "enum": [ "replace" ] }, "isRegExp": { "type": "boolean", "description": "If true, searchValue is interpreted as a regular expression, otherwise as a literal string. Note: Due to encoding issues, backslash (\\) cannot currently be used in RegExp", "default": false, "example": true }, "searchValue": { "type": "string", "description": "Value to search for. Interpreted as RegExp if isRegExp is true, otherwise as literal string", "example": "[A-Za-z]+" }, "replaceValue": { "type": "string", "description": "Value to replace the found occurrences with", "example": "" } }, "required": [ "transformerType", "searchValue", "replaceValue" ] }, "RoundTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that rounds a number to the specified number of decimal places", "enum": [ "round" ] }, "round": { "type": "number", "description": "Number of decimal places to round the number to", "minimum": 0, "example": 2 } }, "required": [ "transformerType", "round" ] }, "FormatDateTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that formats a date passed as string, number, or Date object", "enum": [ "formatDate" ] }, "format": { "type": "string", "description": "Input date format. Uses day.js parsing formats. If empty, attempts to parse in 'YYYY-MM-DD' format", "default": "YYYY-MM-DD", "example": "DD/MM/YYYY" }, "targetFormat": { "type": "string", "description": "Target date format for output. Uses day.js formatting. If empty, returns date in ISO8601 format", "default": "YYYY-MM-DDTHH:mm:ssZ[Z]", "example": "YYYY-MM-DD" } }, "required": [ "transformerType" ] }, "ParseFloatTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that converts a string to a floating-point number", "enum": [ "parseFloat" ] } }, "required": [ "transformerType" ] }, "ParseFloatToStringTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that converts a number to a string", "enum": [ "parseFloatToString" ] } }, "required": [ "transformerType" ] }, "ParseBooleanTransformerDto": { "type": "object", "properties": { "transformerType": { "type": "string", "description": "Transformer type that converts a string or number to a boolean. For strings: 'true' becomes true, all others become false. For numbers: 1 becomes true, all others become false. Other data types remain unchanged", "enum": [ "parseBoolean" ] } }, "required": [ "transformerType" ] }, "GroupByFieldDto": { "type": "object", "properties": { "transform": { "description": "Transformation options that are executed after retrieving data and before sending data. When an array of transformation options is passed, they are processed sequentially from first to last element. The output of one transformation option becomes the input for the next transformation option", "oneOf": [ { "$ref": "#/components/schemas/TrimTransformerDto" }, { "$ref": "#/components/schemas/TakeTransformerDto" }, { "$ref": "#/components/schemas/SubstringTransformerDto" }, { "$ref": "#/components/schemas/ReplaceTransformerDto" }, { "$ref": "#/components/schemas/RoundTransformerDto" }, { "$ref": "#/components/schemas/FormatDateTransformerDto" }, { "$ref": "#/components/schemas/ParseFloatTransformerDto" }, { "$ref": "#/components/schemas/ParseFloatToStringTransformerDto" }, { "$ref": "#/components/schemas/ParseBooleanTransformerDto" }, { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TrimTransformerDto" }, { "$ref": "#/components/schemas/TakeTransformerDto" }, { "$ref": "#/components/schemas/SubstringTransformerDto" }, { "$ref": "#/components/schemas/ReplaceTransformerDto" }, { "$ref": "#/components/schemas/RoundTransformerDto" }, { "$ref": "#/components/schemas/FormatDateTransformerDto" }, { "$ref": "#/components/schemas/ParseFloatTransformerDto" }, { "$ref": "#/components/schemas/ParseFloatToStringTransformerDto" }, { "$ref": "#/components/schemas/ParseBooleanTransformerDto" } ] } } ] }, "key": { "type": "string", "description": "" }, "keyInGroupResult": { "description": "Determines if and under which key a value from the source data is included in the output dataset", "default": false, "oneOf": [ { "type": "string", "description": "The value under 'key' is read from source data and stored in the output dataset under the specified string key" }, { "type": "boolean", "description": "true: value is stored under the same key as 'key', false: value is not included in output" } ], "examples": [ "customKeyName", true, false ] } }, "required": [ "key" ] }, "SingleMappingDto": { "type": "object", "properties": { "transform": { "description": "Transformation options that are executed after retrieving data and before sending data. When an array of transformation options is passed, they are processed sequentially from first to last element. The output of one transformation option becomes the input for the next transformation option", "oneOf": [ { "$ref": "#/components/schemas/TrimTransformerDto" }, { "$ref": "#/components/schemas/TakeTransformerDto" }, { "$ref": "#/components/schemas/SubstringTransformerDto" }, { "$ref": "#/components/schemas/ReplaceTransformerDto" }, { "$ref": "#/components/schemas/RoundTransformerDto" }, { "$ref": "#/components/schemas/FormatDateTransformerDto" }, { "$ref": "#/components/schemas/ParseFloatTransformerDto" }, { "$ref": "#/components/schemas/ParseFloatToStringTransformerDto" }, { "$ref": "#/components/schemas/ParseBooleanTransformerDto" }, { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TrimTransformerDto" }, { "$ref": "#/components/schemas/TakeTransformerDto" }, { "$ref": "#/components/schemas/SubstringTransformerDto" }, { "$ref": "#/components/schemas/ReplaceTransformerDto" }, { "$ref": "#/components/schemas/RoundTransformerDto" }, { "$ref": "#/components/schemas/FormatDateTransformerDto" }, { "$ref": "#/components/schemas/ParseFloatTransformerDto" }, { "$ref": "#/components/schemas/ParseFloatToStringTransformerDto" }, { "$ref": "#/components/schemas/ParseBooleanTransformerDto" } ] } } ] }, "sourceField": { "type": "string", "description": "Source field name" }, "targetField": { "type": "string", "description": "Target field name" }, "isUpdateKey": { "type": "boolean", "description": "Indicates whether this field is used as an update key for identifying existing records during database updates. When true, this field is used in WHERE clauses to match existing records for updates instead of inserts", "default": false, "example": true } }, "required": [ "sourceField", "targetField" ] }, "GroupMappingDto": { "type": "object", "properties": { "groupByFields": { "description": "Defines the fields by which data should be grouped. Can be a single field name (string), a GroupByField object with additional configuration, or an array of either type for grouping by multiple fields", "oneOf": [ { "$ref": "#/components/schemas/GroupByFieldDto" }, { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/GroupByFieldDto" }, { "type": "string" } ] } } ] }, "itemsTargetField": { "type": "string", "description": "Specifies the field name in the output data record under which the grouped items are stored as an array." }, "itemsMapping": { "description": "Defines how fields of grouped items are mapped in the output.", "oneOf": [ { "$ref": "#/components/schemas/GroupMappingDto" }, { "$ref": "#/components/schemas/SingleMappingDto" }, { "type": "array", "items": { "$ref": "#/components/schemas/SingleMappingDto" } } ] } }, "required": [ "groupByFields", "itemsTargetField", "itemsMapping" ] }, "OperationDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the operation", "example": "fetchCostCenters" }, "direction": { "type": "string", "description": "The direction of the operation. Can be SAP_TO_DB or DB_TO_SAP", "enum": [ "SAP_TO_DB", "DB_TO_SAP" ], "example": "SAP_TO_DB" }, "mapping": { "description": "The mapping between the SAP response and the database table.", "oneOf": [ { "$ref": "#/components/schemas/GroupMappingDto" }, { "$ref": "#/components/schemas/SingleMappingDto" }, { "type": "array", "items": { "$ref": "#/components/schemas/SingleMappingDto" } } ] }, "iteratorInputPath": { "type": "string", "description": "JSON path to the items array in the SAP response (used only for direction SAP_TO_DB). If provided, this path is used. Otherwise, the response is checked for a top-level 'value' property, then 'd.results'. If neither exists, an empty array is assumed.", "example": "[0]._CostCenter.SAP__Messages" }, "updateBatchSize": { "type": "number", "description": "Specifies how many records per batch are written to the database during an update from SAP. Only considered when direction is set to SAP_TO_DB and clear: false is used in the databaseConnection configuration. Batches are processed sequentially. WARNING: If updateBatchSize ≤ 0, all updates in the batch run completely parallel and without transactions (ATTENTION: Deadlock risks)", "minimum": 0, "default": 0, "example": 1000 }, "updateTransactionSize": { "type": "number", "description": "Specifies the maximum number of records updated per database transaction. Only considered when direction is set to SAP_TO_DB and clear: false is used in the databaseConnection configuration. Enables batch processing of large datasets to avoid memory and performance issues. When the total records exceed this value, a commit is automatically executed and a new transaction is started", "minimum": 1, "default": 100, "example": 100 } }, "required": [ "name", "direction", "mapping" ] }, "ConfigDto": { "type": "object", "properties": { "log": { "description": "Logging configuration settings (Note: These settings are not yet functional and are intended for future extensions)", "allOf": [ { "$ref": "#/components/schemas/LogOptionsDto" } ] }, "sapConnection": { "description": "Connection details for the SAP system", "allOf": [ { "$ref": "#/components/schemas/SapConnectionDto" } ] }, "databaseConnection": { "description": "Database connection configuration - can be either server-based or file-based connection", "oneOf": [ { "$ref": "#/components/schemas/ServerDatabaseConnectionDto" }, { "$ref": "#/components/schemas/FileBasedDatabaseConnectionDto" } ] }, "operations": { "description": "Array of operation objects to be executed for data transport and processing", "type": "array", "items": { "$ref": "#/components/schemas/OperationDto" } } }, "required": [ "sapConnection", "databaseConnection", "operations" ] }, "CreateTaskResponseDto": { "type": "object", "properties": { "taskId": { "type": "string", "description": "The unique identifier of the created task", "example": "27e0c243-e736-42d9-8f7b-4c988c0fa4f0" } }, "required": [ "taskId" ] }, "TaskStatusDto": { "type": "object", "properties": { "taskId": { "type": "string", "description": "The unique identifier of the task", "example": "27e0c243-e736-42d9-8f7b-4c988c0fa4f0" }, "status": { "type": "string", "description": "Current status of the task", "enum": [ "pending", "running", "completed", "failed" ], "example": "completed" }, "startDate": { "format": "date-time", "type": "string", "description": "Timestamp when the task started in ISO 8601 format (UTC)", "example": "2025-03-07T15:00:47.125Z" }, "endDate": { "format": "date-time", "type": "string", "description": "Timestamp when the task ended in ISO 8601 format (UTC)", "example": "2025-03-07T15:00:47.945Z" }, "errorMessage": { "type": "string", "description": "Contains an error message if the task failed, otherwise null", "nullable": true, "default": null, "example": null }, "result": { "type": "object", "description": "Result data of the completed task", "nullable": true, "default": null, "example": null } }, "required": [ "taskId", "status", "startDate" ] }, "CleanupLogsTypeDto": { "type": "object", "properties": { "taskDatabaseLogRetentionDays": { "type": "number", "description": "Number of days after which log entries are deleted", "default": 30, "minimum": 1, "example": 30 } } }, "CleanupLogsResultDto": { "type": "object", "properties": { "deletedLogCount": { "type": "number", "description": "Number of deleted log entries that were removed from the database", "minimum": 0, "example": 10 } }, "required": [ "deletedLogCount" ] } } } }