NAME

Kernel::System::ImportExport::ObjectBackend::ITSMConfigItem – import/export backend for ITSMConfigItem

DESCRIPTION

All functions to import and export ITSM configuration items.

PUBLIC INTERFACE

new()

create an object

    use Kernel::System::ObjectManager;
    local $Kernel::OM = Kernel::System::ObjectManager->new();
    my $BackendObject = $Kernel::OM->Get('Kernel::System::ImportExport::ObjectBackend::ITSMConfigItem');

ObjectAttributesGet()

get the object attributes of an object as a ref to an array of hash references

    my $Attributes = $ObjectBackend->ObjectAttributesGet(
        UserID => 1,
    );

MappingObjectAttributesGet()

get the mapping attributes of an object as array/hash reference

    my $Attributes = $ObjectBackend->MappingObjectAttributesGet(
        TemplateID => 123,
        UserID     => 1,
    );

SearchAttributesGet()

get the search object attributes of an object as array/hash reference

    my $AttributeList = $ObjectBackend->SearchAttributesGet(
        TemplateID => 123,
        UserID     => 1,
    );

ExportDataGet()

get export data as 2D-array-hash reference

    my $ExportData = $ObjectBackend->ExportDataGet(
        TemplateID => 123,
        UserID     => 1,
    );

ImportDataSave()

imports a single entity of the import data. The TemplateID points to the definition of the current import. ImportDataRow holds the data. Counter is only used in error messages, for indicating which item was not imported successfully.

The current version of the configuration item will never be deleted. When there are no changes in the data, the import will be skipped. When there is new or changed data, then a new configuration item or a new version is created.

In the case of changed data, the new version of the configuration item will contain the attributes of the ImportDataRow plus the old attributes that are not part of the import definition. Thus ImportDataSave() guarantees to not overwrite undeclared attributes.

The behavior when imported attributes are empty depends on the setting in the object data. When EmptyFieldsLeaveTheOldValues is not set, then empty values will wipe out the old data. This is the default behavior. When EmptyFieldsLeaveTheOldValues is set, then empty values will leave the old values.

The decision what constitute an empty value is a bit hairy. Here are the rules. Fields that are not even mentioned in the Import definition are empty. These are the 'not defined' fields. Empty strings and undefined values constitute empty fields. Fields with with only one or more whitespace characters are not empty. Fields with the digit '0' are not empty.

    my ( $ConfigItemID, $RetCode ) = $ObjectBackend->ImportDataSave(
        TemplateID    => 123,
        ImportDataRow => $ArrayRef,
        Counter       => 367,
        UserID        => 1,
    );

An empty ConfigItemID indicates failure. Otherwise it indicates the location of the imported data. RetCode is either 'Created', 'Updated' or 'Skipped'. 'Created' means that a new configuration item has been created. 'Updated' means that a new version has been added to an existing configuration item. 'Skipped' means that no new version has been created, as the new data is identical to the latest version of an existing configuration item.

No codes have yet been defined for the failure case.

INTERNAL INTERFACE

_MappingObjectAttributesGet()

recursion function for MappingObjectAttributesGet(). Definitions for object attributes are passed in XMLDefinition. The new object attributes are appended to ElementList. CountMaxLimit limits the max length of importable arrays.

    $ObjectBackend->_MappingObjectAttributesGet(
        XMLDefinition => $ArrayRef,
        ElementList   => $ArrayRef,
        CountMaxLimit => 10,
    );

_SearchAttributesGet()

recursion function for MappingObjectAttributesGet()

    $ObjectBackend->_SearchAttributesGet(
        XMLDefinition => $ArrayRef,
        AttributeList => $ArrayRef,
    );

_ExportXMLSearchDataPrepare()

recursion function to prepare the export XML search params

    $ObjectBackend->_ExportXMLSearchDataPrepare(
        XMLDefinition => $ArrayRef,
        What          => $ArrayRef,
        SearchData    => $HashRef,
    );

_ExportXMLDataPrepare()

recursion function to prepare the export XML data

    $ObjectBackend->_ExportXMLDataPrepare(
        XMLDefinition => $ArrayRef,
        XMLData       => $HashRef,
        XMLData2D     => $HashRef,
    );

_ImportXMLSearchDataPrepare()

recursion function to prepare the import XML search params

    $ObjectBackend->_ImportXMLSearchDataPrepare(
        XMLDefinition => $ArrayRef,
        What          => $ArrayRef,
        Identifier    => $HashRef,
    );

_ImportXMLDataMerge()

recursive function to inplace edit the import XML data.

    my $MergeOk = $ObjectBackend->_ImportXMLDataMerge(
        XMLDefinition => $ArrayRef,
        XMLDataPrev   => $HashRef,
        XMLData2D     => $HashRef,
    );

The return value indicates whether the merge was successful. A merge fails when for example a general catalog item name can't be mapped to an id.

_GetReferenceData()

get a hash with field names and values for a version of a config item my $ReferenceData = $BackendObject->_GetReferenceData( XMLData => $XMLData, # result of Kernel::System::ITSMConfigItem->VersionGet()->{XMLData} XMLDefinition => $XMLDefinition, # result of Kernel::System::ITSMConfigItem->VersionGet()->{XMLDefinition} );

Returns:

    my $Data = {
        CIField1 => '5',
        CIField2 => '6',
        CIField3 => '7',
    }