DataImporter - Import CIs

Table of contents

Overview

Importing CIs will supply the CMDB with the 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.
In the next section, you will find links to articles related to CI imports and files with templates that can be used for it.


 

References

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

 

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, please 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.
  • Status - Text(100)
    • Must correspond to an existing status in Octopus (In service, In inventory, Retired, etc.).
    • The status can be configured from the Tools > Reference data management... > CI > Status menu.
    • When the status is not specified, the CI will be imported as In service by default.

Optional Fields

  • Manufacturer - Text(500)
    • Represents the manufacturer of the CI (or equipment) and is related to the supply 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)
    • 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.
  • InventoryNumber – Text(50)
    • 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.
  • 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.
  • 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.

  • 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.

NOTE: To import the sub-sites, you must separate the levels in the field by a "|" (pipe) character, and respect the following format:

YourSite|YourSub-Site1|YourSub-Site2|YourSub-Site3 ... and so on.
All your sites and sub-sites will hence be imported within the same field in Excel, Access or other ODBC source. The system will create the sites and sub-sites if they do not already exist.

Example: Canada|Quebec|Montreal|East Montreal
  • 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.
    • 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.
NOTE: This field replaces the existing data at each import. The program does not add the information but replaces it.
  • 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 supplier 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 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 Responsible assignee identification method, for more details.

  • PurchaseOrderNumber – Text(50)
  • 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.

  • CostCenter – Text(50)
  • InvoiceNumber – Text(50)
  • PurchaseCost – Decimal.
    • The value must be between 0 and 9 999 999.99.

    • Example: 1234567.89.

  • PurchaseDate – Date and Time
    • The format of the date must be compatible with the Octopus server settings, YYYY-MM-DD.
  • AmortizationDuration – Whole Number.
    • The amortization duration must be expressed in months and the value must be between 1 and 1200.

    • Example: 60.

  • 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.

NOTE: The only way to add a new warranty type is during the import of a CI
  • 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.

  • MaintenanceSupplier – Text(500)
    • Represents the maintenance or service supplier for the CI (or the equipment).

    • 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 Import suppliers. 

  • 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.

  • 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.

  • 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.

    • 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 (XML)

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

NOTE: The XML file used as this example is for an import done from Excel 2007 or 2010. 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

 

<?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>[Importation CI$]</ViewName>

          <Content>CI</Content>

          <IdentificationMethod>CIByName</IdentificationMethod>

          <ManageCIRetirement>false</ManageCIRetirement>

          <MainContactIdentificationMethod>UserByWindowsUsername</MainContactIdentificationMethod>

          <EmptyValueHandling>NoChange</EmptyValueHandling>

     </Source>

</Sources>

Information on Additional Tags

To import CIs, the XML file can contain 4 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.

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

<MainContactIdentificationMethod>VALUE</MainContactIdentificationMethod>

Management of Automatic CI Retirement

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 by giving it 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 at the next import.


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>

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.
X
Help us improve our articles








Help us improve our articles