You can add multiple users to your site at once, or update the user profiles on your site at once, with a profile upload file. You can also upload user-delegate relationships (for a description of delegates, see "Setting Delegates" in Editing a User Profile and Setting Delegates). 

Deem provides templates in the Partner Dashboard for uploading the file.

Note: If you are not familiar with the Profiles tab in the Partner Dashboard, see Profiles Tab for Managing Uploads.

Preparing a User Profile Upload

To prepare a user profile upload, you need to prepare the data according to the upload file format for either a comma-separated values (CSV) file or an XML file. If errors are found in the upload, the error can either prevent one user or the whole file of users from being uploaded, depending on the type of error.

To create the CSV file, you can use the supplied Microsoft Excel template: You can also login to the Partner Dashboard and click on the Profiles tab and click on the Download Templates link.  

• UserProfileUploadTemplate .csv
• UserProfileUploadTemplate.xml
• UserProfileUploadTemplateInstructions.xls

You can prepare a full user profile upload to add new users and update or deactivate existing users in one step. You can also prepare a partial upload that consists of only changes. When scheduling the upload, you can click one of the following:

• "Allow New Users" radio button to add both existing and new users.
• "Update Only (ignore new users)" radio button if the file contains only existing users.

Note: For instructions on downloading this Microsoft Excel template and scheduling uploads, see Uploading User Profiles and Delegates.

An XML file uses a schema to specify how to formally describe the elements in the file (a partial list is shown below). See Uploading User Profiles and Delegates for instructions on downloading the XML template and schema definition.

Learning About the User Profile Fields

The fields that are required for adding a new user are as follows:

• Unique external ID (externalID): The externalID is a user identifier that must be unique per site. It must be alphanumeric without spaces. The maximum number of characters is 100.
• Unique username (userInfo.userName): This attribute is the user's login name, which must be unique per site. It must be alphanumeric without spaces or special characters (exceptions: "." or "-" or "_"). The maximum number of characters is 100.
• First name (userInfo.firstName): This is the user's first name. It must be alphanumeric (spaces are allowed). The maximum number of characters is 35.
• Last name (userInfo.lastName): This is the user's last name. It must be alphanumeric (spaces are allowed). The maximum number of characters is 35.
• Unique email address (userInfo.email): This is the user's email address. It must follow proper email format (for example, smith@corp.com) and be unique per site. The maximum number of characters is 100.

All other fields are optional for a new user, but are important for updating existing users as described in the upcoming section "Updating Existing Users".

Note: To examine all of the fields and requirements, see User Profile Fields. To see the values for profile fields, see Profile List of Values.

Warning: Ensure that all custom fields, corresponding collections, and custom field sets for this site are created first, before uploading profiles containing custom fields. If not, the upload will fail, because the system can't find the custom fields. See Profile Field Settings for instructions on customizing profile fields, and see Creating and Managing Custom Fields for details on custom fields for specialized booking or profile requirements.

Full User Profile Upload

You can use a full upload file of all of your organization's users in order to add new users, and update or deactivate existing users in one step:

• Users that are in the file but not in the user profile database are added to the database.
  
• Users that are in the file and also in the user profile database are updated.
• Users that are not in the file are deactivated.

Note: Sending a full upload file has no effect on users on-boarded by open enrollment or added manually in the Partner Dashboard. See Managing and Supporting Site Users for an overview of on-boarding methods.

Partial User Profile Upload

You can also create a partial upload file that consists of only changes to user profiles.

Tip: You may want to extract profile fields first, and use the extract to create the new upload file. See "Extracting the Profile Database First" in this topic.

You can use the employeeStatus field in the partial upload file to designate whether the user should be activated or deactivated:

• Any user with an employeeStatus of A (for active), and not already on the site, is added.
• Any user with an employeeStatus of A (for active), and is already on the site, is updated.
• Any user with an employeeStatus of D (for deactivate) is deactivated.

For example, in a CSV partial upload file you create from an Excel template, you would use the employeeStatus column to designate the user as A or D:

In an XML partial upload file, you would specify the employeeStatus. For example, the following adds (or updates) the user profile with an employeeStatus of A:

The following deactivates the user profile with an employeeStatus of D:

Note: If your site uses single sign-on (SSO), authentication is handled by the identity provider, and you should set the user's accountStatus field to A so that the user is activated for the site. The employeeStatus field is not used for SSO sites. For non-SSO sites, use the employeeStatus field as described above, and leave the accountStatus field blank. For information about SSO, see Single Sign On.

Updating Existing Users

To update existing users, you can update specific fields, such as employeeStatus and departmentName, as long as you include the required fields for each user:

• Unique external ID (externalID): The user identifier.
• Unique username (userInfo.userName): This attribute is the user's login name, which must be unique per site.
• First name (userInfo.firstName): This is the user's first name. 
• Last name (userInfo.lastName): This is the user's last name. 
• Unique email address (userInfo.email): This is the user's email address. 

Tip: You may want to extract profile fields first, and use the extract to create the new upload file. See "Extracting the Profile Database First" in this topic.

If you include any of the fields that are grouped together into sets, such as payment cards, passport information, custom field collections, and service preferences, you must enter information in all of the fields of the set. These sets are color-coded in the template. For example, the payment card set is color-coded red, and if you change one field in the set, you have to change them all.

Please note the following:

• If an upload contains any fields from a grouped set, all fields in that set must be included in the upload.
• If any of the grouped set’s fields are missing from the upload, the missing fields will be overwritten with blanks.
• All fields from a grouped set must be included in an upload if any of the fields are present. For example, if any update of payment card information is needed, all the payment card information must be included in the upload file, or the pre-existing payment card data will be cleared.

Note: If a user has more than one payment card in his or her profile, all payment card information for all cards in the profile must be included in the upload file, or else the other payment cards will be cleared.

Extracting the Profile Database First

You can extract user profiles first, to obtain a file with all existing users. See Extracting User Profiles for instructions.

Warning: Be sure to remove the payment card information before uploading a file that has been extracted. Uploading payment information from an extracted file will result in an invalid payment card error. Payment card numbers are encrypted in the system and can't be uploaded without updating the information.

Tip: When removing data from a field, particularly a text field, it may be necessary to enter double quotes ("") in the field to remove the data from the field.

Example: Changing Profiles Due to a Company Name Change

The following is an example of the steps to follow in order to change all of the user profiles due to a company name change. Such a name change could affect email addresses which are used as user names on many sites.

In order to change user names for existing users, you must first perform an upload that changes just the user name. Follow these steps:

1. Ensure that there are no scheduled upload feeds (such as an HR feed).
2. Extract the profile fields you need: External ID (externalID), Username (userInfo.userName), First name (userInfo.firstName), Last name (userInfo.lastName), and Email address (userInfo.email). The system needs these fields to validate the existing user. See "Extracting the Profile Database First" in this topic for instructions.
3. Create the upload file using the extract:
   • External ID (externalID): You must include the original externalID in order to change the user name, so that the system can recognize the user.
   • User name (userInfo.userName): This is the field you are changing. In many sites, this is the same as the email address.
     Note: You can change only one of these fields at a time. The system needs at least four of the required fields to recognize and validate the user. 
   • First name (userInfo.firstName): Leave this the same, so that the system can validate the user. 
   • Last name (userInfo.lastName): Leave this the same, so that the system can validate the user. 
   • Email address (userInfo.email): Leave this the same, so that the system can validate the user. 
4. Follow the instructions inUploading User Profiles and Delegates to schedule the upload, and be sure to click the "Update Only (ignore new users)" radio button.
5. The system will update the existing users with the new user names.

Note: Changing the Email address (userInfo.email) field does not change the user name. 

In order to change external IDs for existing users (if you need to), or to change the email address field, you must first follow the steps above to update the user name, and then do a second upload to update the external IDs or email addresses. Follow these steps:

1. Ensure that there are no scheduled upload feeds (such as an HR feed).
2. Follow all of the steps above to upload the change for user names.
3. Extract the profile fields you need after the update is finished in Step 2: External ID (externalID), the new Username (userInfo.userName), First name (userInfo.firstName), Last name (userInfo.lastName), and Email address (userInfo.email). The system needs these fields to validate the existing user. See "Extracting the Profile Database First" in this topic for instructions.
4. Create the upload file using the extract:
   • External ID (externalID): This is the field you are changing, if you are changing external IDs; otherwise, leave this the same.
     Note: You can change only one of these fields, such as external ID, at a time. The system needs at least four of the required fields to recognize and validate the user. 
   • Username (userInfo.userName): Leave this the same, so that the system can recognize the user. 
   • First name (userInfo.firstName): Leave this the same, so that the system can validate the user. 
   • Last name (userInfo.lastName): Leave this the same, so that the system can validate the user. 
   • Email address (userInfo.email): This is the field you are changing, if you are changing email addresses; otherwise, leave this the same. 
     Note: You can change only one of these fields, such as email address, at a time. The system needs at least four of the required fields to recognize and validate the user. 
5. Follow the instructions inUploading User Profiles and Delegates to schedule the upload, and be sure to click the "Update Only (ignore new users)" radio button.
6. The system will update the existing users with the new external ID.

Entering Values for Frequently Used Data Types

• Date formats: All fields that collect dates must be in YYYY-MM-DD format: YYYY for the four digits of the year, MM for the two digits of the month, and DD for the two digits for the day.
• Telephone numbers: Special characters including alpha characters will be stripped out. Phone number length is validated, but if it is incorrect in length, only a warning is returned.
• Country in address: The country must be a two-letter ISO code (for example, United States is US, Canada is CA, and United Kingdom is GB).
• Travel Documents and Passport, Visa, and National IDs: Special characters are stripped out.
• Loyalty numbers for Air, Car, Rental, and Hotel: Vendors must have a valid two-digit vendor code (for example, AA and ZL)
• You can use hotel chain codes to capture multi-brand loyalty numbers (for example, EH for Hilton HHonors, EM for Marriott Rewards, and so on). See Hotel Chain Vendor Preferences for details on hotel chain codes.
• Loyalty numbers are alphanumeric only (no special characters or spaces).

For a list of values for fields, see Profile List of Values.

Steps to Prepare the File

Note: You can create a comma-separated values (CSV) upload file, as described in this topic, or you can create an XML upload file, as described in User Profile Web Service Guide.

Follow these steps to prepare the upload file:

1. After clicking the Profiles tab and clicking Download Template with Instructions (Excel) at the bottom of the Profile Upload section, open the file using Microsoft Excel. For complete instructions on downloading the template, see "Downloading and Using the Template" in Uploading User Profiles and Delegates.
2. Save the upload file template as a new worksheet file before adding or changing rows and columns.
3. Follow the template instructions and the information in User Profile Fields and Profile List of Values to edit your upload file.
4. When finished editing your upload file, save a version of the file as a comma-separated values (CSV). 
5. Name the upload file using the file naming convention domainURL_name_date in YYYYMMDD format.csv (or .xml), where domainURL_name is the name portion of the site’s URL. For example: acmeus_20140215.csv or acmeus_21480215.xml.
6. REQUIRED: Encrypt the file using PGP encryption with a Deem public key. When encrypted, add “.pgp” to the existing filename. For example: acmeus_20140215.csv.pgp or acmeus_20140215.xml.pgp.
7. Follow the instructions for scheduling the upload in "Scheduling the Upload" in Uploading User Profiles and Delegates.

Troubleshooting Errors

Errors can occur due to the manipulation by Excel of a CSV file. For example:

• Numeric values greater than eight digits are truncated (for example, 5.13 E+08).
• Leading zeros are removed from any numeric values. This can cause problems with external IDs or user names if they don't match the existing user profile; the system will load them as new users. Leading zeroes can also cause problems with frequent flyer numbers — if the number doesn't match the carrier's number, the traveler won't receive credit for the trip.
• Dates may be changed to the MM/DD/YY format. All fields that collect dates must be in YYYY-MM-DD format: YYYY for the four digits of the year, MM for the two digits of the month, and DD for the two digits for the day.

Note: We strongly recommend using Excel to save the template as a worksheet file first, and then editing the worksheet file, before saving the worksheet as a CSV file. Avoid using Excel to open a CSV file, as date formats may change, and numeric values may be truncated and their leading zeros removed. To directly edit a CSV file, we strongly recommend using a text editor (such as Textpad or Notepad) or a CSV file editor (such as CSVed).

Preparing a Delegate Upload

You can create a comma-separated values (CSV) upload file for user-delegate relationships, as described in this topic, or you can create an XML upload file, as described in User Profile Web Service Guide.

Follow these steps to prepare the delegate upload file:

1. After clicking the Profiles tab and clicking Download CSV template in the Delegate Upload section, open the file.
   
2. Save the upload file template as a new file before adding or changing rows and columns.
3. Follow the specific instructions in the template. The user's external ID should appear in the first column, and numbered delegates for that user in subsequent columns (one delegate per column, with each delegate's external ID).
4. When finished editing your upload file, save a version of the file as a comma-separated values (CSV). 
5. Follow the instructions for scheduling the upload in "Scheduling the Upload" in Uploading User Profiles and Delegates.