Forem: Makini

Integrating with Jira: Webhook Patterns and Custom Field Handling

Makini — Thu, 30 Apr 2026 08:35:18 +0000

Jira Software presents specific technical challenges when building production integrations. Primary issues: custom field proliferation, webhook reliability, and API rate limits.

Custom Field Problem:

Jira instances are heavily customized. Standard fields get extended, custom fields added per project or workflow. No two installations have identical schemas. Querying issues returns field IDs (customfield_10042) with no semantic meaning.

Solution requires two-phase approach: schema discovery via /field endpoint to map field IDs to names/types, then runtime field resolution per issue. Caching field schemas per connection reduces API calls but requires invalidation on schema changes.

Webhook Reliability:

Jira webhooks fire on issue transitions but have known delivery issues. Webhooks can arrive out of order, duplicate, or not at all. Jira doesn't guarantee ordering or exactly-once semantics.

Implementation requires idempotency keys (use issue.updated timestamp + event type), deduplication logic tracking processed events, and periodic polling as fallback to catch missed webhooks. Don't rely solely on webhooks for critical workflows.

Rate Limiting:

Cloud instances enforce rate limits per client (10 requests/sec for reads, 5/sec for writes). On-premise installations vary based on configuration. Exceeding limits returns 429 with Retry-After header.

Adaptive rate limiting required: track successful request timestamps, implement token bucket algorithm per connection, back off automatically on 429s. Batch operations where possible using JQL queries with pagination.

JQL Complexity:

Jira Query Language is powerful but brittle. Syntax errors return unhelpful messages. Custom field references use IDs not names. JQL injection possible if constructing queries from user input.

Never interpolate user input into JQL strings. Use parameterized queries or construct via API objects. Validate field IDs exist before building queries. Cache frequently-used queries per connection.

Authentication Variants:

Cloud uses OAuth 2.0 or API tokens. Server/Data Center uses basic auth, OAuth 1.0a, or personal access tokens depending on version. No reliable way to detect which auth scheme an instance supports without attempting connection.

Implement multi-auth support with fallback chain. Attempt OAuth first, fall back to API token, then basic auth. Store auth type per connection after successful authentication.

Performance Considerations:

Issue queries can be slow on large instances. Pagination required for result sets >100. Expansion parameters (expand=changelog,renderedFields) significantly impact response size and latency.

Minimize expansions to required data. Use field filters (fields=summary,status,assignee) to reduce payload size. Implement connection-specific query optimization based on observed performance patterns.

Testing Challenges:

Can't reliably replicate customer Jira configurations. Custom fields, workflows, and permissions vary significantly. Mock testing insufficient for integration validation.

Strategy: contract tests for API schema validation, sandbox instance with representative custom fields, snapshot testing for detecting API changes, production monitoring with detailed error logging.

Key Observations:

Jira API documentation incomplete for edge cases. Custom field behavior varies by field type (select vs multi-select vs text). Workflow transitions may have validators blocking programmatic updates. Issue linking semantics differ between projects.

Jira Software integration reference implementation handles these edge cases.

Integrating with Legacy Manufacturing ERP: Technical Realities

Makini — Fri, 24 Apr 2026 07:48:13 +0000

Macola ERP presents typical challenges when integrating modern applications with legacy enterprise systems. Here's what we've learned building production integrations.

Version Fragmentation:

Macola ships in three editions (ES, EX, Progression) with incompatible APIs. ES uses COM interfaces. EX added SOAP web services inconsistently across modules. Progression introduced partial REST support. Single installations often mix interface types depending on which modules were upgraded.

You can't version-detect and branch. You need runtime capability detection per module.

Data Model Variability:

Manufacturing ERPs are heavily customized. Fields renamed, custom fields added, validation rules modified per installation. Creating a unified model as the union of all possible fields produces unusable APIs with unclear field semantics.

Solution: core fields plus typed extension properties. Clients get predictable common fields, custom fields live in a structured metadata object with type information.

Authentication:

Installations use Windows auth, SQL credentials, proprietary tokens, or custom SSO. On-prem adds VPN requirements. Don't expose this to API consumers. Implement connection abstraction—clients reference connections by ID, platform handles auth internally.

Undocumented Rate Limits:

Legacy systems weren't designed for API access. Rate limits exist but aren't documented. Implement adaptive limiting: start conservative, increase gradually while monitoring errors, back off automatically on throttling.

Error Handling:

Systems return XML with cryptic messages or success codes masking partial failures. Translation layer required. Map error conditions to standard codes, extract actionable information where possible, preserve raw responses for debugging.

Testing:

Can't spin up customer ERP instances. Strategy: contract tests for schemas, integration tests against sandboxes when available, snapshot tests for detecting API drift, synthetic monitoring in production.

Key Observations:

Documentation is incomplete or wrong. Behavior varies between versions despite API compatibility claims. API endpoints have hidden dependencies—updating one entity affects others silently. System-specific quirks require per-installation configuration.

Building unified APIs for heterogeneous ERPs is about pragmatic trade-offs between abstraction and capability preservation, not perfect models.

Macola integration reference implementation available.

Connecting TechnologyOne to Your App via Makini API

Makini — Fri, 10 Apr 2026 05:42:35 +0000

TechnologyOne is widely used across government, education, and regulated industries for finance, asset management, HR, and operations. If you're building industrial software and your customers run TechnologyOne, sooner or later you'll need to pull data out of it — work orders, assets, purchase orders, maintenance records, and more.

The traditional approach means negotiating API access with the customer's IT team, reading through dense vendor documentation, and writing a custom connector that you'll have to maintain forever. We built Makini so you don't have to do any of that.

What you get with the Makini × TechnologyOne integration

Through a single unified API, you get access to the full range of TechnologyOne data objects your product is likely to need:

Assets — equipment records and site hierarchy
Work Orders — task execution, assignments, deadlines
Preventive Maintenance — time-based and counter-based templates
Asset Downtime — planned and unplanned outage records
Materials & Stock — spare parts, consumables, storeroom quantities
Purchase Orders — procurement documents with line items
Service Requests — internal and external maintenance requests
Labor — human resources tied to work order execution
Locations, Sites, Teams, Users, Vendors — the full organizational context

All of these are available via the same endpoints you'd use for any other system in the Makini catalog. No per-system SDK, no bespoke field mapping — just consistent, normalized data.

How the connection works

Your customer opens Makini Link (embeddable in your app or triggered via a link/email), selects TechnologyOne, and logs in with their existing credentials. That's it — the connection is live. The whole flow takes about a minute and requires no involvement from your engineering team.

On the backend, Makini handles auth, syncs, retries, and keeps the integration alive as TechnologyOne's API evolves.

Why this matters for your product roadmap

If you're selling to enterprise accounts in the public sector or education, TechnologyOne is a system you'll encounter regularly. Without a ready integration, you're either losing deals or committing to months of custom work upfront. With Makini, you can tell prospects "yes, we support TechnologyOne" on day one — and actually mean it.

Check out the full data model and API reference: makini.io/integrations/technologyone

Want to test the connection? Start a free trial →

Designing APIs for Heterogeneous Enterprise Systems: Lessons from 2000+ Integrations

Makini — Fri, 03 Apr 2026 07:56:55 +0000

At Makini, we've spent six years building integrations across enterprise systems—ERP platforms like SAP and Oracle, CMMS solutions like IBM Maximo, WMS systems like Manhattan, and over 2000 other industrial software platforms. This experience has taught us hard lessons about API design, data modeling, and the unique challenges of creating unified interfaces for fundamentally different systems.

The Standardization Problem:

Enterprise systems weren't designed with third-party integrations in mind. They evolved to solve specific industry problems, which means their data models reflect decades of domain-specific decisions. A "purchase order" in SAP has different required fields, validation rules, and lifecycle states than a purchase order in Oracle. Yet conceptually, they represent the same business entity.

The naive approach is to create a unified data model that's the union of all fields across all systems. This produces an API with hundreds of optional fields where clients never know which combinations are valid for which systems. The result is an interface that's technically complete but practically unusable.

Our Approach: Core Models with Extension Points:

We've settled on a pattern where unified models define a core set of common fields that exist across most systems, use consistent naming conventions regardless of source system terminology, include standard validation rules that apply universally, and provide clear semantic meaning for each field.

System-specific fields that don't fit the common model go into an extended_properties object that's indexed by field name and includes metadata about the field's type and validation rules. This preserves access to all data while keeping the common case simple.

Here's a simplified example of how this looks in practice:

{
  "id": "po_123",
  "type": "purchase_order",
  "vendor_id": "vendor_456",
  "total_amount": 15000.00,
  "currency": "USD",
  "status": "approved",
  "line_items": [...],
  "extended_properties": {
    "sap_plant_code": {
      "value": "US01",
      "type": "string",
      "description": "SAP-specific plant identifier"
    },
    "custom_approval_level": {
      "value": 3,
      "type": "integer",
      "description": "Internal approval hierarchy level"
    }
  }
}

Handling Authentication Flows:

Enterprise systems use wildly different authentication mechanisms. We've encountered OAuth 2.0 with various grant types, API keys with different header formats, session-based authentication requiring login flows, SAML and other SSO protocols, and legacy systems with custom authentication schemes.

Rather than exposing this complexity to API consumers, we implement a credential management layer that normalizes authentication across systems. Developers work with connection objects that abstract the underlying auth mechanism. Our authentication module handles token refresh, session management, and credential storage automatically.

The key architectural decision was separating connection establishment (which happens once per customer) from API requests (which happen continuously). Connection establishment can be complex and user-interactive; API requests must be simple and programmatic.

Rate Limiting and Backpressure:

Different systems have vastly different rate limits, and some don't document their limits at all. We've built adaptive rate limiting that learns system behavior over time, implements per-connection backpressure to avoid overwhelming source systems, queues requests when approaching rate limits, and provides webhook-based notifications when async operations complete.

For systems without documented rate limits, we start conservatively and gradually increase request rates while monitoring for rate limit errors. This auto-tuning approach has proven more reliable than trying to discover limits through documentation or support channels.

Versioning Strategy:

With 2000+ integrations, we need to handle API versioning at multiple levels. The source system's API version can change, our unified API version evolves with new features, and customer-specific configurations may be pinned to specific versions.

Our versioning approach uses semantic versioning for the unified API with backward compatibility guarantees, per-connection version pinning so customers control when they upgrade, transformation layers that translate between unified API versions, and deprecation windows with clear migration paths.

We maintain multiple API versions simultaneously in production, which adds operational complexity but prevents breaking changes from disrupting customer operations.

Error Handling and Observability:

When an API call fails, it could be due to network issues, the source system being down, invalid data format, business rule violations in the source system, or authentication/permission problems. Each category requires different handling and different information for debugging.

Our error responses include structured error codes that clients can switch on programmatically, request IDs that trace through our entire stack and into source systems where possible, contextual information about what operation was being attempted, and actionable remediation steps when we can determine them.

For observability, we emit structured logs at API boundaries, track request latency percentiles per source system, monitor error rates with automatic alerting, and maintain dashboards showing health metrics for each connected system.

The Webhook Challenge:

Many enterprise systems support webhooks for real-time notifications, but implementations vary wildly. Some send webhooks with full payloads, others send just IDs requiring follow-up API calls, signature schemes for verification differ across systems, and retry behavior is inconsistent or undocumented.

We normalize this by receiving webhooks from source systems, verifying signatures using system-specific methods, transforming payloads into our unified event format, and delivering to customer webhook endpoints with guaranteed delivery semantics.

Our webhook infrastructure includes replay capabilities for debugging, automatic retry with exponential backoff, dead letter queues for persistently failing deliveries, and monitoring to detect when source systems stop sending expected webhooks.

Performance Considerations:

Synchronizing data across thousands of connections requires careful attention to performance. We use connection pooling with per-system tuning for optimal throughput, parallel request processing with per-connection rate limiting, intelligent caching based on data volatility patterns, and incremental sync strategies that minimize data transfer.

For large datasets, we implement cursor-based pagination that works across systems with different pagination schemes, streaming responses to avoid memory pressure, and background jobs for operations that exceed reasonable request timeouts.

Testing Strategy:

Testing integrations with hundreds of enterprise systems presents unique challenges. Most systems are expensive to spin up test instances for, many have complex setup requirements, and production data can't be used for testing due to compliance requirements.

Our testing approach includes contract tests that verify API response schemas, integration tests against sandbox environments where available, snapshot testing to detect unexpected API changes, and synthetic monitoring in production to catch issues before customers do.

We also maintain a library of anonymized test fixtures captured from real customer connections, which helps us catch edge cases that wouldn't appear in clean test data.

Lessons Learned:

After building thousands of integrations, some patterns are clear. Documentation is often incomplete or outdated—observing actual API behavior is more reliable than trusting docs. Error messages from enterprise systems can be cryptic or entirely absent—good error handling must account for this. System behavior varies between versions even when APIs are supposedly compatible. Hidden rate limits and undocumented throttling are common.

The most important lesson is that building a unified API isn't about finding the perfect abstraction—it's about making pragmatic trade-offs that optimize for developer experience while preserving system-specific capabilities when needed.

Open Questions:

We're still exploring better approaches to several challenges. How do you design APIs that gracefully handle source system downtime without confusing clients? What's the right balance between eagerly validating input versus passing it through to source systems? How do you version data models when the underlying systems evolve in incompatible ways? What testing strategies work for systems you can't easily replicate?

If you're working on similar problems—API design for heterogeneous systems, integration platforms, or enterprise software connectivity—we'd love to hear your approaches and learn from your experiences.

More on integration architecture: https://www.makini.io/integrations