NAME

Kernel::System::ITSMConfigItem::Version – sub module of Kernel::System::ITSMConfigItem

DESCRIPTION

All version functions.

PUBLIC INTERFACE

VersionZoomList()

return a configuration item version list as array-hash reference

    my $VersionListRef = $ConfigItemObject->VersionZoomList(
        ConfigItemID => 123,
    );

VersionListAll()

Returns a two-dimensional hash reference with the configuration item ids as keys of the first level and the corresponding version ids as keys of the second level, then followed by the version data as hash reference.

    my $VersionListRef = $ConfigItemObject->VersionListAll(
        ConfigItemIDs => [ 1, 2, 3, 4, ...],    # optional

        OlderDate     => '2014-12-22 23:59:59', # optional
                                                # finds versions older than the given date
                                                # Format MUST be
                                                # YYYY-MM-DD HH:MM:SS
                                                # fill missing values with 0 first
                                                # Example: 2014-04-01 07:03:04
                                                # otherwise it won't be taken as
                                                # valid search parameter

        Limit         => 1000000,               # optional
    );

Returns:

$VersionListRef = {

    # ConfigItemID
    1 => {

        # VersionID
        100 => {
            VersionID    => 100,
            ConfigItemID => 1,
            Name         => 'ConfigItem1',
            DefinitionID => 5,
            DeplStateID  => 3,
            InciStateID  => 2,
            CreateTime   => '2016-03-22 17:58:00',
            CreateBy     => 1,
        },

        # VersionID
        101 => {
            VersionID    => 101,
            ConfigItemID => 1,
            Name         => 'ConfigItem2',
            DefinitionID => 5,
            DeplStateID  => 3,
            InciStateID  => 2,
            CreateTime   => '2016-03-22 17:58:00',
            CreateBy     => 1,
        },
    },

    # ConfigItemID
    2 => {

        # VersionID
        150 => {
            VersionID    => 150,
            ConfigItemID => 2,
            Name         => 'ConfigItem1',
            DefinitionID => 5,
            DeplStateID  => 3,
            InciStateID  => 2,
            CreateTime   => '2016-03-22 17:58:00',
            CreateBy     => 1,
        },

        # VersionID
        151 => {
            VersionID    => 151,
            ConfigItemID => 2,
            Name         => 'ConfigItem1',
            DefinitionID => 5,
            DeplStateID  => 3,
            InciStateID  => 2,
            CreateTime   => '2016-03-22 17:58:00',
            CreateBy     => 1,
        },
    },
};

VersionList()

return a configuration item version list as array reference

    my $VersionListRef = $ConfigItemObject->VersionList(
        ConfigItemID => 123,

        Name         => 'The Name',                             # (optional)
        DeplStateIDs => [ 321, 123 ],                           # (optional)
        InciStateIDs => [ 321, 123 ],                           # (optional)

        # versions with created time after ...
        VersionCreateTimeNewerDate => '2006-01-09 00:00:01',    # (optional)

        # configuration items versions with created time before then ....
        VersionCreateTimeOlderDate => '2006-01-19 23:59:59',    # (optional)

        OrderBy => [ 'VersionID', 'Name' ],                     # (optional)
        # default: [ 'VersionID' ]
        # (VersionID, VersionNumber, Name, DeplStateID, InciStateID, CreateTime, CreateBy)

        # Additional information for OrderBy:
        # The OrderByDirection can be specified for each OrderBy attribute.
        # The pairing is made by the array indices.

        OrderByDirection => [ 'Down', 'Up' ],                   # (optional)
        # default: [ 'Up' ]
        # (Down | Up)

        UsingWildcards => 0,    # (optional) default 1

        Limit => 10, # (optional)
    );

VersionNumberGet()

returns a lookup hash reference from version id to version number for the given configuration item id.

    my $VersionID2Number= $ConfigItemObject->VersionNumberGet(
        ConfigItemID => 123,
    );

VersionGet()

returns a version of a configuration item as hash reference. The returned hash contains following attributes.

    $Version{VersionID}
    $Version{VersionNumber}      # Incremental version number for the versions of a configuration item
    $Version{ConfigItemID}
    $Version{Number}             # Configuration Item Number
    $Version{ClassID}
    $Version{Class}
    $Version{LastVersionID}
    $Version{Name}
    $Version{DefinitionID}
    $Version{DeplStateID}
    $Version{DeplState}
    $Version{DeplStateType}
    $Version{CurDeplStateID}
    $Version{CurDeplState}
    $Version{CurDeplStateType}
    $Version{InciStateID}
    $Version{InciState}
    $Version{InciStateType}
    $Version{CurInciStateID}
    $Version{CurInciState}
    $Version{CurInciStateType}
    $Version{XMLDefinition}
    $Version{XMLData}
    $Version{CreateTime}
    $Version{CreateBy}

    my $VersionRef = $ConfigItemObject->VersionGet(
        VersionID  => 123,
        XMLDataGet => 1,    # (optional) default 1 (0|1)
    );

    or

    my $VersionRef = $ConfigItemObject->VersionGet(
        ConfigItemID => 123,
    );

When the data from the XML storage is not needed then fetching the XML data can be explicitly turned off by passing XMLDataGet => 0.

    my $VersionRef = $ConfigItemObject->VersionGet(
        ConfigItemID => 123,
        XMLDataGet   => 0,
    );

When cache is disabled (like during CI import), it's useful to pass some data, like DeploymentStates, IncidentStates and ClassList. It improves import performances.

    my $VersionRef = $ConfigItemObject->VersionGet(
        VersionID => 123,
        XMLDataGet   => 0,
        DeploymentStates => \%DeploymentStates,
        IncidentStates   => \%IncidentStates,
        ClassList        => $ClassList,
    );

VersionNameGet()

returns the name of a version of a configuration item.

    my $VersionName = $ConfigItemObject->VersionNameGet(
        VersionID => 123,
    );

    or

    my $VersionName = $ConfigItemObject->VersionNameGet(
        ConfigItemID => 123,
    );

VersionNameList()

returns a list of config item ids and related names (latest version).

    my %List = $ConfigItemObject->VersionNameList();

returns:

    %List = (
        123 => 'Config item name',
    );

VersionConfigItemIDGet()

return the configuration item id of a version

    my $ConfigItemID = $ConfigItemObject->VersionConfigItemIDGet(
        VersionID => 123,
    );

VersionAdd()

add a new version

    my $VersionID = $ConfigItemObject->VersionAdd(
        ConfigItemID => 123,
        Name         => 'The Name',
        DefinitionID => 1212,
        DeplStateID  => 8,
        InciStateID  => 4,
        XMLData      => $ArrayHashRef,  # (optional)
        UserID       => 1,
    );

VersionDelete()

delete an existing version or versions

    my $True = $ConfigItemObject->VersionDelete(
        VersionID => 123,
        UserID    => 1,
    );

    or

    my $True = $ConfigItemObject->VersionDelete(
        ConfigItemID => 321,
        UserID       => 1,
    );

    my $True = $ConfigItemObject->VersionDelete(
        VersionIDs => [ 1, 2, 3, 4 ],
        UserID     => 1,
    );

VersionSearch()

return a configuration item version list as array reference

    my $ConfigItemIDs = $ConfigItemObject->VersionSearch(
        Name         => 'The Name',      # (optional)
        ClassIDs     => [ 9, 8, 7, 6 ],  # (optional)
        DeplStateIDs => [ 321, 123 ],    # (optional)
        InciStateIDs => [ 321, 123 ],    # (optional)

        PreviousVersionSearch => 1,  # (optional) default 0 (0|1)

        OrderBy => [ 'ConfigItemID', 'Number' ],                  # (optional)
        # default: [ 'ConfigItemID' ]
        # (ConfigItemID, Name, Number, ClassID, DeplStateID, InciStateID
        # CreateTime, CreateBy, ChangeTime, ChangeBy)

        # Additional information for OrderBy:
        # The OrderByDirection can be specified for each OrderBy attribute.
        # The pairing is made by the array indices.

        OrderByDirection => [ 'Up', 'Down' ],                    # (optional)
        # default: [ 'Up' ]
        # (Down | Up)

        Limit          => 122,  # (optional)
        UsingWildcards => 0,    # (optional) default 1
    );

INTERNAL INTERFACE

_GetEvents()

This method checks what values were changed and what events have to be triggered. It returns a hash reference with all event names as keys that should be triggered.

    my $Events = $CIObject->_GetEvents(
        Param => {
            DeplStateID => 123,
        },
        ConfigItemInfo => {
            DeplStateID => 234,
        },
    );

    print keys %{$Events}; # prints "DeploymentStateUpdate"

_EventHandlerForChangedXMLValues()

This method calls the event handler for each changed value of the configuration item. The changed values are passed in UpdateValues as an hashref with tag-keys as keys. Please note that this only handles values inside the XML structure, not general attributes like CurInciState.

    my $Success = $ConfigItemObject->_EventHandlerForChangedXMLValues(
        ConfigItemID => 123,
        UpdateValues =>
            {
               "[1]{'Version'}[1]{'Vendor'}[1]" => 'OldVendor%%NewVendor',
               "[1]{'Version'}[1]{'Type'}[1]"   => '127%%128',
            }
        UserID       => 1,
    );

_FindChangedXMLValues()

compares the new xml data NewXMLData with the xml data of the latest version of the configuration item ConfigItemID. Note that the new XML data does not contain tag keys. All values of the two data sets are compared. When a changed value is encountered, the tag key and the old and the new value are stored in a hash. The hash with the updated values is returned.

    my %UpdateValues = $ConfigItemObject->_FindChangedXMLValues(
        ConfigItemID => 123,
        NewXMLData   =>
            [
                undef,
                {
                    'Version' =>
                        [
                            undef,
                            {
                                'Owner' =>
                                    [
                                       undef,
                                       {
                                           'Content' => ''
                                       },
                                    ],
                            },
                        ],
                },
            ],
    );

The returned hash looks like:

    %UpdateValues = (
       "[1]{'Version'}[1]{'Vendor'}[1]" => 'OldVendor%%NewVendor',
       "[1]{'Version'}[1]{'Type'}[1]"   => '127%%128',
    );

The key is a tag key. The values contains the old and the new XML value.

_GrabTagKeys()

recursively scans a perl data structure for the hash key 'TagKey' and returns a list of all the values for that key.

    my @TagKeys = $ConfigItemObject->_GrabTagKeys(
        Data => $XMLHashReferenz,
    );