Overview

This article explains how to import users in Octopus. 

References

• Import Members of User Groups
• XML Configuration File
   
• Back to main page for DataImporter
• Back to the Import Source Specification list

What you need to know:

The reference template files (.xlsx et .xml) to prepare imports are included in the Users.zip file.

Required Fields

• FirstName - Text (100).
  • Represents the first name of the user.
• Surname - Text (100).
  • Represents the last name of the user.

Optional Fields

• EmployeeID – Text (50).
  • If the employee number is used as the identification method for the user during import, it must be unique.
  • If the employee number is used as the authentification mode for the Web Portal, it must be unique.
• WindowsUsername - Text (250).
  • If the Windows username is used as the identification method for the user during import, it must be unique. The format with more than one username is not accepted, like "sile01;esil18". Only one username must be used.
  • If the Windows username is used as the authentication mode for the Web Portal, it must be unique.
• UPN - Text (250).
  • This field is used to synchronize the userPrincipalName (UPN) required by the Azure AD federated identity manager. This will be added to the existing value of the Windows Username field.
• ExternalIdentifier - Text (50).
  • An identifier specific to the user that can be used to uniquely tie with an external system.
  • This field is used by ADSIReader to recognize Active Directory objects.
• Active - Boolean.  
  NOTE: 
  By default, when a user is deactivated, Octopus removes the links between the user and its CIs. It is possible to modify this behaviour and ensure that the status of a user does not affect its links to CIs.
  
  If needed, communicate with the Octopus Service Desk, to have this option modified.
  • Acceptable values are: 1 or 0, True or False, Yes or No.
  • The user will be active by default if this field is not included.
• SharedAccount - Boolean.

  • Acceptable values are: 1 or 0, True or False, Yes or No.

  • The account will not be shared by default if this field is not included.

• Department - Text (100).
  • If the department does not exist, it will be created during import.

• Supervisor
  • Must contain the unique identifier to the user's supervisor as specified in the identification method.
  • The user must exist in Octopus because it will not be imported and will generate an error.
  • It is not required for the line containing the supervisor identifier to appear before the one of the employee.
  • If a user is indicated as his own supervisor, the system will accept the value but will give a warning during import.
• Title- Text (100).
  • Represents the user's title.
• Language
  • Accepted values are: English, French or Portuguese.
  • By default, if this field is not filled, it will be configured with the database default language.
• VIP - Boolean.
  • Accepted values are: 1 or 0, True or False, Yes or No.
  • By default, if this field is not filled, it will not be activated during creation and will stay as is during update.
• OfficePhone - Text (50).
• PhoneExtension - Text (50).
• CellPhone - Text (50).
• HomePhone - Text (50).
• Pager - Text (50).
• Email - Text (320).
  • The email address must have a valid format, in other words it must contain an @ and a period (.) for .com, .ca, .gouv.qc.ca, etc.
  • The information entered will go to the Professionnal email field. 
• PersonalEmail - Text (320).
  • The email address must have a valid format, in other words it must contain an @ and a period (.) for .com, .ca, .gouv.qc.ca, etc.
  • The information entered will go to the Personal email field. 

• CommunicationPreference 
  • ​Accepted values are: Professional Email, Personal Email or Professional / Personal Email
  • By default, if this field is not filled, it will be configured with the default communication preference: Professional Email
• Site – Text (200).

  • The system will create the site or sub-site during import if it does not already exist.

  • The site can be configured from the Tools > Reference data management > General > Sites menu.

  • It is possible to import many levels of sites, so you can have a main site and it's sub-sites.

• Local – Text (50).
  • Represents the local number (office) of the user.
• Note - Text (2000).
  • Import all additional information about the user that cannot be linked to other fields in the file in this field.
  • Data imported to this field replaces previous data at each import. The program does not add the information but replaces it.
• DelegatesApprovalsTo
  • Must contain the unique identifier to the user's delegate as specified in the identification method.
  • The user must exist in Octopus or it will not be imported and will generate an error.
  • It is not required for the line containing the delegate to appear before the one of the employee.
  • If a user is indicated as his own delegate the system will generate an error and the line will not be imported.
• Role
  • By default, all users are given the End User role. If necessary, you can manage the roles with an import.
  • Must represent one or more existing roles.
  • If the roles are associated with licences other than End User, the user account must already exist and they must have the correct licence.
  • WARNING: this import does not add the new roles, it overwrites the previous values, it is therefore important to add all the roles that the user will need during the import.
  • If more than one role is imported, use the vertical bar (|) to separate.

Configuration File (XML)

The declaration of the source is done by indicating the User value in the <Content> tag.

<?xml version="1.0" encoding="utf-8" ?>
<Sources>
     <Source Name="Import Users">
          <ConnectionString>Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\Import\Users.xlsx;Extended Properties="Excel 12.0 Xml;HDR=YES";</ConnectionString>
          <ViewName>[Import User$]</ViewName>
          <Content>user</Content>
          <IdentificationMethod>UserByWindowsUsername</IdentificationMethod>
          <DepartmentIdentificationMethod>DepartmentByName</DepartmentIdentificationMethod>
  <SiteSplitStrategy>ByComma</SiteSplitStrategy>
          <EmptyValueHandling>NoChange</EmptyValueHandling>
     </Source>
</Sources>

To explain the tags used in all types and to find out more about the types of files, please refer to the XML Configuration File article

Additional Tags to Import Users

To import planned requests, the XML file can contain 3 additional tags. These tags are not mandatory and if they are not specified, the default values will be used.

User Identification Method

In the XML file to import the users, it is possible to specify how the user, supervisor or the approval delegate will be found.

Accepted values for this tag IdentificationMethod:

• UserByID (Default value): User's employee number.
• UserByName: User's first and last name.
• UserByNameAndPhoneExtension : User's first name, last name and phone extension.
• UserByWindowsUsername: User's Windows Username. In the data source, the format with more than one username is not accepted, like "sile01;esil18". Only one username must be used.
• UserByExternalID: User's External Identifier.

To use this tag, add the following line to the XML file: 

<IdentificationMethod>VALUE</IdentificationMethod>

Department identification method

In the XML file used to import users, it is possible to specify how the departments and sub-departments of the users will be found.

Accepted values for the DepartmentIdentificationMethod tag are:

• DepartmentByName (Default value): Uses the department name.
• DepartmentByNumber: Uses the department number.

To use this tag, add the following line to the XML file: 

<DepartmentIdentificationMethod>VALUE</DepartmentIdentificationMethod>

Data Separator Management

When importing choices for categories, a separator must indicate the delimitation of the data. 

The two choices are:

• The pipe ( | ) 
• The comma ( , )

To specify which separator to use in the file, the SiteSplitStrategy tag must be added to the XML file

Values allowed for the SiteSplitStrategy tag:

• ByPipe (default value)
• ByComma

To use this tag, add the following line in the XML file.

<SiteSplitStrategy>VALUE</SiteSplitStrategy>

If the tag is not specified in the XML file, the default value is applied.

Management of Empty Fields

DataImporter can help clean the data contained in Octopus when empty fields are encountered. If this tag is not present, the NoChange default value will be used. 

If you want to use this tag as part of an import, it is important that your data source only contains columns to act on. DataImporter will systematically try to clean all these columns. You can clean all fields except:

• Required fields.
• Fields that have been configured as mandatory in the Octopus database.
• Fields that accept only specific values, for example, boolean type fields (yes/no).

Permitted values for the EmptyValueHandling tag:

• Clear: The existing value in Octopus will be cleared and the field will be empty.
• NoChange (Default Value): Fields that are empty in the data source being imported will be ignored and the existing value in Octopus will be kept.

To use this tag, add the following line to the XML file: 

<EmptyValueHandling>VALUE</EmptyValueHandling>