Documentation
¶
Overview ¶
Package automation offers tools for building customized Clarify routines. Use the Routines type to build a three structure of named routines, and use the automationcli sub-package for setting up a command-line tool that can match and run these routines by name.
While you could write all your routines from scratch, we provide a few pre-implemented types that you might find useful:
- Routines: Build a three-structure of sub-routines.
- PublishSignals: Define filters that inspect signals in your organization, tracks changes to signal input, and publish them as new or existing items. Apply custom transforms to improve your item meta-data before save.
- EvaluateActions: Run the powerful evaluate method against your Clarify instance to detect conditions and trigger custom actions.
- LogDebug,LogInfo,LogWarn,LogError: Log a message to the console; useful for debugging and testing.
Index ¶
- Constants
- func AttrDataFrame(data views.DataFrame) slog.Attr
- func AttrError(err error) slog.Attr
- type ActionFunc
- type Config
- func (cfg *Config) AppName() string
- func (cfg Config) Client() *clarify.Client
- func (cfg *Config) DryRun() bool
- func (cfg *Config) EarlyOut() bool
- func (cfg *Config) Logger() *slog.Logger
- func (cfg *Config) RoutinePath() string
- func (cfg Config) WithAppName(name string) *Config
- func (cfg Config) WithDryRun(dryRun bool) *Config
- func (cfg Config) WithEarlyOut(value bool) *Config
- func (cfg Config) WithLogger(l *slog.Logger) *Config
- func (cfg Config) WithSubRoutineName(name string) *Config
- type EvaluateActions
- type EvaluateResult
- type Evaluation
- type PublishSignals
- type Routine
- type RoutineFunc
- type Routines
Constants ¶
const ( AnnotationPrefix = "clarify/clarify-go/" AnnotationPublisherName = AnnotationPrefix + "publisher/name" AnnotationPublisherTransformVersion = AnnotationPrefix + "publisher/transform-version" AnnotationPublisherSignalID = AnnotationPrefix + "publisher/signal-id" AnnotationPublisherSignalAttributes = AnnotationPrefix + "publisher/signal-attributes" )
Clarify annotations used by automation routines.
const (
ErrBadConfig strError = "bad configuration"
)
Variables ¶
This section is empty.
Functions ¶
func AttrDataFrame ¶ added in v0.3.0
AttrDataFrame returns a log attribute for data.
Types ¶
type ActionFunc ¶ added in v0.3.0
type ActionFunc func(ctx context.Context, cfg *Config, result *EvaluateResult) bool
ActionFunc describes a function that is run in response to an evaluation. The return value indicates whether the next action in a chain of action should run or not.
Implementations are responsible for handling their own errors and for acting according to the cfg.DryRun() and cfg.EarlyOut() configuration values.
func ActionAnnotate ¶ added in v0.3.0
func ActionAnnotate(key, value string) ActionFunc
ActionAnnotate returns an action that adds an annotation with the passed-in key and value to the result.
func ActionRoutine ¶ added in v0.3.0
func ActionRoutine(r Routine) ActionFunc
ActionRoutine returns a new action function that runs the passed-in routine. If the routine succeed, the action returns true. If it fails, the error is logged and the action returns false.
func ActionSeriesContains ¶ added in v0.3.0
func ActionSeriesContains(series string, value float64) ActionFunc
ActionSeriesContains returns an action that return true if the named series contain at least one instance of value.
type Config ¶ added in v0.3.0
type Config struct {
// contains filtered or unexported fields
}
Config contain configuration for running routines, including a reference to a Clarify Client.
func NewConfig ¶ added in v0.3.0
func NewConfig(client *clarify.Client) *Config
NewConfig returns a new configuration for the passed in clients, using sensible defaults for all optional configuration. This means using slog package default logger, and setting the application name based on the main module's import path.
func (Config) Client ¶ added in v0.3.0
func (cfg Config) Client() *clarify.Client
Client returns the Clarify client contained within options.
func (*Config) DryRun ¶ added in v0.3.0
DryRun returns the value of the dry-run option. When true, routines and actions should not perform write and persist operations.
func (*Config) EarlyOut ¶ added in v0.3.0
EarlyOut returns the value of the early-out option. When true, routines with sub-routines should abort at the first error.
func (*Config) RoutinePath ¶ added in v0.3.0
RoutinePath returns the current routine name path joined by slash (/).
func (Config) WithAppName ¶ added in v0.3.0
WithAppName returns a new configuration with the specified application name. When set, this property is added to the logger. The default app name is the main Go module's declared import path.
func (Config) WithDryRun ¶ added in v0.3.0
WithDryRun returns a new configuration where the dry-run property is set to the specified value.
Dry-run signals routines and actions to not perform any write or persist operations, but instead log the action as if it has been performed.
func (Config) WithEarlyOut ¶ added in v0.3.0
WithEarlyOut returns a new configuration where the early-out property is set to the specified value.
Early-out signals routines with sub-routines to abort at the first error.
func (Config) WithLogger ¶ added in v0.3.0
WithLogger returns a new configuration with the specified logger. If a nil logger is passed in, all logs will be omitted. The default logger is the default logger from the slog package.
func (Config) WithSubRoutineName ¶ added in v0.3.0
WithSubRoutineName returns a new configuration where name is appended to the existing routine path property.
Special cases:
- If name is an empty string then no changes is performed.
type EvaluateActions ¶ added in v0.3.0
type EvaluateActions struct {
// Evaluation contains the evaluations to perform.
Evaluation Evaluation
// TimeFunc is provided the current time, and should return a time range to
// evaluate. If not specified, a default window containing the last hour
// will be evaluated.
TimeFunc func(time.Time) (gte, lt time.Time)
// RollupBucket describe the rollup bucket to use for the evaluation. If not
// specified, a window rollup is used.
RollupBucket fields.CalendarDuration
// Actions describe a chain of functions that are run in order for each
// evaluation result. If an action modifies the evaluation result, this
// change is visible to the next action in the chain. If an action returns
// false, the chain is broken and no further actions are run for the given
// evaluation result.
//
// Actions are responsible for checking opts.DryRun, and for logging their
// own errors.
Actions []ActionFunc
}
EvaluateActions allows running a single evaluation and pass the result onto a chained list of actions.
type EvaluateResult ¶ added in v0.3.0
type EvaluateResult struct {
Annotations fields.Annotations
Data views.DataFrame
}
EvaluateResult describe the result of an evaluation.
type Evaluation ¶ added in v0.3.0
type Evaluation struct {
// Items lists item aggregations for items with known IDs.
Items []fields.ItemAggregation
// Calculations lists calculations to perform. A calculation can reference
// items or previous calculations.
Calculations []fields.Calculation
// SeriesIn filters which series keys (aliases) to return in the server
// result. If the value is nil, all series are returned.
SeriesIn []string
}
Evaluation describe the instruction for performing an evaluation request as well as annotations for passing on to actions.
type PublishSignals ¶
type PublishSignals struct {
// Integrations must list the IDs of the integrations to publish signals
// from. If this list is empty, the rule set is a no-op.
Integrations []string
// SignalsFilter can optionally be specified to limit which signals to
// publish.
SignalsFilter fields.ResourceFilterType
// TransformVersion should be changed if you want existing items to be
// republished despite the source signal being unchanged.
TransformVersion string
// Transforms is a list of transforms to apply when publishing the signals.
// The transforms are applied in order.
Transforms []func(item *views.ItemSave)
}
PublishSignals allows you to automate signal publishing from one or more source integrations. The routine respects the DryRun and EarlyOut configurations.
type Routine ¶ added in v0.3.0
Routine describe the interface for running an arbitrary automation task.
Implementations are responsible for checking cfg.DryRun() and cfg.EarlyOut() values and act appropriately.
type RoutineFunc ¶ added in v0.3.0
The RoutineFunc type is an adapter to allow the use of ordinary functions as automation routines. If f is a function with the appropriate signature, RoutineFunc(f) is a Routine that calls f.
func LogDebug ¶ added in v0.3.0
func LogDebug(msg string, attrs ...slog.Attr) RoutineFunc
LogDebug return a routine that logs the provided message and attributes at debug level.
This routine can be useful for early testing.
func LogError ¶ added in v0.3.0
func LogError(msg string, attrs ...slog.Attr) RoutineFunc
LogError return a routine that logs the provided message and attributes at error level.
This routine can be useful for early testing.
func LogInfo ¶ added in v0.3.0
func LogInfo(msg string, attrs ...slog.Attr) RoutineFunc
LogInfo return a routine that logs the provided message and attributes at info level.
This routine can be useful for early testing.
type Routines ¶ added in v0.3.0
Routines describe a set of named (sub-)routines. Routines can be nested by letting the value be a Routines entry.
For usability reasons, keys are recommended to only contain ASCII alphanumerical characters (0-9, A-Z, a-z), dash (-) and underscore (_).
Keys must not contain the slash (/) or asterisk (*) characters as they hold special meaning during matching. The question mark (?) character should be considered reserved. Keys must also not be empty strings. Failing to follow these restrictions will result in undefined behavior for the SubRoutines method.
func (Routines) Do ¶ added in v0.3.0
Do runs the member routines in an alphanumerical order and assigns correct sub-routine names. If cfg.EarlyOut() returns true, return at the first error. Otherwise log the error and continue.
func (Routines) SubRoutines ¶ added in v0.3.0
SubRoutines returns a sub-set composed of routines that matches the passed in patterns. When routines are nested, the slash character (/) can be used to match nested entries. The asterisk (*) character will match all entries at the given level.
Examples:
- "*", "*/": matches all entries.
- "a" or "a/": Match sub-routine "a" with sub-routines.
- "a/*/b": Match sub-routine "b" for all sub routines of sub-routine "a".
Source Files
Directories