This documentation supports the 21.05 version of BMC Helix CMDB.To view an earlier version, select the version from the Product version menu

Creating an Atrium Integrator job to import data

An Atrium Integrator Administrator creates an Atrium Integrator job and schedules it to run repeatedly.

The following video (05:26) shows how to transfer data from a CSV file to CMDB by using sample CSV data files:

icon_play.pnghttps://youtu.be/A1OUUhjB_dU


Related topics

Transferring-data-from-external-data-stores-to-BMC-Helix-CMDB

BMC Community blog about Planning Successful Atrium Integrator Jobs

Before you begin

Ensure that you have the following:


Best practice
Do not use Atrium Integrator to transfer data directly into the BMC.ASSET data set. Instead, transfer the data into a staging data set, and then reconcile it into BMC.ASSET.

Process of creating an Atrium Integrator data job

Scenario

Calbro Services maintains its discovery data in CSV files that store information about all the hardware components in its environment. There are separate files for computers, processors, disk drives, memory, and so on.

A Calbro Services administrator, Allen Allbrook, creates and runs an import job, verifies its success, and schedules it to run repeatedly.

Task

Action

Reference

1.

Specify the source and target data store details

You must specify the job name and description, source data store details, target dataset, and the target data store details to which you want to transfer data.

For more information, see To specify the job details.

2.

Select CI types to transfer

Select the CI types that you want to transfer from the target data store.

For more information, see To select the CI types for the transfer, and map target attributes and source columns.

3

Map attributes

Map the target attributes to the source columns.

For more information, see To map the target attributes to the source columns.

4.

Enable delta data import

Choose if you want to import only new or updated source records since the last transfer was run.

For more information, see To enable delta data import.

5.

Enable Delete Orphan records

For more information, see To delete orphan records.

6.

Update source column (only for DB source)

For more information, see To update the source column.


You must perform task numbers 2 to 6 for every class that you select.

7.

Define the relationship mapping

Select the relationships and define the relationships between the CI types to transfer to BMC Helix CMDB.

For more information, see To define the relationship mapping for the CI types to be transferred.

8.

Create a schedule for the job

Schedule the job to run at a specific time or timed interval.

For more information, see To create a schedule for the job.


To specify the job details

  1. On CMDB Portal, select Jobs > Manage Atrium Integrator > Create Job.
    The     Create Imports Job page opens.
  2. In the Job Details section, specify the job name and description, target data store details, and the target data store to which the data must be transferred. 
    Provide the following details:

Field

Action

Job Name

Enter a name for the job.

(optional) Description

Enter a description for the job.

Important: Length of description should not exceed 256 characters.

Data Store Details for Source Type

Select a source data store type from the list. 

Name

Select the data store from which you will import data.

Data Store Details for Target

Select a data store type, which is an AR System from this list. 
This is the destination data store type to which you want to transfer data. 

Target Dataset

Select the destination dataset from the list.

After you have entered all the job details, the page looks as follows:

For a CSV data store, click here

Job Details section for a CSV data store

JobDetails_CSV_cropped.png

For a DB data store, click here

Job Details section for a DB data store

JobDetails_DB_cropped.png

For an XML data store, click here

Job Details section for an XML data store

JobSDetails_XML_cropped.png

To select the CI types to transfer from the external data store

  1. In the Mapping section, select the CI types that you want to transfer from the external data store; for example, Computer System and Monitor, and then provide the following details:

Field

Action

Select Class

Select a class to which the CI belongs.

You can filter the class by using the search box. You can select multiple classes, but you must select at least two classes, one of which is a parent class, and the other is a child class.  

After you select the class, the other mapping details are displayed, and you can enter the mapping information for that class.

Logical Name For CI Type

Specify a logical name for the CI type. 
A logical name identifies the mapping of a class for a particular CI type and it enables you to map the same class or custom classes multiple times with different CI types..

For example, BMC_ComputerSystem class can be mapped to various CI types, such as computer system, cluster node, and master server.

The logical name should be unique for the current job.

     2.  Select the source files available for the selected data store.

Field

Action

For CSV


Select the source CSV file from the Source list.

For Database


Perform the following steps:

  1. Select a schema from the Schema list.
  2. Select the Table or View option from Select Source.
  3. Select a table name from the Select Table list or select a view name from the Select View list.  


For XML

Perform the following steps:

  1. Select the source XML file from the Source list.
  2. Select the XPath from the list. 
    The Xpath lists all the parent nodes available in an XML file. 

To map target attributes to source columns

Mapping target attributes to source columns defines the way in which data in the source column corresponds to data in the CMDB, and the actions that you must perform when transferring data between the source and target columns. A source key or primary key uniquely identifies a row of data. After a data transfer, the source key is the link that matches a record in the external data store with its counterpart in the CMDB. 

  1. To map a target attribute to a source column, select the target attribute (that belongs to the selected class) and the corresponding source column (from the CSV data store), and click Map. 
    The mapping is displayed in a tabular format.
    For some attributes, you can specify a constant value. For example, you can choose the target as Availability and assign a constant value Yes to it. 
  2. Select at least one row but not all rows from the table as the source key. 
    The target attribute and the corresponding source column in the external data store make up the source key, which is the primary key. 
    You must have two or more rows in the table out of which at least one row must be selected as the primary key, and at least one row should not be selected as the primary key. 

For a CSV type of data store, the Mapping section looks as shown in the following figure:

MappingCITypes_CSV_cropped.png

For a database (DB) type of data store, the Mapping section looks as shown in the following figure:

Mapping_CITypes_DB_cropped.png

For an XML type of data store, the Mapping section looks as shown in the following figure:

CITypes_tab_XML_cropped.png

To enable delta data import 

  1. (Optional) Select Enable Data Import to import only new or updated source records since the last transfer was run.
    EnableDeltaImport2.png

  2. Select the column that holds the time stamp when each record was last modified. 
    During each data transfer, only new records and those records with a last modified timestamp that is later than the most recent successful transfer are retrieved from the source.

Note

For Database type of data store, the Enable Data Import check box is displayed only if the source columns have at least one column with datatype that is either “date”, “timestamp”, or “datetime”.

To delete orphan records

(Optional) Select Delete Orphan Records from CMDB to mark a record as deleted from BMC Helix CMDB when that record is deleted from the source data source. 

If this option is selected, this action is not performed when the job runs for the first time, but when the job runs subsequently, the records received in current job run are compared with previous job run, and those found to be missing from the source data source are marked as deleted from BMC Helix CMDB.

Warning

We recommend that you must exercise caution when orphan records are selected to be deleted from CMDB because this action can accidentally mark all your data from CMDB as deleted.

To update the source column

Update Source Data is displayed only for database type of data stores when at least one unmapped source column belongs to "integer", "int", "number", "varchar", "char", or "string" datatypes.

  1. Select Update Source Data.
  2. Select the column to be updated.
    Mapping_CITypes_DB_Cropped2.png


To define the relationship mapping for the CI types to be transferred

  1. Click the Relationship tab.
  2. Select a parent CI from the Parent Class list.
    All the mapped CI types are shown in the Parent Class list.
  3. Select a child CI from the Child Class list.
    All the mapped CI types are shown in the Child Class list. 
    This list is populated based on the CIs that you have selected on the CI Types tab.

  4. Select a relationship between the parent and child class from the Relationship Class list.
    Only applicable relationships are populated in the Relationship Class list.
    If the parent and child CI belong to the same class, a message is displayed as shown in the following image. 
    SameClass_ConfirmMessage.png

    If you select Yes, the  CI Types tab is displayed again. 

    You cannot create a mapping between a parent and child CI belonging to the same type.

  5. To add the relationship, click Add.
  6. In Logical Name For Relationship Class, enter a logical name for the relationship. 
  7. Map the key column of the parent class with that of the child class by selecting a CI from the Columns list.
  8. (optional) To import only new or updated source records since the last transfer was run, select Enable Data Import.
  1. (optional) Repeat steps 2 to 6 for other CIs. 

For a CSV type of data store, the Mapping section looks as shown in the following figure:

MappingRelationships_CSV.png

For a DB type of data store, the Mapping section looks as shown in the following figure:

Mapping_CITypes_DB_cropped.png

For an XML type of data store, the Mapping section looks as shown in the following figure:

RelMapping_XML_cropped.png


To create a schedule for the job

Create a schedule for the job to run at a specific time or timed interval.

Best practice
You must not run a reconciliation job and an Atrium Integrator job at the same time, because both the jobs can query or update the same data.

  1. To create a schedule, click Add Schedule.
  2. Enter a schedule name. 
  3. Select the Carte Server from the list to attach the schedule to the Carte Server.
    This step is useful if you have multiple Carte servers set up in your AR server group and you want to select a particular Carte server to  be used for running this job. It also helps to balance integration job load on the AR System server. 
  4. Specify the time at which you want the job to start running.
  5. Specify the frequency at which you want the job to run. For example, Weekly.
  6. You can choose a custom interval by selecting the Interval option and then specifying the interval.
    AtriumIntegrator_CarteServer.jpg

  7. Click Save to save the job.


Where to go from here

Running-an-Atrium-Integrator-job

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*