Import from file

Import data into ALM Octane from an Excel file.


The following data types can be imported: Requirements, backlog items, defects, tests, and test suites.

For details on importing requirements, see Import requirements from Excel.

In an Excel (.xls or .xlsx) file, list the items that you want to import. You can import items of several types (for example, stories and defects) in a single import operation using a separate sheet for each type.

If you exported items to the file from another tool, you must update the file according to the specifications described below.

Calculated fields and certain system fields cannot be set via import. Example: Testing tool type, Last runs, Estimated hours, Code coverage.

By default, you can import up to 1000 backlog items in a single import. If you have more, you can import them in separate files.

To change the default, your site admin can configure the IMPORT_WORK_ITEMS_FUSE parameter. For details, see Configuration parameters.

Back to top

Template files

To help you prepare an Excel file with the formatting and fields required for import, you can download a template file. Click Settings and select the appropriate import action. In the Import dialog box, click View import file example.

Alternatively, you can export items of the same item type that you want to import, edit, and re-import the file. For details, see Export to file.

Back to top

Prepare the import file

You can export items from ALM Octane and re-import them to the same workspace with modifications, or import them to another workspace. For details, see Export to file.

To prepare a new import file:

  1. In an Excel file, create a separate sheet for each item type you want to import. Name the sheets with one of the following: User stories, Quality stories, Defects, Manual tests, Test suites.

  2. In Row 1 of the sheet, type the names of the fields for which you want to enter values. You must use the fields' logical names, not the field labels. You can list both system and user-defined fields. For lists of supported and required fields for each item type, see Fields for import files.

    You can also include any REST API-editable field. Ask your system admin for information.

Guidelines for listing items in the worksheet:

  1. On separate rows, enter field values for each item you want to import.

    • For possible field values, see Fields for import files.
    • Required fields. Each item type in ALM Octane has required fields, as determined in the workspace configuration. If you do not enter values for all the required fields of an item, ALM Octane imports the item in draft status.
    • Multiple values. In fields that support multiple values, separate the values with a comma.

      Note: Importing field values that contain commas is not supported.

    • Localization. For fields that use system lists, use the localized list values according to your client's language.
    • Date fields. The following date syntaxes are supported:

      Definition Example
      Time with offset


      Time with zone ID "2015-05-12T10:15:30Z"
      Time with offset and zone ID



  2. Specific item type guidelines:

    Item type Guideline
    Backlog items

    When importing backlog items, ALM Octane uses both the Epic and Feature fields to decide where the backlog item is created. For example, if you want to place a user story under a feature which is under an epic but you do not specify the epic, a new feature is created under the Backlog root.

    Manual tests

    In the rows following a manual test, define steps for the test. See examples in the template file.

    The manual test row should contain values only in the manual test fields. The test step rows should contain values only in the test step fields.

    Application modules: If an application module's name includes a forward or backslash, in the import file, double the slashes. For example, if the application module's name is app/1, specify it in the file as app//1.

    Note: You cannot specify in the import file application modules beginning or ending with a slash.

    Test suites

    In the rows following a test suite, list the tests that are part of the suite. See examples in the template file.

    Refer to the tests using their unique_id in the manual tests sheet, or their ID in ALM Octane. See the tables below for details.

    The test suite row should contain values only in the test suite fields. The test rows should contain values only in the test fields.

  3. Update existing items: You can update the fields of items that already exist in ALM Octane. To identify the existing item, specify its ALM Octane ID number in the unique_id column, prefixed by '@. For example: '@9100.

    Enter new values only for the fields that you want to change. All other fields will remain unchanged.

Back to top

Custom lookup lists

In fields that use custom lookup lists, in each of the field's values you need to specify the lookup list that the field uses. For example, the Test Type field in your workspace may be configured to use a custom list with different values than the default list.

In each cell that uses a custom lookup list use the following syntax: listName/listValue

  • listName: The name of the custom lookup list.
  • listValue: A valid value in the custom lookup list.


  • You can use either a forward slash or backslash in the syntax above.
  • If the list name or list value themselves contain a slash or backslash, type a double character: // or \\. This instructs ALM Octane to import the character literally. Example: list//Name/listValue
  • When specifying an alternative system list, listName must be the English-language name of the list, even if your space is set to another language. listValue should contain a value in your space's language.

Back to top

Import the file

Follow this procedure to import an Excel file to ALM Octane.

To import a file:

  1. Expand Settings and select an item under the Import section.
  2. Click Browse and navigate to the folder with the Excel file.

    You can re-import the same file provided that it contains changes since the last import.

  3. Click Import. ALM Octane performs a validation to check correct formatting of the Excel file and that you have not imported the same file before.

    When ALM Octane finishes the validation:

    If there are errors

    ALM Octane displays a report of the validation with the sheet and line of the error.

    At the bottom of the error report, click the Export to Excel link to save the error report.

    Fix the errors and try the import again.

    If there are duplications

    Backlog and test items:ALM Octane Warns you if you already have an item with the same name and in the same tree location as an item you are importing. This can also occur if there were network problems while importing.

    You can either cancel the import and rename the duplicate items in Excel before importing, or import anyway, creating two items with the same name in ALM Octane.

    If there are no errors The import begins.
  4. After the import is complete, the items are added to ALM Octane in the relevant module and location.

    Items that you imported without values in required fields are created ALM Octane as drafts. After the import, filter the relevant grid based on the Is Draft field, and fill in values for all the required fields.

Back to top

See also: