import_module

package
v0.2.19 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	BlueprintConcurrency = 5
	EntityConcurrency    = 20
	DefaultConcurrency   = 10
)

Concurrency limits for different resource types

View Source 
const RuleResultTargetRelationType = "rule_result_target"

RuleResultTargetRelationType is the Port blueprint relation type for scorecard rule result catalog targets.

Variables

View Source 
var DependentFields = []string{
	"mirrorProperties",
	"calculationProperties",
	"aggregationProperties",

	"ownership",
}

DependentFields are blueprint fields that may reference other blueprints. Note: "relations" is NOT included because the relation schema must be created with the blueprint - you can't add relations to a blueprint after creation. The topological sort ensures relation targets exist before blueprint creation.

Functions

func BlueprintWithRelations added in v0.2.10 

func BlueprintWithRelations(bp api.Blueprint, kept map[string]interface{}) api.Blueprint

BlueprintWithRelations returns a shallow copy of bp with relations replaced by kept (or relations removed if kept is nil or empty).

func BuildExistingBlueprintsSet added in v0.1.3 

func BuildExistingBlueprintsSet(additionalExisting []string) map[string]bool

BuildExistingBlueprintsSet creates a set of blueprint identifiers that are considered "existing". This includes system blueprints and any explicitly provided identifiers.

func CleanActionForCreate added in v0.1.11 

func CleanActionForCreate(action api.Action) api.Action

CleanActionForCreate returns a copy of the action with audit fields removed.

func CleanFolderForCreate added in v0.1.15 

func CleanFolderForCreate(folder api.Folder) api.Folder

func CleanPageForCreate added in v0.1.11 

func CleanPageForCreate(page api.Page) api.Page

CleanPageForCreate returns a copy of page with audit/internal fields removed. Sidebar placement fields are preserved, but requiredQueryParams is stripped because Port rejects it for some page types on create.

func CleanPageForCreateNoNav added in v0.1.11 

func CleanPageForCreateNoNav(page api.Page) api.Page

CleanPageForCreateNoNav is like CleanPageForCreate but also strips navigation fields (after, sidebar, parent, section, requiredQueryParams). Used as a fallback when the target org is missing the sidebar parent.

func CleanPageForUpdate added in v0.1.11 

func CleanPageForUpdate(page api.Page) api.Page

CleanPageForUpdate returns a copy of page with audit/internal fields and `type` removed. Navigation fields are kept so Port can move the page to the correct sidebar position, except requiredQueryParams and sidebar which are stripped by default because Port rejects them for some page types on update. Nav fields that are nil/null are also stripped — sending null would clear the page's existing navigation context in Port.

func CleanPageForUpdateNoNav added in v0.1.12 

func CleanPageForUpdateNoNav(page api.Page) api.Page

CleanPageForUpdateNoNav is the fallback for CleanPageForUpdate when Port rejects the update because the parent page doesn't exist in the target org.

func CommonSystemBlueprints added in v0.1.3 

func CommonSystemBlueprints() []string

CommonSystemBlueprints returns identifiers of commonly available system blueprints.

func CreateBlueprintWithRelations 

func CreateBlueprintWithRelations(identifier string, relations map[string]interface{}) api.Blueprint

CreateBlueprintWithRelations creates a blueprint payload with only the relations field. This is used for the second pass update.

func DescribeSidebarPipeline added in v0.1.15 

func DescribeSidebarPipeline(steps []SidebarPipelineStep) []string

func ExtractDependentFields added in v0.1.3 

func ExtractDependentFields(bp api.Blueprint) map[string]interface{}

ExtractDependentFields extracts all dependent fields from a blueprint. Returns a map of field name to field value for fields that were present.

func ExtractEntityRelations added in v0.1.3 

func ExtractEntityRelations(entity api.Entity) map[string]interface{}

ExtractEntityRelations extracts the relations field from an entity.

func ExtractRelations 

func ExtractRelations(bp api.Blueprint) map[string]interface{}

ExtractRelations extracts the relations field from a blueprint.

func FlattenLevels added in v0.1.3 

func FlattenLevels(levels [][]api.Blueprint) []api.Blueprint

FlattenLevels converts leveled blueprints to a flat slice in dependency order.

func GetAllDependencies added in v0.1.3 

func GetAllDependencies(bp api.Blueprint) []string

GetAllDependencies extracts all blueprint identifiers that this blueprint depends on. This includes targets from relations, mirrorProperties, calculationProperties, and aggregationProperties.

func HasEntityRelations added in v0.1.3 

func HasEntityRelations(entity api.Entity) bool

HasEntityRelations checks if an entity has any relation values set.

func IsAdditionalPropertyError added in v0.1.13 

func IsAdditionalPropertyError(err error) bool

IsAdditionalPropertyError is the exported form for use by the migrate package.

func IsAfterItemNotInParent added in v0.1.11 

func IsAfterItemNotInParent(err error) bool

IsAfterItemNotInParent returns true when Port rejects page creation because the `after` sibling item doesn't exist inside the specified parent folder.

func IsAgentIdentifierError added in v0.1.11 

func IsAgentIdentifierError(err error) bool

IsAgentIdentifierError returns true when the Port API rejects a request because a widget is missing the required agentIdentifier field.

func IsInvalidPermissionsError added in v0.2.18 

func IsInvalidPermissionsError(err error) bool

IsInvalidPermissionsError is the exported form for use by the migrate package.

func IsRelationError 

func IsRelationError(err error) bool

IsRelationError checks if an error is related to missing relation targets. This detects common error patterns from the Port API when a relation target doesn't exist.

func IsSidebarParentNotFound added in v0.1.11 

func IsSidebarParentNotFound(err error) bool

IsSidebarParentNotFound is the exported form for use by the migrate package.

func IsSystemBlueprint added in v0.1.3 

func IsSystemBlueprint(identifier string) bool

IsSystemBlueprint returns true if the blueprint identifier indicates a system blueprint. System blueprints start with underscore (_user, _team, _rule, etc.)

func MergeWidgetAgentIdentifiers added in v0.1.11 

func MergeWidgetAgentIdentifiers(newWidgets, existingWidgets []interface{}) []interface{}

MergeWidgetAgentIdentifiers copies agentIdentifier values from existing widgets into new widgets so that Port's required-field validation passes.

func ParseInvalidPermissionFields added in v0.2.18 

func ParseInvalidPermissionFields(err error) (relations, properties []string)

ParseInvalidPermissionFields extracts the invalidRelations and invalidProperties arrays from an invalid_permissions API error. Returns nil slices when the error is not parseable or not an invalid_permissions error.

func PartitionBlueprintRelationsRuleResultTarget added in v0.2.10 

func PartitionBlueprintRelationsRuleResultTarget(rels map[string]interface{}) (kept map[string]interface{}, ignoredKeys []string)

PartitionBlueprintRelationsRuleResultTarget splits blueprint relations into kept vs ignored. A relation is ignored when its definition map has type rule_result_target (Port-managed). ignoredKeys is sorted lexicographically for stable tests and CLI output.

func SanitizePermissions added in v0.2.18 

func SanitizePermissions(perms api.Permissions, invalidRelations, invalidProperties []string) api.Permissions

SanitizePermissions returns a deep copy of perms with the named relation and property keys removed. Invalid relations are stripped from top-level keys and from entities.updateRelations; invalid properties are stripped from top-level keys and from entities.updateProperties.

func SeparateSystemBlueprints added in v0.1.3 

func SeparateSystemBlueprints(blueprints []api.Blueprint) (nonSystem, system []api.Blueprint)

SeparateSystemBlueprints splits blueprints into system and non-system blueprints.

func SortFoldersByAfterLevels added in v0.1.15 

func SortFoldersByAfterLevels(folders []api.Folder) [][]api.Folder

func SortPagesByAfterDeps added in v0.1.13 

func SortPagesByAfterDeps(pages []api.Page) []api.Page

SortPagesByAfterDeps is the exported version of sortPagesByAfterDeps for use by migrate.

func StripDependentFields added in v0.1.3 

func StripDependentFields(bp api.Blueprint) api.Blueprint

StripDependentFields creates a copy of the blueprint without any dependent fields.

func StripEntityRelations added in v0.1.3 

func StripEntityRelations(entity api.Entity) api.Entity

StripEntityRelations creates a copy of the entity without the relations field.

func StripRelations 

func StripRelations(bp api.Blueprint) api.Blueprint

StripRelations creates a copy of the blueprint without the relations field.

func TopologicalSort added in v0.1.3 

func TopologicalSort(blueprints []api.Blueprint, existingBlueprints map[string]bool) ([][]api.Blueprint, []api.Blueprint)

TopologicalSort sorts blueprints in dependency order using Kahn's algorithm. Returns blueprints grouped by dependency level (level 0 has no dependencies, etc.) Also returns any blueprints involved in cycles (which couldn't be sorted).

func TopologicalSortAggProps added in v0.2.7 

func TopologicalSortAggProps(storedAggProps map[string]map[string]interface{}) [][]string

TopologicalSortAggProps sorts blueprint IDs by their cross-blueprint aggregation property dependencies. If blueprint A has an agg prop that targets blueprint B and references a property that is itself an agg prop on B, A must run after B. Returns levels where blueprints in the same level can be applied concurrently.

func TopologicalSortOwnership added in v0.1.14 

func TopologicalSortOwnership(blueprints []api.Blueprint) ([][]api.Blueprint, []api.Blueprint)

TopologicalSortOwnership sorts blueprints with ownership in the order their ownership can be applied. Blueprints with direct ownership are in the first level. Blueprints with inherited ownership depend on the target blueprint of the first relation segment in their ownership path.

func ValidateAllDependencies added in v0.1.3 

func ValidateAllDependencies(bp api.Blueprint, existingBlueprints map[string]bool) []string

ValidateAllDependencies checks if all dependencies exist in the provided blueprint set.

func ValidateRelationTargets 

func ValidateRelationTargets(bp api.Blueprint, existingBlueprints map[string]bool) []string

ValidateRelationTargets checks if all relation targets exist in the provided blueprint set.

Types

type BatchProcessor added in v0.1.3 

type BatchProcessor[T any] struct {
	// contains filtered or unexported fields
}

BatchProcessor processes items in batches with bounded concurrency.

func NewBatchProcessor added in v0.1.3 

func NewBatchProcessor[T any](concurrency int) *BatchProcessor[T]

NewBatchProcessor creates a processor for batch operations.

func (*BatchProcessor[T]) Process added in v0.1.3 

func (bp *BatchProcessor[T]) Process(items []T, fn func(T) error) []BatchResult[T]

Process processes all items using the provided function. Returns results in the order items were processed (not necessarily submission order).

func (*BatchProcessor[T]) ProcessWithContext added in v0.1.3 

func (bp *BatchProcessor[T]) ProcessWithContext(ctx context.Context, items []T, fn func(T) error) []BatchResult[T]

ProcessWithContext processes items with context cancellation support.

func (*BatchProcessor[T]) SetProgressCallback added in v0.1.3 

func (bp *BatchProcessor[T]) SetProgressCallback(cb func(processed, total int))

SetProgressCallback sets a callback for progress updates.

type BatchResult added in v0.1.3 

type BatchResult[T any] struct {
	Item  T
	Error error
}

BatchResult holds the result of processing a single item.

type DiffComparer 

type DiffComparer struct {
	// contains filtered or unexported fields
}

DiffComparer compares import data with current organization state.

func NewDiffComparer 

func NewDiffComparer(client *api.Client) *DiffComparer

NewDiffComparer creates a new diff comparer.

func (*DiffComparer) Compare 

func (d *DiffComparer) Compare(ctx context.Context, importData *export.Data, opts Options) (*DiffResult, error)

Compare compares import data with current organization state.

type DiffResult 

type DiffResult struct {
	BlueprintsToCreate   []api.Blueprint
	BlueprintsToUpdate   []api.Blueprint
	BlueprintsToSkip     []api.Blueprint
	EntitiesToCreate     []api.Entity
	EntitiesToUpdate     []api.Entity
	EntitiesToSkip       []api.Entity
	ScorecardsToCreate   []api.Scorecard
	ScorecardsToUpdate   []api.Scorecard
	ScorecardsToSkip     []api.Scorecard
	ActionsToCreate      []api.Action
	ActionsToUpdate      []api.Action
	ActionsToSkip        []api.Action
	TeamsToCreate        []api.Team
	TeamsToUpdate        []api.Team
	TeamsToSkip          []api.Team
	UsersToCreate        []api.User
	UsersToUpdate        []api.User
	UsersToSkip          []api.User
	PagesToCreate        []api.Page
	PagesToUpdate        []api.Page
	PagesToSkip          []api.Page
	IntegrationsToUpdate []api.Integration
	IntegrationsToSkip   []api.Integration
	BlueprintPermissions []PermissionsChange
	ActionPermissions    []PermissionsChange
	PagePermissions      []PermissionsChange
}

DiffResult represents the result of comparing import data with current state.

func (*DiffResult) FilterData 

func (d *DiffResult) FilterData(original *export.Data) *export.Data

FilterData filters import data to only include resources that need to be created or updated.

type ErrorCategory added in v0.1.3 

type ErrorCategory string

ErrorCategory represents the type of error encountered during import. 

const (
	// ErrDependency indicates a missing blueprint/entity reference.
	// These errors may resolve after dependencies are created.
	ErrDependency ErrorCategory = "DEPENDENCY"

	// ErrAuth indicates authentication or permission issues.
	ErrAuth ErrorCategory = "AUTH"

	// ErrBlueprintConfig indicates blueprint configuration prevents the operation.
	// E.g., inherited ownership enabled, protected blueprints, etc.
	ErrBlueprintConfig ErrorCategory = "BLUEPRINT_CONFIG"

	// ErrValidation indicates invalid data format or values.
	ErrValidation ErrorCategory = "VALIDATION"

	// ErrSchemaMismatch indicates entity data doesn't match blueprint schema.
	ErrSchemaMismatch ErrorCategory = "SCHEMA_MISMATCH"

	// ErrRateLimit indicates the API throttled the request.
	ErrRateLimit ErrorCategory = "RATE_LIMIT"

	// ErrNetwork indicates connection or network issues.
	ErrNetwork ErrorCategory = "NETWORK"

	// ErrConflict indicates the resource already exists.
	ErrConflict ErrorCategory = "CONFLICT"

	// ErrNotFound indicates the resource was not found.
	ErrNotFound ErrorCategory = "NOT_FOUND"

	// ErrServerError indicates the API returned a 5xx server-side error.
	ErrServerError ErrorCategory = "SERVER_ERROR"

	// ErrUnknown indicates an unexpected error.
	ErrUnknown ErrorCategory = "UNKNOWN"
)

type ErrorCollector added in v0.1.3 

type ErrorCollector struct {
	// contains filtered or unexported fields
}

ErrorCollector collects and categorizes errors during import.

func NewErrorCollector added in v0.1.3 

func NewErrorCollector() *ErrorCollector

NewErrorCollector creates a new error collector.

func (*ErrorCollector) Add added in v0.1.3 

func (ec *ErrorCollector) Add(err error, resourceType, resourceID string)

Add adds an error to the collector.

func (*ErrorCollector) AddImportError added in v0.1.3 

func (ec *ErrorCollector) AddImportError(ie *ImportError)

AddImportError adds a pre-categorized ImportError.

func (*ErrorCollector) All added in v0.1.3 

func (ec *ErrorCollector) All() []*ImportError

All returns all collected errors.

func (*ErrorCollector) Clear added in v0.1.3 

func (ec *ErrorCollector) Clear()

Clear removes all collected errors.

func (*ErrorCollector) Count added in v0.1.3 

func (ec *ErrorCollector) Count() int

Count returns the total number of errors.

func (*ErrorCollector) CountByCategory added in v0.1.3 

func (ec *ErrorCollector) CountByCategory(cat ErrorCategory) int

CountByCategory returns the count of errors for a category.

func (*ErrorCollector) GetByCategory added in v0.1.3 

func (ec *ErrorCollector) GetByCategory(cat ErrorCategory) []*ImportError

GetByCategory returns errors for a specific category.

func (*ErrorCollector) GetByResource added in v0.1.3 

func (ec *ErrorCollector) GetByResource(resourceType string) []*ImportError

GetByResource returns errors for a specific resource type.

func (*ErrorCollector) GetRetryable added in v0.1.3 

func (ec *ErrorCollector) GetRetryable() []*ImportError

GetRetryable returns all errors that are retryable.

func (*ErrorCollector) HasErrors added in v0.1.3 

func (ec *ErrorCollector) HasErrors() bool

HasErrors returns true if any errors were collected.

func (*ErrorCollector) Summary added in v0.1.3 

func (ec *ErrorCollector) Summary(maxExamplesPerCategory int) string

Summary returns a human-readable summary of errors. Shows count + first N examples per category.

func (*ErrorCollector) ToStringSlice added in v0.1.3 

func (ec *ErrorCollector) ToStringSlice() []string

ToStringSlice converts errors to a simple string slice (for backward compatibility).

type ImportError added in v0.1.3 

type ImportError struct {
	Category     ErrorCategory
	ResourceType string // "blueprint", "entity", "action", etc.
	ResourceID   string // identifier of the resource
	Message      string
	Cause        error
	Retryable    bool
}

ImportError represents a categorized error from an import operation.

func CategorizeError added in v0.1.3 

func CategorizeError(err error, resourceType, resourceID string) *ImportError

CategorizeError analyzes an error and returns an ImportError with appropriate category.

func (*ImportError) Error added in v0.1.3 

func (e *ImportError) Error() string

type Importer 

type Importer struct {
	// contains filtered or unexported fields
}

Importer handles importing data to Port with proper dependency ordering.

func NewImporter 

func NewImporter(client *api.Client) *Importer

NewImporter creates a new importer.

func (*Importer) Import 

func (i *Importer) Import(ctx context.Context, data *export.Data, opts Options) (*Result, error)

Import imports data to Port with proper dependency ordering.

func (*Importer) SetLogCallback added in v0.1.16 

func (i *Importer) SetLogCallback(cb func(string))

func (*Importer) SetProgressCallback added in v0.1.3 

func (i *Importer) SetProgressCallback(cb ProgressCallback)

SetProgressCallback sets the progress callback for the importer.

type Loader 

type Loader struct{}

Loader loads data from tar.gz or JSON files.

func NewLoader 

func NewLoader() *Loader

NewLoader creates a new loader.

func (*Loader) LoadData 

func (l *Loader) LoadData(inputPath string) (*export.Data, error)

LoadData loads data from a file (tar.gz or JSON).

func (*Loader) ValidateData 

func (l *Loader) ValidateData(data *export.Data) error

ValidateData validates the loaded data structure.

type Module 

type Module struct {
	// contains filtered or unexported fields
}

Module handles importing data to Port.

func NewModule 

func NewModule(token *auth.Token, orgConfig *config.OrganizationConfig) *Module

NewModule creates a new import module.

func (*Module) Close 

func (m *Module) Close() error

Close closes the API client.

func (*Module) Execute 

func (m *Module) Execute(ctx context.Context, opts Options) (*Result, error)

Execute performs the import operation.

type Options 

type Options struct {
	InputPath              string
	DryRun                 bool
	SkipEntities           bool
	SkipSystemBlueprints   bool // skip _* blueprint schemas and their entities
	IncludeRuleResults     bool // include _rule_result system blueprint entities (included by default)
	IncludeResources       []string
	ExcludeBlueprints      []string // deep: exclude blueprint schema + all its resources
	ExcludeBlueprintSchema []string // shallow: exclude only the blueprint schema, keep resources
	Verbose                bool
	ShowPagesPipeline      bool
	ProgressCallback       ProgressCallback
	LogCallback            func(string)
}

Options represents import options.

type PermissionsChange added in v0.1.7 

type PermissionsChange struct {
	Identifier  string
	Permissions api.Permissions
}

PermissionsChange represents a permissions update for a single resource.

type ProgressCallback added in v0.1.3 

type ProgressCallback func(phase string, current, total int)

Options represents import options. ProgressCallback is called to report import progress. phase is the current phase name, current is the number of items processed, total is the total count.

type Result 

type Result struct {
	Success                     bool
	Message                     string
	BlueprintsCreated           int
	BlueprintsUpdated           int
	EntitiesCreated             int
	EntitiesUpdated             int
	ScorecardsCreated           int
	ScorecardsUpdated           int
	ActionsCreated              int
	ActionsUpdated              int
	TeamsCreated                int
	TeamsUpdated                int
	UsersCreated                int
	UsersUpdated                int
	PagesCreated                int
	PagesUpdated                int
	IntegrationsUpdated         int
	BlueprintPermissionsUpdated int
	ActionPermissionsUpdated    int
	PagePermissionsUpdated      int
	Errors                      []string
	ErrorsByCategory            map[string][]string // Categorized errors for verbose output
	Warnings                    []ValidationWarning // Pre-import validation warnings
	DiffResult                  *DiffResult
	SidebarPipeline             []string
	// IgnoredRuleResultTargetRelationCount is how many _rule_result relations with type rule_result_target were omitted from API payloads.
	IgnoredRuleResultTargetRelationCount int
	// IgnoredRuleResultTargetRelationKeys lists relation identifiers omitted (sorted, unique).
	IgnoredRuleResultTargetRelationKeys []string
}

Result represents the result of an import operation.

type SidebarPipelineOperation added in v0.1.15 

type SidebarPipelineOperation struct {
	ResourceType string
	Identifier   string
	Folder       api.Folder
	Page         api.Page
}

type SidebarPipelineStep added in v0.1.15 

type SidebarPipelineStep struct {
	Operations []SidebarPipelineOperation
}

func PlanSidebarPipeline added in v0.1.15 

func PlanSidebarPipeline(folders []api.Folder, pages []api.Page) []SidebarPipelineStep

type ValidationWarning added in v0.1.3 

type ValidationWarning struct {
	Type    string // "cycle", "missing_dependency", "protected_resource", "orphaned_permission_field"
	Message string
	Details []string
}

ValidationWarning represents a pre-import validation warning.

type WorkerPool added in v0.1.3 

type WorkerPool struct {
	// contains filtered or unexported fields
}

WorkerPool provides bounded concurrency for parallel operations. Unlike errgroup.WithContext, individual task failures don't cancel other tasks.

func NewWorkerPool added in v0.1.3 

func NewWorkerPool(limit int) *WorkerPool

NewWorkerPool creates a worker pool with the specified concurrency limit.

func (*WorkerPool) Go added in v0.1.3 

func (p *WorkerPool) Go(task func())

Go submits a task to the worker pool. The task will run when a worker slot is available. Tasks run in separate goroutines and errors are handled by the task itself.

func (*WorkerPool) GoWithContext added in v0.1.3 

func (p *WorkerPool) GoWithContext(ctx context.Context, task func())

GoWithContext submits a task that respects context cancellation. Returns immediately if context is already canceled.

func (*WorkerPool) Wait added in v0.1.3 

func (p *WorkerPool) Wait()

Wait blocks until all submitted tasks complete.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.