Endpoints & Domains

Endpoints define the integration points between the Manager and your backend services. They specify how the Manager should communicate with external APIs and services, and can be used for both direct backend integration and the Enterprise Service Bus (ESB).

Overview

Endpoints serve multiple purposes:

1. Backend Integration - Define URLs and authentication for calling backend services
2. Enterprise Service Bus (ESB) - Provide secure API gateway with transformation and audit logging

Managing Endpoints

Creating an Endpoint

1. Navigate to Applications in the sidebar
2. Select an application
3. Click the Endpoints tab
4. Click New Endpoint
5. Fill in the endpoint details:
   • Name - Descriptive name for the endpoint
   • Description - Purpose and usage notes
   • Consume URL - Path that triggers this endpoint (e.g., /api/webhook)
   • URL - Target backend URL (e.g., https://backend.example.com/webhook)
   • Enabled - Toggle to enable/disable the endpoint
   • Log Level - ESB audit logging verbosity (None, Basic, Full)

Authentication Types

Endpoints support multiple authentication methods:

None

No authentication is applied to requests.

Bearer Token

Adds an Authorization: Bearer <token> header to requests.

Configuration:

• Auth Token - The bearer token to use

Basic Authentication

Adds an Authorization: Basic <credentials> header with base64-encoded credentials.

Configuration:

• Auth Username - The username
• Auth Password - The password

ESB Audit Log Level

Control how much data is logged for ESB requests:

None

No audit logs are created. Use this for high-volume, low-security endpoints to save database space.

Basic (Default)

Logs metadata only:

• Timestamp and duration
• Source IP, method, and path
• Response status code
• Error messages (if any)
• Whether transformation was applied

Request/response headers and bodies are not logged.

Full

Logs everything including:

• All Basic level data
• Complete request headers and body
• Complete response headers and body

Database Impact

Full logging can significantly increase database size. Use only for debugging or compliance requirements.

Message Transformation

ESB Implementation

Message transformation templates are fully implemented in the Enterprise Service Bus (ESB). The ESB provides secure API gateway functionality with transformation, authentication, and configurable audit logging.

Endpoints support Go template-based message transformation for use with the ESB. Templates transform incoming request bodies before forwarding to the backend URL.

Example Template:

{
  "endpoint": "{{ .Endpoint.Name }}",
  "timestamp": "{{ .Meta.Timestamp }}",
  "user": "{{ .User.Username }}",
  "data": {{ .Data | toJson }}
}

Template Context:

• .Data - Parsed request body (JSON object or XML data)
• .Application.ID - Application UUID
• .Application.Name - Application name
• .Application.Slug - Application slug
• .Application.Description - Application description
• .Endpoint.ID - Endpoint UUID
• .Endpoint.Name - Endpoint name
• .Endpoint.ConsumeURL - The consume URL path
• .Endpoint.URL - Backend target URL
• .Endpoint.Description - Endpoint description
• .User.ID - Machine user UUID (if authenticated)
• .User.Username - Machine user username
• .User.Name - Machine user display name
• .Meta.Timestamp - Request timestamp (RFC3339 format)
• .Meta.RequestTime - Go time.Time object
• .Env - Map of safe environment variables (PRODUCTIFY_ENV, APP_ENV, etc.)

Template Functions:

• toJson - Convert value to JSON string
• toString - Convert value to string
• toUpper - Convert string to uppercase
• toLower - Convert string to lowercase
• now - Get current timestamp (RFC3339 format)
• env - Get environment variable by key

Input/Output Message Types

Configure how the endpoint parses and outputs messages:

Input Message Type:

• JSON - Parse as JSON (application/json)
• XML - Parse as XML (application/xml)
• SOAP - Parse as SOAP/XML (text/xml)
• None - Auto-detect (tries JSON, falls back to plain text)

Output Message Type:

• JSON - Output as JSON (application/json)
• XML - Output as XML (application/xml)
• SOAP - Output as SOAP (text/xml; charset=utf-8)

The output type determines the Content-Type header sent to the backend service when transformation is applied.

Template Examples

Add Authentication Header:

{
  "authorization": "Bearer {{ env "API_TOKEN" }}",
  "payload": {{ .Data | toJson }}
}

Enrich with Context:

{
  "timestamp": "{{ now }}",
  "application": {
    "id": "{{ .Application.ID }}",
    "name": "{{ .Application.Name }}"
  },
  "user": "{{ .User.Username }}",
  "request": {{ .Data | toJson }}
}

Transform Field Names:

{
  "customerName": "{{ .Data.name | toUpper }}",
  "customerEmail": "{{ .Data.email | toLower }}",
  "timestamp": "{{ .Meta.Timestamp }}"
}

Conditional Logic:

{
  "data": {{ .Data | toJson }},
  {{ if .User.Username }}
  "authenticated_user": "{{ .User.Username }}",
  {{ end }}
  "environment": "{{ .Env.PRODUCTIFY_ENV }}"
}

XML to JSON Transformation:

Set Input Message Type: XML and Output Message Type: JSON, then use:

{
  "converted_from_xml": {{ .Data | toJson }},
  "processed_at": "{{ now }}"
}

Machine User Access

Endpoints can be restricted to specific machine users for security, especially when used with the ESB.

Assigning Machine Users

1. Navigate to Endpoints → Select endpoint
2. Click Machine User Access
3. Select machine users that can access this endpoint
4. Enable/disable access per machine user

This creates a many-to-many relationship between machine users and endpoints, allowing fine-grained access control for ESB requests.

Enterprise Service Bus (ESB)

Endpoints can be exposed through the ESB for secure external API access. See the ESB documentation for details on:

• Calling endpoints via /esb/{applicationId}/{endpointPath}
• Machine user authentication
• Request transformation
• Audit logging configuration

Best Practices

Security

• Use Bearer token or Basic auth for production endpoints
• Rotate authentication credentials regularly
• Use HTTPS for all backend URLs
• Limit machine user access to required endpoints only

Reliability

• Enable only endpoints that are actively in use
• Test endpoints before enabling in production
• Configure appropriate timeout values
• Implement retry logic in backend services

Organization

• Use descriptive names that indicate the endpoint's purpose
• Document authentication requirements in the description
• Group related endpoints under the same application
• Use consistent URL patterns across endpoints
• Set appropriate log levels (BASIC for production, FULL for debugging)

Message Transformation

• Keep templates simple and maintainable
• Validate template syntax before deployment
• Handle missing fields gracefully
• Log transformation errors for debugging

Troubleshooting

Endpoint Not Responding

Check:

• Endpoint is Enabled
• Backend URL is accessible from the Manager server
• Authentication credentials are correct
• Network/firewall rules allow outbound connections

Authentication Failures

Verify:

• Auth type matches backend expectations
• Credentials are current and valid
• Token/password hasn't expired
• Machine user has access to the endpoint

Transformation Errors

Common Issues:

• Template syntax error - Check Go template syntax ( braces, proper function calls)
• Missing fields - Verify .Data contains expected fields from request
• Function not found - Use only supported functions: toJson, toString, toUpper, toLower, now, env
• JSON parsing failed - Check input message type matches actual request format
• Context fields missing - Some context (Application, User) requires proper edge loading

Debug Steps:

1. Set Log Level: FULL to capture request/response bodies
2. Check ESB audit logs for transformation errors
3. Test template with simple static output first
4. Verify .Data structure matches input format
5. Use {{ .Data | toJson }} to inspect parsed data
6. Review Manager server logs for detailed error messages

API Integration

Endpoints can be managed via the GraphQL API. Available mutations:

• createEndpoint - Create new endpoint with authentication and transformation
• updateEndpoint - Update existing endpoint configuration
• deleteEndpoint - Remove endpoint

Key Fields:

• name, description - Identification
• consumeURL - ESB path that triggers this endpoint
• url - Backend target URL
• enabled - Enable/disable toggle
• authType, authUsername, authPassword, authToken - Authentication
• inputMessageType, outputMessageType - Message format (SOAP, XML, JSON)
• transformationTemplate - Go template for transformation
• logLevel - Audit logging verbosity (NONE, BASIC, FULL)

See the API Reference for complete endpoint management operations.