Skip to main content

​
Overview

The Workflows Service manages the complete lifecycle of workflows including creation, updates, termination, and deletion. Service Details:
  • Package: workflows
  • Port: 50052
  • Proto: proto/workflows/workflows.proto

​
Service Definition

service WorkflowsService {
    rpc CreateWorkflow(CreateWorkflowRequest) returns (CreateWorkflowResponse) {}
    rpc UpdateWorkflow(UpdateWorkflowRequest) returns (UpdateWorkflowResponse) {}
    rpc UpdateWorkflowBuildStatus(UpdateWorkflowBuildStatusRequest) returns(UpdateWorkflowBuildStatusResponse) {}
    rpc GetWorkflow(GetWorkflowRequest) returns (GetWorkflowResponse) {}
    rpc GetWorkflowByID(GetWorkflowByIDRequest) returns (GetWorkflowByIDResponse){}
    rpc IncrementWorkflowConsecutiveJobFailuresCount(IncrementWorkflowConsecutiveJobFailuresCountRequest) returns (IncrementWorkflowConsecutiveJobFailuresCountResponse) {}
    rpc ResetWorkflowConsecutiveJobFailuresCount(ResetWorkflowConsecutiveJobFailuresCountRequest) returns (ResetWorkflowConsecutiveJobFailuresCountResponse) {}
    rpc TerminateWorkflow(TerminateWorkflowRequest) returns(TerminateWorkflowResponse) {}
    rpc DeleteWorkflow(DeleteWorkflowRequest) returns (DeleteWorkflowResponse) {}
    rpc ListWorkflows(ListWorkflowsRequest) returns (ListWorkflowsResponse) {}
}

​
RPC Methods

​
CreateWorkflow

Create a new workflow. Request:
​
user_id
string
required
ID of the user creating the workflow
​
name
string
required
Name of the workflow
​
payload
string
required
JSON string containing workflow configuration
​
kind
string
required
Type of workflow (e.g., “http”, “script”, “docker”)
​
interval
int32
required
Execution interval in minutes
​
max_consecutive_job_failures_allowed
int32
required
Maximum consecutive failures before workflow termination
Response:
​
id
string
Unique identifier of the created workflow
Example: 
req := &workflows.CreateWorkflowRequest{
    UserId:                           "user-123",
    Name:                             "Daily Health Check",
    Payload:                          `{"url": "https://api.example.com/health"}`,
    Kind:                             "http",
    Interval:                         60,
    MaxConsecutiveJobFailuresAllowed: 3,
}

resp, err := client.CreateWorkflow(ctx, req)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Workflow created: %s\n", resp.Id)

​
UpdateWorkflow

Update an existing workflow’s configuration. Request:
​
id
string
required
Workflow ID to update
​
user_id
string
required
User ID (for authorization)
​
name
string
required
Updated workflow name
​
payload
string
required
Updated JSON configuration
​
interval
int32
required
Updated interval in minutes
​
max_consecutive_job_failures_allowed
int32
required
Updated failure threshold
Response: Empty response on success. Example: 
req := &workflows.UpdateWorkflowRequest{
    Id:                               "workflow-456",
    UserId:                           "user-123",
    Name:                             "Hourly Health Check",
    Payload:                          `{"url": "https://api.example.com/health", "timeout": 30}`,
    Interval:                         60,
    MaxConsecutiveJobFailuresAllowed: 5,
}

_, err := client.UpdateWorkflow(ctx, req)
if err != nil {
    log.Fatal(err)
}

​
UpdateWorkflowBuildStatus

Internal API - Not exposed to public. Used for inter-service communication.
Update the build status of a workflow. Request:
​
id
string
required
Workflow ID
​
user_id
string
required
User ID
​
build_status
string
required
Build status (e.g., “pending”, “building”, “success”, “failed”)
Response: Empty response on success.

​
GetWorkflow

Retrieve workflow details by ID and user ID. Request:
​
id
string
required
Workflow ID
​
user_id
string
required
User ID (for authorization)
Response:
​
id
string
Workflow ID
​
name
string
Workflow name
​
payload
string
JSON configuration
​
kind
string
Workflow type
​
build_status
string
Current build status
​
interval
int32
Execution interval in minutes
​
consecutive_job_failures_count
int32
Current consecutive failure count
​
max_consecutive_job_failures_allowed
int32
Maximum allowed consecutive failures
​
created_at
string
Creation timestamp
​
updated_at
string
Last update timestamp
​
terminated_at
string
Termination timestamp (if terminated)
Example: 
req := &workflows.GetWorkflowRequest{
    Id:     "workflow-456",
    UserId: "user-123",
}

resp, err := client.GetWorkflow(ctx, req)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Workflow: %s (Status: %s)\n", resp.Name, resp.BuildStatus)

​
GetWorkflowByID

Internal API - Not exposed to public. Used for inter-service communication.
Retrieve workflow by ID only (no user_id required). Request:
​
id
string
required
Workflow ID
Response: Same as GetWorkflow response, plus user_id field.

​
IncrementWorkflowConsecutiveJobFailuresCount

Internal API - Not exposed to public. Called when jobs fail.
Increment the consecutive job failures counter. Request:
​
id
string
required
Workflow ID
​
user_id
string
required
User ID
Response:
​
threshold_reached
bool
True if max failures threshold was reached

​
ResetWorkflowConsecutiveJobFailuresCount

Internal API - Not exposed to public. Called when jobs succeed.
Reset the consecutive job failures counter to zero. Request:
​
id
string
required
Workflow ID
​
user_id
string
required
User ID
Response: Empty response on success.

​
TerminateWorkflow

Terminate a workflow (stop scheduling new jobs). Request:
​
id
string
required
Workflow ID
​
user_id
string
required
User ID
Response: Empty response on success. Example: 
req := &workflows.TerminateWorkflowRequest{
    Id:     "workflow-456",
    UserId: "user-123",
}

_, err := client.TerminateWorkflow(ctx, req)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Workflow terminated")

​
DeleteWorkflow

Permanently delete a workflow. Request:
​
id
string
required
Workflow ID
​
user_id
string
required
User ID
Response: Empty response on success. Example: 
req := &workflows.DeleteWorkflowRequest{
    Id:     "workflow-456",
    UserId: "user-123",
}

_, err := client.DeleteWorkflow(ctx, req)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Workflow deleted")

​
ListWorkflows

List all workflows for a user with optional filters. Request:
​
user_id
string
required
User ID
​
cursor
string
Pagination cursor (empty for first page)
​
filters
ListWorkflowsFilters
Optional filters
ListWorkflowsFilters:
​
query
string
Search query string
​
kind
string
Filter by workflow type
​
build_status
string
Filter by build status
​
is_terminated
bool
Filter terminated workflows
​
interval_min
int32
Minimum interval filter
​
interval_max
int32
Maximum interval filter
Response:
​
workflows
WorkflowsByUserIDResponse[]
Array of workflow objects
​
cursor
string
Cursor for next page (empty if no more pages)
Example: 
req := &workflows.ListWorkflowsRequest{
    UserId: "user-123",
    Cursor: "",
    Filters: &workflows.ListWorkflowsFilters{
        Kind:        "http",
        BuildStatus: "success",
    },
}

resp, err := client.ListWorkflows(ctx, req)
if err != nil {
    log.Fatal(err)
}

for _, wf := range resp.Workflows {
    fmt.Printf("Workflow: %s (ID: %s)\n", wf.Name, wf.Id)
}

​
Connection Example

package main

import (
    "context"
    "log"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "github.com/hitesh22rana/chronoverse/pkg/proto/go/workflows"
)

func main() {
    conn, err := grpc.Dial(
        "localhost:50052",
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()

    client := pb.NewWorkflowsServiceClient(conn)
    ctx := context.Background()

    // Create workflow
    resp, err := client.CreateWorkflow(ctx, &pb.CreateWorkflowRequest{
        UserId:                           "user-123",
        Name:                             "API Monitor",
        Payload:                          `{"url": "https://api.example.com"}`,
        Kind:                             "http",
        Interval:                         30,
        MaxConsecutiveJobFailuresAllowed: 3,
    })
    if err != nil {
        log.Fatalf("CreateWorkflow failed: %v", err)
    }

    log.Printf("Created workflow: %s", resp.Id)
}

Build docs developers (and LLMs) love

Get started for freeTalk to us