Skip to main content

Go

github.com/QuantumBPM/quantum-go-sdk — the reference implementation. Requires Go 1.23+.

Installation​

go get github.com/QuantumBPM/quantum-go-sdk

Quick start​

package main

import (
    "context"
    "log"

    "github.com/google/uuid"

    quantumbpm "github.com/QuantumBPM/quantum-go-sdk"
    "github.com/QuantumBPM/quantum-go-sdk/auth"
    "github.com/QuantumBPM/quantum-go-sdk/variables"
)

func main() {
    provider, err := auth.NewZitadelTokenProvider(
        "./service-account.json",
        "https://auth.quantumbpm.com",
        "your-zitadel-project-id",
    )
    if err != nil {
        log.Fatal(err)
    }

    client, err := quantumbpm.New(quantumbpm.Config{
        BaseURL:       "https://api.quantumbpm.com",
        ProjectID:     uuid.MustParse("YOUR_PROJECT_ID"),
        TokenProvider: provider,
    })
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()
    result, err := client.DMN.Evaluate(ctx, "loan-eligibility", variables.New().
        Set("requestedAmt", 1000).
        Set("creditScore", 720))
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("decisions: %+v", result)
}

BPMN​

draft, _ := client.BPMN.CreateResource(ctx, "loan-process", bpmnXML)
client.BPMN.DeployResource(ctx, draft.Id)

deployed, _ := client.BPMN.GetResource(ctx, draft.Id)
processDef := (*deployed.Processes)[0]

workflowID, _ := client.BPMN.StartInstance(ctx, processDef.Id, variables.New().
    Set("applicantID", "u-123"))

External job workers​

The runtime owns long-polling, lock heartbeats, dispatch, and outcome mapping. Handlers run on a goroutine pool sized per task type.

import "github.com/QuantumBPM/quantum-go-sdk/workers"

worker := client.NewWorker(workers.Config{ClientID: "billing-svc"})

worker.Handle("send-email", func(ctx context.Context, j *workers.Job) (variables.Vars, error) {
    to, _ := variables.Get[string](j.Vars, "recipient")
    if err := emailer.Send(to); err != nil {
        return nil, err  // → ThrowError("WORKER_ERROR")
    }
    return variables.New().Set("messageID", "msg-123"), nil  // → Complete
}, workers.WithMaxJobs(10), workers.WithLockDuration("1m"))

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
worker.Run(ctx)  // blocks until ctx is cancelled

Throw a *workers.BpmnError to fail the job with a code that boundary error events on the originating service task can catch:

return nil, workers.NewBpmnError("INSUFFICIENT_FUNDS", variables.New().Set("balance", 12.0))

Use workers.HandleTyped[T] for opt-in typed dispatch — the SDK decodes job variables into T before invoking the handler.

Full reference​

See the SDK README for the complete API surface, including resource/instance management, messaging and signals, user tasks, and the Vars typed-access helpers.