Convert Users

When changing from one authentication provider to another, existing users need to be switched over to matching users in the new provider or deleted.

  • DELETE: If admins choose to delete users, all users will be removed permanently from the platform and their content will be deleted.
  • CONVERT: If admins choose to convert users, admins need to map existing users to users in the new Authentication Provider. This process is iterative, offering admins an opportunity to preview the mapping process and make adjustments before committing the changes. Users that are successfully mapped, will seamless transition with their content. Users that are not matched are disabled - but their content is NOT deleted.

Mapping Pyramid Users

Once you have launched the change provider process, with a new initial user, you will be prompted to go through the user conversion process.

For the conversion process, you will need to prepare an upload-able CSV file with the user mapping from the old to new.

Creating your Upload File

The CSV file that you use to map your users has different columns depending on your target Authentication Provider and whether you have supplied User Provisioning Settings to allow Pyramid to search for user details held by your Authentication Provider. You can download blank template CSV files below:

See below for details of the fields that you need to complete for each of these file types,

Important: The first row in the CSV file is always treated as a header row. Your spreadsheet must include all columns described below. Where a column is described as "optional," the column may be left empty but still needs to be present in the spreadsheet.

Uploading your file

This process begins at the end of the Change Provider process:

Once you click Apply to change your provider, you will be prompted to make a decision: either to DELETE or CONVERT existing users.

  • If you are happy to delete your current Pyramid users and their content, select that option in the dialog and then click DELETE USERs button to continue.
  • If you have want to migrate your existing users, select that option in the dialog. Next browse to and select your CSV mapping file. Then click the CONVERT USERs button to continue.
  • If you are unsure, click cancel to stop the provider change over process.

Conversion

If you chose "CONVERT", the conversion process begins with an evaluation of the mapping for each user supplied. Finally the user mapping dialog will open and report results.

Mapped Users

The Convert Users dialog lists each user in the CSV mapping and indicates:

  • Status: The status field indicates whether the user has been converted (green) or not (red). The user may not be converted because:
    • The Search Value and Target User Name do not match.
    • There is no user that matches the Search Value.
    • There are mandatory details that are not supplied for the user.
  • Error: Where the status is red, an error is displayed indicating the cause of the failure.

It is important to note that users that are not converted will be disabled in Pyramid.

Exporting the status list

Click the export button to download the listing of users mapped successfully or failed. This may help you resolve any mapping problems.

Canceling the Mapping

If you choose to cancel the mapping exercise, the entire change provider process is canceled without committing ANY changes. This means, if you want to proceed, you must start from the beginning of the change provider process again.

Mapping File Structures

Active Directory Users (with search)

The active directory file needs to be in comma delimited format (CSV) where each row represents a user in the Active Directory that you want to map to a user in Pyramid. The following columns are required:

  • Source user name
  • Target user name
  • Search value

Internal Database Users (no search)

Where the Authentication Provider is Database (internal), the import file needs to include the following columns:

  • Source user name
  • Target user name
  • External ID - The Mandatory External ID for the user in Pyramid. You need to supply this value where search is not being used.

SAML and OpenID Users (with search)

Where the Authentication Provider is SAML or OpenID and Pyramid is set up to search for user details on that Authentication Provider (Provider Provisioning Settings are set up for the Authentication Provider), the import file needs to include the following columns:

  • Source user name
  • Target user name
  • Search value - The value used to search for the user on the Authorization Provider. This is typically the Principal Name or User Name, although it can be Display Name where the Vendor is Azure and will always be Email where the Vendor is Google.