Packages

Packages move a versioned set of workspace artifacts from one workspace to another. Use them for starter kits, reusable features, templates, or maintained building blocks that should receive updates.

A package can include Resources and Fields, selected Records, Workflows, Pages, Components, navigation, workspace settings, Roles, Policies, Media Library assets, and E2E test suites. Installing it creates those artifacts in the target workspace with their references remapped.

Package and release lifecycle

A Package is the container you edit. A Release is a versioned snapshot of its contents.

1. Open Packages and create or select a Package.
2. Choose New release. A Package can have only one draft release per authoring Workspace at a time; use Open draft when one already exists.
3. Select the artifacts and Records the release should contain.
4. Review dependency and policy warnings, then build the release.
5. Publish the release when it is ready to install.

Published releases are immutable. Create a new release for every change. Abandon a draft you no longer intend to publish.

Select complete content

Diagonal follows references between selected artifacts so a release can identify what else it needs. Review the resulting contents rather than assuming one selected Page or Workflow is self-contained.

For example, a Page may reference a Component, Resource, Workflow, File, or navigation item. A Resource may depend on related Resources, Fields, Policies, and capability settings. The release review shows dependencies that must be included or supplied by another package.

You can include selected Records for seed data. Avoid packaging customer or production data unless that data is deliberately reusable.

Choose ownership policies

Package policies decide what an installing workspace can change and what happens during updates. Apply the least restrictive policy that still lets the package remain maintainable.

Before publishing, review policy at both the entity and property level. A Resource might allow local Records while keeping its package-defined Fields managed, for example. The release contents view shows the effective policy for each item.

Install a release

1. Browse available Packages and open the release.
2. Choose Install.
3. Review the install plan. Diagonal identifies new artifacts and possible matches in the target workspace.
4. Resolve each conflict using the choices Diagonal offers:
5. Map uses the existing workspace item as-is and keeps it workspace-owned.
6. Adopt writes the packaged definition onto the existing item and makes it package-managed.
7. Contribute adds the package's parts to a shared item without taking ownership of the rest.
8. Approve the plan to install.

Approval applies to the exact release and target state shown in the plan. If either changes, Diagonal asks you to review again rather than applying a stale plan.

Artifacts install in dependency order and receive target-workspace IDs. Files are copied into the target workspace; the installation never serves them from the source workspace.

Update an installed Package

When a newer release is available, open Manage installation and start the update review.

The update compares three states:

• the release currently installed;
• local workspace changes since installation;
• the new release.

Review each decision point. Package changes that don't conflict with local work can apply directly. When both the workspace and package changed the same managed content, choose which result to keep. The update won't silently overwrite a local conflict.

Content the new release locks is part of the update. You can't skip a change to it, exclude it when it's new, or leave it deleted. Its row shows Locked in place of a choice. You can still keep your own value for a property the package lets you edit.

When the new release ships a newer published version of a workflow or page, the version the previous release shipped stays in that workflow's or page's version history. The package no longer manages it; it reads like a version the workspace published itself.

Publishable artifacts may be created as drafts during installation or update. The result tells you whether content was published immediately, queued for publication, or left with nothing new to publish.

Publish pages and workflows automatically is on by default. It also covers the required Packages that the install or update installs or updates, and the panel names them. Required Packages publish before the Package that uses them. A required Package that is already installed keeps its drafts, and so do your own drafts and the update changes you declined. If publication fails, the failure names the Package. Its content stays installed, so you can publish it from its Package page.

Taking the update for a workflow conflict replaces only the conflicting property. Local edits to other properties stay. To replace the entire workflow, use Reset to package version.

Reset a workflow to the package version

If a workflow that a Package installed stops working in your workspace, you can replace your copy with the version that the installed release ships. You can do this even when the Package locks the workflow.

1. Open the Package and expand Contents.
2. Select the workflow.
3. Select Reset to package version, then confirm.

The reset replaces every change made to the workflow in your workspace: its settings, steps, step inputs, and transitions. Steps added in your workspace are removed, and steps deleted in your workspace come back. A paused workflow becomes active again. Records are not changed.

The reset leaves the workflow as a draft. The live workflow keeps running its last published version until you publish. Select Review and publish to open the workflow.

Availability and library controls

A published release may still be unavailable to a workspace because of listing state, dependency requirements, or which environment holds the package. Each environment publishes to its own registry. Development can install packages from development, staging, and production; staging from staging and production; production from production only. Packages are never promoted between environments.

Each package has one owner workspace, and only the owner can publish its releases. Package authors manage releases in the owner workspace. Diagonal operators manage global library listing and registry synchronization from the Control Panel, and can transfer ownership to another publisher workspace. A published package that another workspace owns goes only to a publisher workspace that has it installed. When the owner workspace is deleted, its published packages stay installable but have no owner until an operator transfers them.

Troubleshooting

• New release is unavailable: open the existing draft or abandon it before starting another.
• Install requires decisions: the target already contains a possible match or conflicting key. Review the artifact details; don't match unrelated artifacts just to clear the warning.
• Plan became stale: the release or target workspace changed after review. Rebuild and approve the current plan.
• Local edit is disabled: the installed package's effective policy manages that entity or property.
• Update isn't offered: confirm a newer compatible release is published, listed for the workspace's environment, and satisfies package dependencies.