workflows.go

package vsax

import (
	"context"
	"fmt"
	"iter"
	"net/http"
	"strconv"
)

// Workflow trigger types.
const (
	TriggerTypeNotification    = "Notification"
	TriggerTypeAdHocScheduled  = "Ad-hoc and Scheduled"
	TriggerTypeExternalWebhook = "External Webhook"
)

// Workflow context types.
const (
	WorkflowContextScope        = "Scope"
	WorkflowContextOrganization = "Organization"
	WorkflowContextDevice       = "Device"
	WorkflowContextDeviceless   = "Deviceless"
)

// Workflow execution statuses.
const (
	WorkflowStatusPending   = "Pending"
	WorkflowStatusRunning   = "Running"
	WorkflowStatusSuccess   = "Success"
	WorkflowStatusFailed    = "Failed"
	WorkflowStatusCanceling = "Canceling"
	WorkflowStatusCanceled  = "Canceled"
)

// Workflow is a VSA X automation workflow (list/detail summary).
type Workflow struct {
	ID             int64  `json:"Id"`
	Name           string `json:"Name,omitempty"`
	Description    string `json:"Description,omitempty"`
	IsEnabled      bool   `json:"IsEnabled"`
	TriggerType    string `json:"TriggerType,omitempty"`
	TriggerSubType string `json:"TriggerSubType,omitempty"`
	UpdatedAt      Time   `json:"UpdatedAt,omitzero"`
	ContextType    string `json:"ContextType,omitempty"`
	ContextItemID  string `json:"ContextItemId,omitempty"`
	FolderPath     string `json:"FolderPath,omitempty"`
}

// WorkflowDetails extends Workflow with trigger, actions, and folder info
// returned by GET /automation/workflows/{id}.
type WorkflowDetails struct {
	Workflow
	Trigger *WorkflowTrigger `json:"Trigger,omitempty"`
	Actions []WorkflowStep   `json:"Actions,omitempty"`
}

// WorkflowTrigger describes what starts a workflow.
type WorkflowTrigger struct {
	TriggerType    string                   `json:"TriggerType,omitempty"`
	TriggerSubType string                   `json:"TriggerSubType,omitempty"`
	Description    string                   `json:"Description,omitempty"`
	SkipOffline    bool                     `json:"SkipOffline,omitempty"`
	Schedule       *WorkflowTriggerSchedule `json:"Schedule,omitempty"`
	ID             int64                    `json:"Id,omitempty"`
	DisplayName    string                   `json:"DisplayName,omitempty"`
}

// WorkflowTriggerSchedule is the schedule for scheduled triggers.
type WorkflowTriggerSchedule struct {
	StartDate                   Time   `json:"StartDate,omitzero"`
	Timezone                    string `json:"Timezone,omitempty"`
	Frequency                   int    `json:"Frequency,omitempty"`
	FrequencyInterval           string `json:"FrequencyInterval,omitempty"`
	FrequencySubInterval        string `json:"FrequencySubInterval,omitempty"`
	DistributionPeriodInSeconds int    `json:"DistributionPeriodInSeconds,omitempty"`
}

// WorkflowStep is a single node in a workflow's execution tree. Action steps
// carry ActionType + Parameters; condition steps carry Rules + Positive/
// NegativeOutcome branches.
type WorkflowStep struct {
	ID              int64                   `json:"Id,omitempty"`
	DisplayName     string                  `json:"DisplayName,omitempty"`
	StepType        string                  `json:"StepType,omitempty"` // "Action" | "Condition"
	ActionType      string                  `json:"ActionType,omitempty"`
	Parameters      string                  `json:"Parameters,omitempty"` // JSON-encoded string
	PositiveOutcome []WorkflowStep          `json:"PositiveOutcome,omitempty"`
	NegativeOutcome []WorkflowStep          `json:"NegativeOutcome,omitempty"`
	RuleAggregation string                  `json:"RuleAggregation,omitempty"`
	Rules           []WorkflowConditionRule `json:"Rules,omitempty"`
}

// WorkflowConditionRule is a rule evaluated by a condition step.
type WorkflowConditionRule struct {
	PropertyID string `json:"PropertyId,omitempty"`
	Operator   string `json:"Operator,omitempty"`
	Value      string `json:"Value,omitempty"`
}

// VariableOverride overrides a named workflow variable at run time.
type VariableOverride struct {
	Name  string `json:"Name"`
	Value string `json:"Value"`
}

// WorkflowExecution summarises one execution of a workflow.
type WorkflowExecution struct {
	ID                        int64              `json:"Id"`
	WorkflowID                int64              `json:"WorkflowId"`
	TargetType                string             `json:"TargetType,omitempty"` // "Device" | "Server"
	TargetID                  string             `json:"TargetId,omitempty"`
	TriggerType               string             `json:"TriggerType,omitempty"`
	TriggerID                 string             `json:"TriggerId,omitempty"`
	Status                    string             `json:"Status,omitempty"`
	CreatedAt                 Time               `json:"CreatedAt,omitzero"`
	CompletedAt               Time               `json:"CompletedAt,omitzero"`
	ConstantVariableOverrides []VariableOverride `json:"ConstantVariableOverrides,omitempty"`
	FolderPath                string             `json:"FolderPath,omitempty"`
}

// WorkflowExecutionDetails extends WorkflowExecution with per-step results.
type WorkflowExecutionDetails struct {
	WorkflowExecution
	ExecutionSteps []WorkflowExecutionStep `json:"ExecutionSteps,omitempty"`
}

// WorkflowExecutionStep is one step's result in an execution.
type WorkflowExecutionStep struct {
	WorkflowStepID int64                         `json:"WorkflowStepId"`
	Status         string                        `json:"Status,omitempty"`
	CompletedAt    Time                          `json:"CompletedAt,omitzero"`
	UpdatedAt      Time                          `json:"UpdatedAt,omitzero"`
	Outcome        *bool                         `json:"Outcome,omitempty"`
	OutputItems    []WorkflowExecutionOutputItem `json:"OutputItems,omitempty"`
}

// WorkflowExecutionOutputItem is one output from a workflow step.
type WorkflowExecutionOutputItem struct {
	VariableID              int64          `json:"VariableId,omitempty"`
	VariableName            string         `json:"VariableName,omitempty"`
	VariableDataType        string         `json:"VariableDataType,omitempty"`
	VariableValue           string         `json:"VariableValue,omitempty"`
	EmailSubject            string         `json:"EmailSubject,omitempty"`
	EmailBody               string         `json:"EmailBody,omitempty"`
	PsaTicketTitle          string         `json:"PsaTicketTitle,omitempty"`
	PsaTicketNote           string         `json:"PsaTicketNote,omitempty"`
	PsaTicketDescription    string         `json:"PsaTicketDescription,omitempty"`
	IsPsaTicketNoteInternal bool           `json:"IsPsaTicketNoteInternal,omitempty"`
	PsaIntegrationID        int64          `json:"PsaIntegrationId,omitempty"`
	PsaTicketParameters     []KeyValuePair `json:"PsaTicketParameters,omitempty"`
}

// KeyValuePair is a generic string key/value pair used by several endpoints.
type KeyValuePair struct {
	Key   string `json:"Key"`
	Value string `json:"Value"`
}

// RunWorkflowRequest is the body for POST /automation/workflows/{id}/run.
//
// When DeviceIdentifiers is empty the workflow runs against the configured
// scope. ConstantVariableOverrides only applies to variables registered as
// a separate "Get Device Value > Constant Value" step.
type RunWorkflowRequest struct {
	DeviceIdentifiers         []string           `json:"DeviceIdentifiers,omitempty"`
	WebhookURL                string             `json:"WebhookUrl,omitempty"`
	ConstantVariableOverrides []VariableOverride `json:"ConstantVariableOverrides,omitempty"`
}

// RunWorkflowResult is the response to POST /automation/workflows/{id}/run.
// NewExecutions are the executions created by this call; ExistingExecutions
// are runs already targeting the same devices (no new execution is created
// for those devices until those runs complete).
type RunWorkflowResult struct {
	NewExecutions      []WorkflowExecution `json:"NewExecutions,omitempty"`
	ExistingExecutions []WorkflowExecution `json:"ExistingExecutions,omitempty"`
}

// CancelWorkflowExecutionsRequest cancels one or more workflow executions by ID.
type CancelWorkflowExecutionsRequest struct {
	ExecutionIDs []int64 `json:"ExecutionIds"`
}

// WorkflowService provides access to workflow endpoints under /automation/workflows.
type WorkflowService struct {
	client *Client
	list   listService[Workflow]
}

func newWorkflowService(c *Client) *WorkflowService {
	return &WorkflowService{client: c, list: listService[Workflow]{client: c, path: "/automation/workflows"}}
}

// List retrieves one page of workflows.
func (s *WorkflowService) List(ctx context.Context, q *Query) (*PagedResult[Workflow], error) {
	return s.list.List(ctx, q)
}

// All iterates all workflows across pages.
func (s *WorkflowService) All(ctx context.Context, q *Query) iter.Seq2[Workflow, error] {
	return s.list.All(ctx, q)
}

// Get retrieves a single workflow by ID.
func (s *WorkflowService) Get(ctx context.Context, id int64) (*WorkflowDetails, error) {
	env, err := s.client.do(ctx, http.MethodGet, "/automation/workflows/"+strconv.FormatInt(id, 10), nil)
	if err != nil {
		return nil, err
	}
	return decodeOne[WorkflowDetails](env)
}

// Run triggers execution of the workflow. body may be nil if the workflow
// needs no overrides.
func (s *WorkflowService) Run(ctx context.Context, workflowID int64, body *RunWorkflowRequest) (*RunWorkflowResult, error) {
	var payload any
	if body != nil {
		payload = body
	}
	env, err := s.client.do(ctx, http.MethodPost, "/automation/workflows/"+strconv.FormatInt(workflowID, 10)+"/run", payload)
	if err != nil {
		return nil, err
	}
	return decodeOne[RunWorkflowResult](env)
}

// Executions lists workflow executions (across all workflows). Filter by
// WorkflowId via Query.Filter to scope to a single workflow.
func (s *WorkflowService) Executions(ctx context.Context, q *Query) (*PagedResult[WorkflowExecution], error) {
	return listSub[WorkflowExecution](ctx, s.client, "/automation/workflows/executions", q)
}

// AllExecutions iterates all workflow executions across pages.
func (s *WorkflowService) AllExecutions(ctx context.Context, q *Query) iter.Seq2[WorkflowExecution, error] {
	return allFromList(ctx, func() (*PagedResult[WorkflowExecution], error) {
		return s.Executions(ctx, q)
	})
}

// Execution returns the details of a single workflow execution.
func (s *WorkflowService) Execution(ctx context.Context, executionID int64) (*WorkflowExecutionDetails, error) {
	env, err := s.client.do(ctx, http.MethodGet, "/automation/workflows/executions/"+strconv.FormatInt(executionID, 10), nil)
	if err != nil {
		return nil, err
	}
	return decodeOne[WorkflowExecutionDetails](env)
}

// CancelExecutions cancels the specified workflow executions.
func (s *WorkflowService) CancelExecutions(ctx context.Context, executionIDs ...int64) error {
	if len(executionIDs) == 0 {
		return fmt.Errorf("vsax: at least one execution id is required")
	}
	_, err := s.client.do(ctx, http.MethodPost, "/automation/workflows/executions/cancel",
		CancelWorkflowExecutionsRequest{ExecutionIDs: executionIDs})
	return err
}