DocumentationWorkfrontWorkfront Guide

Overview of moving objects between Workfront environments (Environment promotion)

Last update: Mon Feb 24 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin

The environment promotion capability allows you to move objects from one Workfront environment to another. For example, you can create a template and configure it in your sandbox environment, knowing that any testing you do will not affect your organization’s actual data. After the template is configured and tested, you can move it to your production environment, ready to use.

This process is referred to as “environment promotion.”

You can perform this process in Workfront by creating a package of objects to move, and then installing that package in the new environment.

View a video demonstration of this feature

Supported objects for environment promotion

The environment promotion capability is intended to provide the ability to move configuration-related object from one environment to another. These are objects that can be configured, such as projects, teams, or custom forms.

Because environment promotion deals with object configuration, transactional objects (objects that change frequently or that are highly dependent on use case) are not included. Examples of transactional objects include documents, issues, requests, updates, and and proof decisions.

Work objects

Promotable object
Included promotable linked objects
Project (PROJ)
Project
Task
Assignment
Predecessor
Company
Override Rate
Group
Role
Team
Approval Process
Approval Path
Approval Step
Step Approver
Schedule
Non Work Day
Queue Definition
Queue Topic Group
Queue Topic
Routing Rule
Milestone Path
Milestone
Hour Type
Resource Pool
Category
Category Parameter
Parameter
Parameter Group
Parameter Option
Category Display Logic
Template (TMPL)
Template
Template Task
Template Task Assignment
Template Task Predecessor
Company
Override Rate
Group
Role
Team
Approval Process
Approval Path
Approval Step
Step Approver
Schedule
Non Work Day
Queue Definition
Queue Topic Group
Queue Topic
Routing Rule
Milestone Path
Milestone
Hour Type
Resource Pool
Category
Category Parameter
Parameter
Parameter Group
Parameter Option
Category Display Logic

Reporting objects

Promotable object
Included promotable linked objects
Layout Template (UITMPL)
Layout Template
Dashboard
Calendar
Calendar Section
External Page
Report
Filter
Grouping
View
Parameter
Group
Dashboard (PTLTAB)
Dashboard
Calendar
Calendar Section
External Page
Report
Filter
Grouping
View
Parameter
Calendar (CALEND)
Calendar
Calendar Section
External Page (EXTSEC)
External Page
Report (PTLSEC)
Report
Filter
Grouping
View
Parameter
Filter (UIFT)
Filter
Parameter
Grouping (UIGB)
Grouping
Parameter
View (UIVW)
View
Parameter

Custom data objects

Promotable object
Included promotable linked objects
Category (CTGY)
Category
Category Parameter
Parameter
Parameter Group
Parameter Option
Category Display Logic
Group
Parameter (PARAM)
Parameter
Parameter Option
Parameter Group (PGRP)
Parameter Group

Organization objects

Promotable object
Included promotable linked objects
Group (GROUP)
Group
Sub-groups (up to 5 levels) *
Category
Category Parameter
Parameter
Parameter Group
Parameter Option
Category Display Logic
Role (ROLE)
Role
Team (TEAM)
Team
Group
Company (CMPY)
Company
Override Rate
Category
Category Parameter
Parameter
Parameter Group
Parameter
Category Display Logic
Group
Portfolio (PORT)
Portfolio
Program
Group
Category
Category Parameter
Parameter
Parameter Group
Parameter Option
Category Display Logic
Program (PRGM)
Program
Portfolio
Group
Category
Category Parameter
Parameter
Parameter Group
Parameter Option
Category Display Logic

Other configuration objects

Promotable object
Included promotable linked objects
Approval Process (ARVPRC)
Approval Process
Approval Path
Approval Step
Step Approver
Role
Team
Group
Schedule (SCHED)
Schedule
Non Work Day
Group
Milestone Path (MPATH)
Milestone Path
Milestone
Timesheet Profile (TSPRO)
Timesheet Profile
Hour Type
Hour Type (HOURT)
Hour Type
Expense Type (EXPTYP)
Expense Type
Risk Type (RSKTYP)
Risk Type
Resource Pool (RSPL)
Resource Pool
Access Level (ACSLVL)
Access Level
Rate Card (RTCRD)
Rate Card
Location / Classifier (CLSF)
Location / Classifier
Business Rules (BSNRUL)
Business Rules

* Not currently available

Environment promotion statuses

Environment promotion packages proceed through several statuses as they are created and prepared to move between environments. You can see these statuses in your list of packages inside Workfront, or in the API responses if you are using the Workfront API.

These statuses include the following:

UNASSEMBLED

This status is automatically assigned, and represents a package that has been saved but not yet assembled.

This status cannot be set by a user directly.

ASSEMBLING

This status is automatically assigned while objects are being assembled.

Assembling refers to the automated process of identifying objects and sub-objects to include in a package, and adding those objects and their data to the package.

This status cannot be set by a user directly.

DRAFT

This status is assigned at the conclusion of an assembly process, or when creating an empty promotion package.

It is possible for a user to move the promotion package back to this status.

While in this status, the promotion package cannot be installed in any environment.

TESTING
This status allows a promotion package to be installed in any Preview or Custom Refresh sandbox. While in this status, the package cannot be installed in Production.
ACTIVE

This status allows a promotion package to be installed in any environment, including Production.

When a package status is set to ACTIVE, the publishedAt date is automatically set to the current timestamp of the request.

DISABLED

This status is used to hide previously used promotion packages that will not be installed into any environment in the future.

When a package is in this status, it cannot be installed into any environment.

When a package status is set to DISABLED, the retiredAt date is automatically set to the current timestamp of the request.

Using this status is recommended over using the DELETE /package endpoint because it is retrievable, and the installation history is retained for any deployments made with this package.

ASSEMBLING_FAILED

The promotion package is automatically put in this status if the ASSEMBLING stage fails.

To return the package to the ASSEMBLING stage, you must trigger the assembling process again.

For details on assembling a package, see the section Edit or assemble an existing package in the article Create or edit an environment promotion package.

Resources

recommendation-more-help
5f00cc6b-2202-40d6-bcd0-3ee0c2316b43