Importing Benefits

An integration with the Import Data Type Benefits creates benefits from an Excel spreadsheet, and updates benefits that already exist. Each row is one benefit: its name, classification, owner, start and end dates, unit, reporting cadence and the initiative it belongs to, and optionally its plan value, contributing measures, custom fields and team roles. The integration is set up from the initiative's Tools > Integrations, by clicking New Integration, leaving the Adapter as Excel, and selecting Benefits as the Import Data Type. Where your instance calls benefits Impacts, these labels read Impacts instead.

This article covers both the Advanced and Simple Models. It needs the Integrations permission on the initiative, as set out in Before you start. On the Simple Model, each benefit belongs to a project of the program. Importing the values of benefits that already exist is a separate import. See Importing Benefit Values.

This is different from Administration > Integrations, which connects third-party applications. See Connecting a Third-Party Application.

Before you start

Who can import

Importing needs both of the following:

• Enable Integrations turned on for the initiative. On the Advanced Model, it is a setting on the initiative's classification, under General Configuration. See Configuring Initiative Classifications (Advanced Model). On the Simple Model, it is in the Integrations section of the program's Configuration > Features. See Program Features.
• The Integrations permission set to Full on a team role held on the initiative. See Team Roles. A Full Admin, or a user whose admin role sets Hierarchy to Full, can import without a team role. See Admin Roles.

Where either is missing, Integrations isn't offered under Tools.

What must exist first

The import doesn't create anything other than the benefits. Set up the following before importing:

• Initiatives for the benefits to belong to — every initiative a row names must already exist, and its classification must have benefits turned on. See Where each benefit is placed.
• Benefit classifications — each benefit's classification must exist and be active, and the classification of the initiative it belongs to must allow it as a benefit type. See Configuring Benefit Classifications (Advanced Model). A classification that can't be created under that initiative's classification is refused.
• Owners — each owner must be an existing, unlocked user, and not a guest user. On the Simple Model, the owner must also be on the Program team.
• Units — each unit named in the sheet must exist.
• Contributing measures — for a benefit that has a Benefit Formula, every measure it uses must exist. See Contributing measures.
• Custom fields — a custom field must be mapped to the classification to be filled in, and any option a cell names must exist. See Custom Fields (Advanced Model) or Custom Fields (Simple Model).
• Team roles — only where the sheet has columns for them.

Where to set up the integration

Set the integration up on the highest initiative that holds every initiative the benefits belong to. Benefits can only be created, or updated, at or below the initiative the integration is set up on. Anything outside it is refused, not moved. On the Simple Model, set it up on the program. A project has no Integrations menu.

File limits

• The file is an Excel file (.xlsx) of 5 MB or less.
• The sheet has up to 2,000 rows. The row of column headings isn't counted where Header? is selected. A sheet with more can't be run, so split it into several sheets or files.
• Only one sheet is read each time the integration runs. The sheet is chosen when the file is uploaded.

Preparing the spreadsheet

Put one benefit on each row, with a column for each field. A row of column headings at the top makes mapping easier. The columns can be in any order, but each integration remembers the mapping by column position, so keep the order the same from one run to the next.

Where each benefit is placed

Every benefit belongs to an initiative. Each row names it in a column mapped as Parent Initiative. On the Simple Model, it is the project of the program the benefit belongs to.

• The initiative must already exist when the import runs. It must be the initiative the integration is set up on or one beneath it.
• The initiative's classification must have benefits turned on, and must allow the row's classification.
• A benefit can't be moved to another initiative by a later import.

Columns to create benefits

A created benefit needs all of the following:

• Parent Initiative — the initiative the benefit belongs to. It can be matched on its name, Amplify ID or External ID.
• Name — a name longer than 120 characters is shortened.
• Classification — matched on the classification's name or ID.
• Owner — matched on the user's name, email or ID.
• Start Date and End Date — see Dates and reporting cadence.
• Unit — the unit the benefit is measured in, matched on its name or ID.
• Resolution — how often the benefit's values are reported. Enter MONTH, QUARTER or FINANCIAL_YEAR.

Where the classification has required custom fields, include a column for each. A row that leaves one blank isn't created. A benefit whose classification has a Benefit Formula also needs its contributing measures.

Columns to update benefits

To update benefits that already exist, include one column that identifies each benefit: its ID or its External ID. The other columns hold the fields to change. See Updating benefits later.

Optional columns

• External ID — a reference from another system. It must be unique across benefits, and it can be used later to find the benefit again. It is set only through the Identifier Lookup column.
• Description — text for the benefit's description.
• Weight — a number from 0.1 to 100. A created benefit without one has a weight of 1.
• This is a negative Benefit — TRUE or FALSE. A created benefit without one isn't negative.
• This Benefit is Cumulative — TRUE or FALSE. A created benefit without one takes the classification's default.
• This Benefit has Dual View and Display On Dashboard — TRUE or FALSE.
• Plan value — one value for the benefit's plan, set when the benefit is created. See Setting a plan value.
• Contributing measures and Formula — for a benefit that has a Benefit Formula.
• Custom fields — one column for each custom field mapped to the classification.
• Team roles — one column for each team role, holding the user to add to the benefit's team.

Each of Classification, Owner, Parent Initiative, Identifier Lookup, Unit and Contributing Measures can be mapped to one column only. Each attribute, custom field, team role and plan value can also be mapped once.

Dates and reporting cadence

Enter dates in a format that gives the year, month and day unambiguously, such as 2026-03-01. A cell that isn't a date shows a red icon.

• Start Date — for a created benefit, the first day of a month.
• End Date — for a created benefit, the last day of a month. It must be later than the start date.

A created benefit with any other day is refused, not moved. In an update, a start date is moved to the first day of its month, and an end date to the last day of its month.

The Resolution sets which months a benefit can start and end in. Quarters and financial years follow the instance's financial year end. For example, where the financial year ends on 30 June, it starts in July and the quarters start in July, October, January and April.

• MONTH — any month.
• QUARTER — the start date is the first day of a quarter and the end date is the last day of a quarter.
• FINANCIAL_YEAR — the start date is the first day of the financial year and the end date is the last day of the financial year.

Where the classification locks the Resolution, the locked value is used and the cell shows an amber warning. Where it locks the dates, the cell shows an amber warning too.

Creating the integration

To create the integration:

1. Open the initiative the integration is set up on.
2. Navigate to Tools > Integrations. The initiative's integrations are listed.
3. Click New Integration.
4. Enter a Name for the integration.
5. Select Benefits as the Import Data Type.
6. Click Create.

The Adapter is always Excel.

Uploading the spreadsheet

To upload the spreadsheet:

1. On the initiative's integrations, click Run... next to the integration. A window opens.
2. Where the integration has been run before, select Upload New to choose a file, or Use Previous to use the last file again.
3. Choose the file.
4. Select Header? where the first row holds column headings.
5. Select the Sheet that holds the benefits.
6. Click Continue. The session page opens, with the rows from the sheet.

The file must be an Excel file (.xlsx) of 5 MB or less, and the sheet can't exceed the row limit. Otherwise a message says so and Continue stays disabled. Only the last file uploaded is kept.

The session page runs a preview straight away. Map the columns as described in Mapping the columns, then click Preview again to check the mapping.

Mapping the columns

The columns are mapped on the session page that opens once the spreadsheet is uploaded. To map the columns:

1. Click Edit Mapping. A header appears above each column.
2. Select the Type for a column.
3. Set the fields that appear for that type.
4. Repeat for each column that is imported.

The mapping saves as you go. It is kept on the integration and applies by column position the next time the integration runs. A column left as No Action is ignored. A green tick on a column header means its mapping is valid. A red icon means it isn't, and hovering over it shows why.

Mapping types

• Attribute Assignment — puts the value into one of the benefit's fields, chosen from the Attribute list: Name, Description, Weight, Start Date, End Date, Resolution, Formula, This is a negative Benefit, This Benefit is Cumulative, This Benefit has Dual View and Display On Dashboard. Name, Start Date, End Date and Resolution are required to create, once each, and are marked Required:. Fields that Amplify calculates or controls elsewhere, such as totals, progress, status and the benefit's active and confidential settings, aren't in the list.
• Parent Initiative — matches the initiative a created benefit belongs to. Required to create.
• Classification — matches the classification of a created benefit. Required to create.
• Owner — matches a user as the benefit's owner. Required to create.
• Unit — matches the unit the benefit is measured in. Required to create.
• Identifier Lookup — finds an existing benefit to update. For a created benefit, the value becomes its External ID.
• Measure Series — sets a plan value on a created benefit, chosen from the Series list.
• Contributing Measures — names the measures that feed a benefit that has a Benefit Formula.
• Custom Field — puts the value into a custom field, chosen from the Custom Field list.
• Team Role — adds a user to the benefit's team in the role chosen in Team Role.
• No Action — leaves the column out of the import.

The session shows whether the mapping can create and update benefits. Where it can't create, it lists the columns still needed. Until the mapping can either create or update, a message says the minimum requirement hasn't been met, and Preview and Import... are disabled.

Match on Attribute and fallbacks

For a column that is matched to existing records, Match on Attribute sets which field of the record the cell is compared with.

• Parent Initiative — Name, Amplify ID or External ID. Matching on Name looks only at the integration's initiative and the initiatives beneath it.
• Classification — Name or ID.
• Owner — Name, Email or ID.
• Unit — Name or ID.
• Identifier Lookup — ID or External ID.
• Contributing Measures — External ID or Measure Id.
• Team Role — the user's Name or Email.
• Custom Field — Value or Label, for a custom field with a list of options. Choose whether the cell holds the option's value or the label shown on screen. For a custom field that holds users, the choice is ID or Name.

A fallback gives a row a default when its cell is blank or has no match, so the row isn't skipped. A row that uses a fallback shows an amber warning.

• Fallback to Default Initiative — places the row under the Default Initiative you choose. It must be at or below the initiative the integration is set up on.
• Fallback to Default Classification — uses the Default Classification you choose. The default must still be allowed under the initiative the row belongs to.
• Fallback to Default User — uses the Default User you choose as the owner, or as the team member for a Team Role column.
• Fallback to Default Unit — uses the Default Unit you choose.

Without a fallback, a row whose initiative, classification, owner or unit isn't found isn't created. Capital letters and spaces around the value are ignored.

Unit

Map a column as Unit, and choose whether the cell holds the unit's Name or ID. Only one Unit column can be mapped. Where the classification locks the unit, the locked unit is used, and a cell that names another unit shows an amber warning.

Setting a plan value

A Measure Series column sets the plan of a benefit when it is created. It gives one value for the benefit, not a value for each period. To set the plan period by period, import the values afterwards. See Importing Benefit Values.

To set a plan value:

1. Select Measure Series as the Type of the column.
2. Select the plan value in Series. The list is grouped by benefit classification, and shows Plan Value under a classification without a Benefit Formula.

• Map one column for each entry in the list. Each can be mapped once.
• Choose the entry that belongs to the same classification as the row. Where a row has another classification, the value isn't used and the cell shows a warning.
• A blank cell, or a cell that isn't a number, shows a warning and the classification's default is used.
• Where the plan is locked, the value isn't used and the cell shows a warning. A plan is locked where the classification has Prevent modifications to the Plan turned on, or where the initiative's stage gate process locks plan values.
• An update doesn't change a plan value. The column is skipped with a warning.

Contributing measures

A benefit whose classification has a Benefit Formula is calculated from measures, and has no values of its own. Each created benefit of this kind needs the measures that feed it, and a formula that uses them. For how formulas work, see Managing Benefits. For measures, see Managing Measures.

The measures must exist before the import. To create measures from a spreadsheet, see Importing Measures.

To map the measures and the formula:

1. Select Contributing Measures as the Type of the column that lists the measures.
2. Select the Match on Attribute, either External ID or Measure Id.
3. Select Attribute Assignment as the Type of the column that holds the formula.
4. Select Formula as the Attribute.

• List the measures in one cell, separated by commas. A Measure Id can be written with or without the letter M, such as M22 or 22.
• Write the formula with the same identifiers, such as M22 + M25, or with the External IDs. Every measure in the formula must be in the list, and every measure in the list must be in the formula.
• Only one Contributing Measures column can be mapped.
• The measures are found among the measures of the initiative the benefit belongs to, and the measures held at the enterprise level. A measure that isn't found fails the row.
• Each measure must cover the benefit's start and end dates, and the benefit's Resolution can't be more precise than its measures'.
• Where the classification locks the formula, a Formula column fails the row, and no Formula column is needed.

A Contributing Measures or Formula column is ignored for a benefit whose classification has no Benefit Formula. A Measure Series column is ignored for a benefit whose classification has one. A created benefit with a Benefit Formula and no measures fails the row.

Custom fields

Map each custom field with the Custom Field type, and choose the field from the Custom Field list. The following apply to the values:

• A custom field that isn't mapped to the benefit's classification isn't set, and the cell shows a warning.
• For a field with a list of options, an option that doesn't exist isn't created. The field is left empty and the cell shows a warning. For a Multi-Select field, separate the options in a cell with commas.
• Text that is longer than the field's maximum length is an error.
• Where the classification requires a custom field, a created benefit without a value for it fails.
• Entering null in a cell clears the field on an update.

Team roles

Select the role in Team Role, then the Match on Attribute. Map one column for each role. The user is added to the benefit's team with that role, and nobody is removed. A support user or a guest user can't be added.

Previewing and importing

Previewing the import

The preview checks every row against Amplify and saves nothing. Each row shows a plus icon where it will create a benefit, or a pen icon where it will update one. A red icon on a cell marks a problem. Hover over it to read the message. An amber icon marks a warning, and the row still imports.

Where rows fail, a banner says how many rows were unsuccessful, such as "2 rows were unsuccessful." Click View these rows only. to show just those rows, and Show all rows. to return to the full list. Fix the file or the mapping, then preview again.

Where every row creates a benefit, Import... stays disabled until a preview has no failed rows. Preview again after each fix. Otherwise rows with errors don't disable it, and they are skipped when the rest import.

Import... is also disabled while a preview, import or mapping change is running, while the mapping is invalid, and until the mapping can create or update benefits.

Importing the benefits

To import the benefits:

1. Click Import.... A confirmation opens.
2. Click Confirm.
3. Wait for the banner to report that the import has been completed.
4. Click End Session. The integrations list opens.

Until the session is ended, the integration shows Terminate in place of Run... and can't be run again. If a session was left in progress, click Terminate on the integrations list to end it.

Updating benefits later

The same integration can be run again with another file. To update benefits that already exist, map a column as Identifier Lookup, matched on ID or External ID. Each row then works as follows:

• Where the value matches a benefit, the row updates it. The benefit must be active, and must belong to the integration's initiative or one beneath it.
• Where it matches no benefit and the mapping has every column needed to create one, the row creates a benefit. An External ID in the cell becomes the benefit's External ID. A mistyped identifier therefore creates a benefit instead of failing.
• Where it matches no benefit and the mapping can't create, the row fails.
• Where the cell is blank, the row creates a benefit.

Where ID is used and the value matches nothing, the row creates a benefit and the ID is ignored. The cell shows an amber warning.

An update changes only the mapped columns. A column set to No Action leaves its field as it is, and so does a blank cell. The following can't change in an import:

• Classification — the column is skipped with a warning.
• Parent Initiative — the column is skipped with a warning. A benefit can't be moved to another initiative.
• Measure Series — the column is skipped with a warning. To change a plan, import values. See Importing Benefit Values.

The following apply to an update:

• A start or end date must keep the benefit's periods whole, so it can only move in steps of the benefit's reporting cadence. A message suggests a date that works.
• For a benefit without a Benefit Formula, the Resolution can't change once actual values exist.
• For a benefit with a Benefit Formula, the dates can't be narrower than its measures' dates, and the Resolution can't be more precise than its measures'.
• A Contributing Measures column replaces the benefit's measures with the ones listed. A measure not in the cell is removed from the benefit. A blank cell changes nothing.
• A Team Role column adds the user to the team, and doesn't change anyone else.

Duplicate External IDs

Where the Identifier Lookup is matched on External ID, each External ID can appear on one row only. If the same External ID appears on several rows and doesn't exist in Amplify yet, the first row creates the benefit and the later rows fail with a message that the External ID is the same on other rows. If the External ID already exists, every row with it updates that benefit.

Things to know

Measures created with the benefit

Each benefit whose classification has no Benefit Formula gets its own measure, created automatically, as it does when a benefit is created in Amplify. Its name starts with "Measure of", followed by the benefit's name. The benefit's values are calculated in the background, so a new benefit can take a short while to show them. For a benefit with a Benefit Formula, the measures are the ones listed in the Contributing Measures column.

Importing in the right order

Rows are checked against what is in Amplify when the import runs. Create the initiatives before the benefits that belong to them. See Importing Initiatives. Then create the benefits before importing their values. See Importing Benefit Values.

Correcting benefits

To correct benefits after an import, update them with another import that has an Identifier Lookup, or edit them in Amplify. Preview every file first, and try a few rows before importing a large file.

For an overview of imports, including importing other types of data, see Importing Data.