Overview

Importing CIs will supply the CMDB with an inventory from an external source that can then be kept up to date directly in Octopus.

Once CIs are imported, it is possible to import the link between CIs and CI users.



 

References

Links to articles related to importing CIs and configuring the XML file:

• Import CI types

• Import CI relations

• Import relations between users and CIs

• Import CI attached files

• 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 CI_EN.zip file.

Available fields for CI import

Required Fields

• Type - Text(100)
  • This column represents the CI type that is to be imported. In order for this to work, it needs to correspond EXACTLY to a CI type present in the Octopus database.
  • The CI types are available from the Tools > Reference data management > CI > Type menu.
  • To import CI types, refer to the following article:Import CI Types.
• Name - Text(850)
  • Must be unique.
  • In a non-IT team, the inventory number can be used as the name.
  • If your CI name contains only numbers, it's important to format the cell as Text, once Excel may detect the format as Number in this case.

Optional Fields

• ManagedSoftware
  • When importing Software CIs, you can specify whether they will be managed or unmanaged by adding Yes/No to the column.
  • This column applies only to software CIs. For all other types, leave the column blank.
• Status - Text(100)

  • Must correspond to an existing status in Octopus (In operation, In inventory, Retired, etc.).

  • The status can be configured from the Tools > Reference data management > CI > Status menu.

  • It is possible to create CIs with different statuses or modify one or more CI status with an import. 

    • You only need to add the corresponding status. 

    • The RetirementDate is mandatory if the status is Retired. 

When the status is not specified:

• If the CI is being imported for the first time, it will be given the In operation status. 
• If the CI already exists, it will keep its existing status. 
• SubStatus
  • Must correspond to an existing substatus in Octopus.
  • The substatus can be configured from the Tools > Reference data management > CI > Types > SubStatus tab.
• Manufacturer - Text(500)
  • Represents the manufacturer of the CI (or equipment) and is related to the Suppliers module.
  • When there is a model, this field is mandatory.
  • The system will create the manufacturer during import if it does not already exist.
  • To import the manufacturers, refer to the Import suppliers article.
• Model - Text(50)
  • Represents the CI or equipment model and is always linked to a manufacturer.
  • The system will create the model during import if it does not already exist.
• Criticality - Text(50) 
  • Represents the Criticality of the equipment.
  • Must correspond to an existing level of criticality.
  • The criticality can be configured from the Tools > Reference data management > Incident > Impact menu.
• SerialNumber – Text(250)
  • Represents the serial number of the CI. 
  • If the Serial number of a CI must be unique option is active in the team's options then the value must be unique. 
  • The serial number can be used to identify the CI or equipment during import. In this case, it must be unique.
  • See the CI identification method section for more details.
• InventoryNumber – Text(50)

  • Represents the inventory number of the CI. 

  • If the Inventory number of a CI must be unique option is active in the team's options then the value must be unique. 

  • The inventory number can be used to identify the CI or equipment during import. In this case, it must be unique.
  • See the CI identification method section for more details.
• Department – Text(100)
  • The system will create the department if it does not already exist.
  • Departments can be configured from the Tools > Reference data management > General > Departments menu.
• SubDepartment – Text(100)
  • The system will create the sub-department if it does not already exist.
  • When a sub-department is specified, the department is mandatory.
  • Sub-departments can be configured from the Tools > Reference data management > General > Departments menu.
  • Sub-departments are edited in the Department column and follow the same nomenclature as sub-sites. See note below on sub-sites.
• MainContact

  • Field related to the users. It can represent the person responsible or the owner of the CI.

  • The user must already exist in Octopus because he will not be added during import and will generate an error.

  • The identification method can be the employee number, the first and last name or the Windows username.

  • See the. CI main contact identification method section for more details.

• 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 where the equipment is located.
• Category – Text(100)

  • The category of a CI is related to its type.

  • The system will create the category if it does not already exist.

  • The category can be configured from the Tools > Reference data management > CI > Types > Categories tab for the selected CI type.

• Supplier – Text(500)
  • Represents the CI or equipment supplier that usually designates the vendor who sold the CI.
    • This information can be found in the Costs tab of the CI. 
  • The system will create the supplier during import if it does not already exist.
  • This information is related to the supplier module. For more information, refer to the Import suppliers article.
• Note – Text(5000)
  • Note tab of the CI.

• MaintenanceSupplier – Text(500)
  • Represents the maintenance supplier of the CI or equipment.
  • The system will create the supplier during import if it does not already exist.
  • This information is related to the Suppliers module. For more information, refer to the Import suppliers article.
• MaintenanceGroup– Text
  • The name of the group responsible for the CI.
  • The group must already exist in Octopus because it will not be added during import and will generate an error.

  • When there is an assignee, this field is mandatory.

• MaintenanceAssignee– Text
  • The name of the assignee responsible for the CI.

  • The user must already exist in Octopus and be part of the group previously selected because it will not be added during import and will generate an error.

  • The identification method can be the employee number, the first and last name or the Windows username.

  • See the Responsible assignee identification method, for more details.

• PurchaseOrderNumber – Text(50)
• PurchaseDate – Date and Time
  • The format of the date must be compatible with the Octopus server settings, YYYY-MM-DD.
• PurchaseCost – Decimal.
  • The value must be between 0 and 9 999 999.99.
  • Example: 1234567.89.
• CostCenter – Text(50)
• InvoiceNumber – Text(50)
• WarrantyExpiryDate – Date and Time.
  • Indicates the end date of the warranty.
  • The format of the date must be compatible with the Octopus server settings, YYYY-MM-DD.
• WarrantyType – Text(100)

  • Indicates the warranty type. Example: Parts and Labour, Maintenance, etc.

  • The system will create the warranty type during import if it does not already exist.

• FundingSource – Text(100)

  Fully configurable from the Tools> Reference data management > General > Founding Sources menu.

  The system will create the funding source during import if it does not already exist.

• RequiresServiceContract – Boolean

  • Checkbox type indicator in the CI file that can be used in searches and reports.

  • Accepted values are 1 or 0, Vrai or Faux, True or False, Yes or No.

• AmortizationDuration – Whole Number.

  • The amortization duration must be expressed in months and the value must be between 1 and 1200.

  • Example: 60.

• PlannedReplacementYear - Whole Number

  • Indicates the planned replacement year when different from the theoretical lifetime.

  • The value must be between 1 and 9999.

• ExternalIdentifier - Text (50)

  • An identifier specific to the CI that can be used to uniquely tie with an external system.

  • This field is normally used by ADSIReader to recognize machine accounts in Active Directory.

  • If you use this field as the identification method for CI, this field will be mandatory and must be unique.

• ScheduleType - Text(50)

  • Represents the time range associated with the configuration item.

  • The time range must already exist following details specified in the Event Management Module article.

  • Time ranges can be configured using Tools > Reference data management CI > Time range menu.

• RetirementDate

  • Indicates the date the CI was retired.

  • ​The CI status must be Retired.

  • The format of the date must be compatible with the Octopus server settings, YYYY-MM-DD.

  • The date must be in the past.

  • If a retired date already exist, it can be updated and an entry will be added in the history following the update.

• ​WMIDetection
  • Checkbox type indicator in the CI file that indicates if the Active configuration detect via WMI checkbox will be active or not.
  • Accepted values are 1 or 0, Vrai or Faux, True or False, Yes or No.
  • Works only with CIs whose type has the Is a computer checkbox activated. 
  • Cannot be active for a Retired CI. 
• Attributes - Text(2000)

  • Any other custom field for the CI type, that does not already exist in the CI file and will be displayed in the configurations tab.

  • Adding a custom attribute can be done from the Tools > Reference Data Management > CI > Types > Attributes tab of the selected CI type.

  • The attribute name must not be the same as another field that already exists in the CI file.

  • The format of the attribute type must be respected. For more information on the available formats see the CI Attribute Management article.

    • The date format must be AAAA-MM-JJ. 

    • The date and time format must be  AAAA-MM-JJ HH:MM or AAAA-MM-JJ HH:MM AM. 

    • Example for date and time 2020-01-15 22:30 or 2020-01-15 10:30 PM. 

    • For check box attribute type, acceptable values are: 1 or 0, True or False, Yes or No.

  • Attributes must be created before the import is done.

  • The name of the column must be identical to the name in Octopus and must not contain any period (.). 

  • The maximum number of characters is 100 for the attribute name and 2000 for the value imported in the field.

Configuration File Content (CI_EN.xml)

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

<?xml version="1.0" encoding="utf-8" ?>
<Sources>
     <Source Name="CIImport">

<ConnectionString>Provider=Microsoft.ACE.OLEDB.12.0;Data Source=c:\Import\CI.xlsx;Extended Properties="Excel 12.0 Xml;HDR=YES";</ConnectionString>
<ViewName>[Import CI$]</ViewName>
<Content>CI</Content>

<!-- Additional tags -->
<IdentificationMethod>CIByName</IdentificationMethod>
<ManageCIRetirement>false</ManageCIRetirement>
<MainContactIdentificationMethod>UserByWindowsUsername</MainContactIdentificationMethod>
<DepartmentIdentificationMethod>DepartmentByName</DepartmentIdentificationMethod>
<MaintenanceAssigneeIdenfiticationMethod>UserByWindowsUsername</MaintenanceAssigneeIdenfiticationMethod>
<SiteSplitStrategy>ByPipe</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

Information on Additional Tags

To import CIs, the XML file can contain some additional tags. These tags are not mandatory and if they are not specified, the default value will be used.

CI Identification Method

In the XML file to import CIs, it is possible to specify how the CIs will be found and updated. This value becomes the unique key for the import. If this tag is not specified, the default value will be the CI name.
Permitted values for the IdentificationMethod tag: 

• CIByName (Default value): CI name.
• CIByInventoryNumber: Inventory number.
• CIBySerialNumber: Serial number.
• CIByExternalID: External identifier.

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

<IdentificationMethod>VALUE</IdentificationMethod>

CI Main Contact Identification Method (Owner)

It is possible to specify how the CI Main Contact will be found, in the data source declaration. If this tag is not mentioned, the default value will be the Windows username.

Permitted values for the MainContactIdentificationMethod tag:

• UserByID: Main contact employee number.
• UserByName: First and last name of the main contact (in the following format John Smith).
• UserByWindowsUsername (Default value): Windows username of the main contact. In the data source, the format with more than one username is not accepted, like "sile01;esil18". Only one username must be used.

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

<MainContactIdentificationMethod>VALUE</MainContactIdentificationMethod>

Management of Automatic CI Retirement and Reactivation

DataImporter can deactivate or reactivate imported CIs, depending on whether they are present or not in the data source.

Deactivating a CI can be done with the Retired status in the Status column during import. However, when the data comes from an external system, it is difficult to manage the retired CIs individually.

The ManageCIRetirement tag allows managing this automatically. If this tag is not mentioned, the default value is False, hence not activated. 

How the option works:

• When you activate this option, you must absolutely make sure that the Source Name in the XML file is always the same for a similar import, but always different for each imported source.
  For example, if you import computers and monitors from 2 different data sources. The first source can be called <Source Name="Computer"> and the second <Source Name="Monitor">.
  The source name must never change because the system uses it as a reference to find out if the CI needs to be retired of not. 
• When the CI is no longer part of the data source, the system will retire it with the next import.
• If the CI, currently Retired, reappears in the data source, it will take the specified status under certain conditions.
  • In addition to the ManageCIRetirement tag set to true, the IdentificationMethod tag must be at CIByName.
  • If the IdentificationMethod tag is another choice and a CI of the same name is already Retired, a new CI will be created.
  • There must not be two CIs of the same name already present in the database.

Permitted values for the ManageCIRetirement tag:

• True
• False (Default value)

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

<ManageCIRetirement>VALUE</ManageCIRetirement>

Department identification method

In the XML file used to import CIs, it is possible to specify how the departments and sub-departments of the CIs 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>

Responsible assignee identification method

It is possible to specify how the CI Main Contact will be found, in the data source declaration. If this tag is not mentioned, the default value will be the Windows username.

Permitted values for the MainContactIdentificationMethod tag:

• UserByID: Main contact employee number.
• UserByName: First and last name of the main contact (in the following format John Smith).
• UserByWindowsUsername (Default value): Windows username of the main contact.

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

<MaintenanceAssigneeIdentificationMethod>VALUE</MaintenanceAssigneeIdentificationMethod>

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>

Tips and Tricks

• Department and sub-department
  • Before importing departments and sub-departments related to CIs, check the ones already existing in Octopus. As the import will create the ones that do not exist, a typo or different spelling can add duplicates to your list
• Main Contact
  • If the main contact is not found during import, the CI will not be imported. We suggest that the first run of imports, without the column MainContact be done, and later import only the following columns: Type, Name and MainContact. This way analyzing the errors will be easier and you will be sure to have all the CIs imported.