Import or update licenses

To import new licenses, or to update data for licenses already in SAM on Atlas, go to Home > Import data > License import/update. This starts a wizard that contains five steps:

  1. Prepare the license import.

  2. Upload the license import file and configure import settings.

  3. Map source and destination fields.

  4. Preview of the import data, including optionally adding new metrics.

  5. View the results of the license import.

Each step of the wizard is described below.

Note

  • If the license import is interrupted, for example if the browser window is accidentally closed, you can resume the import process by returning to step 1 of the license import wizard. A dialog box will appear, where you can select to either Resume current import or Start a new import.

  • You can view or undo the results of the most recently completed license import until a new import is started. If there is a previously completed license import, the Last import section will be shown in the upper right corner of step 1 of the wizard. Select the link in that section to get to the import Results view, where you can view or undo the results of the import.

Step 1: Prepare the license import

The preparations consist of the following steps:

  • Import agreements (optional)

    If you want to attach the licenses, that you are about to import, to agreements that are not yet in SAM on Atlas, you must first import the agreements. To import agreements, go to Home > Import data > Agreement import.

  • Create your license import file

    The license import file must be in Excel (.xls or .xlsx) format. A license import template with the right format and fields can be downloaded from this step of the wizard.

    Use the drop-down menu to see a description of a field in the template. For more detailed information on required import data, and where the data can be found in SAM on Atlas after the import, see User Guide: Data Import Field Description.

    The following fields in the template are mandatory:

    • Application name or SKU (Stock Keeping Unit)

    • Legal organization

    • Purchase date

    • Assignment type

    For license updates, the following field is required in addition to the above fields:

    • License ID

      If the License ID is not included, the licenses in the import file will be treated as new instead of as updates.

      To find the ID for a license in SAM on Atlas: Go to Licenses > List all licenses, open the Column selector and add the License ID column to the list.

    Note

    A license, for which only the above fields have been filled in, will be imported, but will be marked as incomplete and will not be included in compliance calculations. For an imported license to be complete, the fields Metric and Quantity must also be filled in.

When you have completed the preparations, select Start license import to continue to the next step of the wizard.

Step 2: Upload the license import file and configure import settings

  1. Upload the license import file by selecting Choose file and browse for the file you have prepared.

    When the file is uploaded, the file name is displayed to the right of the Choose file button.

  2. In the Configure import settings section, select the identity field to be used for mapping the licenses to applications.

  3. Select Next to continue to the next step of the wizard.

Step 3: Map source and destination fields

In this step, the fields of the license import Source file are mapped to the corresponding Destination fields in SAM on Atlas. Matching source and destination field names are automatically mapped. You can manually override the auto mapping by selecting another source field name from the drop-down list.

Mandatory fields are marked with an asterisk (*) and must be included in the license import file.

For license updates, the License ID field is required in addition to the fields marked with an asterisk. If the License ID field is not mapped, the licenses in the import file will be treated as new. When the License ID field is mapped, the values in the mapped fields will be replaced with the values in the import file for those licenses. Note that this means that if no value is present in the import source file for a mapped field, the field will be cleared in SAM on Atlas.

To configure a field mapping, open the configuration dialog box by selecting the Mapping Mapping icon to the right of the destination field name.

  • To remove any spaces in the beginning or end of a data value, select the Trim leading or trailing white space check box.

    For example, the values "Application xyz" and " Application xyz " in the Application name field will be interpreted as one and the same application when the check box is selected.

  • To populate the destination field with a default value if the source field is empty, enter a value in the Default value box.

    For example, if the fields in the Is upgrade column of the import file contain the value "yes" for upgrade licenses and are empty for non-upgrade licenses, and "no" is entered as default value, the destination field will be populated with the value "no" for all empty source fields.

  • To add a prefix in front of all imported values, enter a prefix (text and/or number) in the Prefix box.

    This option is available for some of the destination fields. It can be used to separate or specify the values in the import file. For example, if the invoice reference values in the import file are "1", "2", and "3", and the text "INV_" is added as a prefix to all invoice references, the imported values will be changed to "INV_1", "INV_2", and "INV_3".

Select Next to continue to the next step of the wizard.

Step 4: Preview of the import data, including optionally adding new metrics

This step presents a preview of the data in the license import file. The Status column shows for each row in the import file if it is Ready or Not ready to be imported. You can continue with the import or update even if the import file contains invalid rows. However, rows in status Not ready will not be included in the import.

The fields of the preview are color-highlighted as follows:

Highlighting color

Description

No highlighting

The field is properly filled.

A row with no highlighted fields is given the status Ready with a green check icon. The license will be included in the import and it will be included in compliance calculations.

Yellow

Required information is missing.

A row with fields highlighted in yellow in addition to any fields with no highlighting is given the status Ready with an orange check icon. The license will be included in the import, but it will be marked as incomplete. It will not be included in compliance calculations until it has been completed with the missing data.

Note

For license updates, empty fields in the import file will result in the fields being cleared in SAM on Atlas. To avoid unintentional loss of data it is therefore important to consider yellow fields, if any, when the import concerns updating existing licenses.

Note

The Incomplete licenses functionality must be activated in Snow Management and Configuration Center for missing required information to be highlighted in yellow.

For missing required information to be highlighted in yellow, the Allow users to save incomplete licenses check box must be activated on the Snow > Manage > Application settings > License Management page.

Red

The field contains errors, such as conflicts or invalid values.

A row with one or more fields highlighted in red is given the status Not ready and will not be included in the import.

You can perform the following actions in this step:

  • Hover over a highlighted field to see more information about it.

  • Select Export all rows to export the entire preview to an Excel file.

  • Select Export invalid rows to export only rows with errors to an Excel file.

    Descriptions of the errors and warnings will be included in the file. This can be an aid in creating a correct source file, with the right fields and content.

  • Select Previous to go back and correct field mappings and import settings.

  • Select application version from the drop-down list in the SKU (Stock Keeping Unit) column to change version for the application in that row.

    The drop-down list is available if SKU was chosen as identity field in step 2 of the import wizard and the SKU represents multiple application versions. Selecting another application version will trigger re-validation of the row.

  • Select Add new metrics to add one or more new metrics from the license import file to one or more applications in SAM on Atlas. See Add new metrics.

  • Once you are satisfied with the preview, select Run import to import the licenses.

    The Import completed pop up window will appear, showing the number of imported rows and the number of rows that failed to be imported. Select Close and view results to continue to the last step of the wizard.

Add new metrics

A Metric field is highlighted in red when the metric for an application in the license import file does not match the metric or metrics currently added to the application in SAM on Atlas.

To add the metric in the license import file to the application:

  1. Select Add new metrics.

    The Import preview/Add new metrics view is displayed. All rows in the license import file containing an unmatched metric are listed. The metric or metrics currently added to the application in SAM on Atlas are shown in the Current metric(s) column. The metric from the license import file is shown in the New metric column.

  2. Select the check box for the application you want to add the new metric to.

    Multiple applications can be selected if they share the same new metric.

  3. Select Add metrics for selected applications.

    The Import preview/Add new metrics/Enter metric details view is displayed.

  4. Enter the details for the new metric.

    See applicable parts of subsections Metrics and General in Edit application for guidance.

    Select the Set as default metric check box if you want to make the new metric the default metric of the application.

    Note

    The default metric cannot be changed for a Windows Server application.

  5. To apply the new metric details, select one of the following:

    • Select Apply to selected to apply the details to the applications you selected in the previous view.

    • Select Apply to applications with same metric type to apply the details to all applications with the same new metric type listed in the previous view.

    You are returned to the Import preview/Add new metrics view. The applications to which the new metrics have been added are now in status Ready.

  6. Select Continue when you are done adding new metrics to applications.

    You are returned to the Import preview view.

Step 5: View the results of the license import

The last step of the wizard shows the results of the license import.

The Status column shows for each row of the import file if it has been Imported, Updated, or if the import or update Failed.

You can perform the following actions in this step:

  • Select Export all rows to export all rows to an Excel file.

  • Select Export invalid rows to export only rows with errors to an Excel file.

    Descriptions of the errors/warnings will be included in the file.

  • Select Undo import to undo the import you just carried out.

    Note

    Any metric changes for an application will also be reverted to the way they were before the import.

    If you have used any of the licenses from the import before undoing it, the action may cause incompliance.

  • Select Go to your licenses to see a list of all licenses in SAM on Atlas.

  • Select Start a new import to go to step 1 of the import wizard and start a new import.