#######
Package
#######


****
NAME
****


Kernel::System::Package - to manage application packages/modules


***********
DESCRIPTION
***********


All functions to manage application packages/modules.


****************
PUBLIC INTERFACE
****************


new()
=====


create an object


.. code-block:: perl

     my $PackageObject = $Kernel::OM->Get('Kernel::System::Package');



RepositoryList()
================


returns a list of repository packages


.. code-block:: perl

     my @List = $PackageObject->RepositoryList();
 
     my @List = $PackageObject->RepositoryList(
         Result => 'short',  # will only return name, version, install_status md5sum, vendor and build commit ID
         instead of the structure
     );



RepositoryGet()
===============


get a package from local repository


.. code-block:: perl

     my $Package = $PackageObject->RepositoryGet(
         Name    => 'Application A',
         Version => '1.0',
     );
 
     my $PackageScalar = $PackageObject->RepositoryGet(
         Name            => 'Application A',
         Version         => '1.0',
         Result          => 'SCALAR',
         DisableWarnings => 1,                 # optional
     );



RepositoryAdd()
===============


add a package to local repository


.. code-block:: perl

     $PackageObject->RepositoryAdd(
         String => $FileString,
     );



RepositoryRemove()
==================


remove a package from local repository


.. code-block:: perl

     $PackageObject->RepositoryRemove(
         Name    => 'Application A',
         Version => '1.0',
     );



PackageInstall()
================


install a package


.. code-block:: perl

     $PackageObject->PackageInstall(
         String => $FileString,
         Force  => 1,             # optional 1 or 0, for to install package even if validation fails
     );



PackageReinstall()
==================


reinstall files of a package


.. code-block:: perl

     $PackageObject->PackageReinstall( String => $FileString );



PackageUpgrade()
================


upgrade a package


.. code-block:: perl

     $PackageObject->PackageUpgrade(
         String => $FileString,
         Force  => 1,             # optional 1 or 0, for to install package even if validation fails
     );



PackageUninstall()
==================


uninstall a package


.. code-block:: perl

     $PackageObject->PackageUninstall( String => $FileString );



GetRequiredPackages()
=====================


This function returns an array of hashes that contains information
about \ ``RequiredPackages``\  of the .sopm-file.


.. code-block:: perl

     my $PackageRequired = $PackageObject->GetRequiredPackages(
         Structure => \%Structure,       # return of PackageParse()
     );


Returns:


.. code-block:: perl

     my $PackageRequired = (
       {
         'Name'                       => 'ITSMCore',
         'Version'                    => '',
         'IsInstalled'                => 'Problem',
         'IsRequiredVersionInstalled' => 0,
       },
       {
         'Name'                       => 'Survey',
         'Version'                    => '6.5.0',
         'IsInstalled'                => 'OK',
         'IsRequiredVersionInstalled' => 1,
       }
     );



RootRepositoryListGet()
=======================


Returns a list of available root repositories. These are the ones contained in the XML file
configured in SysConfig option Package::RepositoryRoot.


.. code-block:: perl

     my %List = $PackageObject->RootRepositoryListGet();



ConfiguredRepositoryListGet()
=============================


Returns the combined configuration of all configured repositories from
Package::RepositoryRoot and Package::RepositoryList.


.. code-block:: perl

     my %RepositoryList = $PackageObject->ConfiguredRepositoryListGet();


Returns:


.. code-block:: perl

     my %RepositoryList = (
         'Freebie Features' => {
             URL   => 'https://download.znuny.org/releases/packages',
         },
         'Znuny Open Source Add-ons' => {
             URL   => 'https://addons.znuny.com/public',
         },
         'Znuny GmbH' => {
             URL   => 'https://addons.znuny.com/private',
             AuthHeaderKey   => '...',
             AuthHeaderValue => '...',
         },
         'Customer Z' => {
             URL             => 'https://addons.znuny.com/private',
             AuthHeaderKey   => '...',
             AuthHeaderValue => '...',
         },
     );



RepositoryPackageListGet()
==========================


Returns a list of available packages for the given source repository.


.. code-block:: perl

     my @List = $PackageObject->RepositoryPackageListGet(
         Source             => 'Example repository 1',   # the value of key 'Name' in item of SysConfig option Package::RepositoryList or a direct download URL
         Lang               => 'en',
         Cache              => 0,                        # (optional) use cached data
         IncludeSameVersion => 1,                        # (optional) also get packages already installed and with the same version
     );



PackageOnlineGet()
==================


download online package and put it into the local repository


.. code-block:: perl

     $PackageObject->PackageOnlineGet(
         Source => 'http://host.example.com/', # or the name of a configured repository in Package::RepositoryList
         File   => 'SomePackage-1.0.opm',
     );



DeployCheck()
=============


check if package (files) is deployed, returns true if it's ok


.. code-block:: perl

     $PackageObject->DeployCheck(
         Name    => 'Application A',
         Version => '1.0',
         Log     => 1,       # Default: 1
     );



DeployCheckInfo()
=================


returns the info of the latest DeployCheck(), what's not deployed correctly


.. code-block:: perl

     my %Hash = $PackageObject->DeployCheckInfo();



PackageBuild()
==============


build an opm package


.. code-block:: perl

     my $Package = $PackageObject->PackageBuild(
         Name => {
             Content => 'SomePackageName',
         },
         Version => {
             Content => '1.0',
         },
         Vendor => {
             Content => 'OTRS AG',
         },
         URL => {
             Content => 'L<http://otrs.org/>',
         },
         License => {
             Content => 'GNU GENERAL PUBLIC LICENSE Version 3, November 2007',
         }
         Description => [
             {
                 Lang    => 'en',
                 Content => 'english description',
             },
             {
                 Lang    => 'de',
                 Content => 'german description',
             },
         ],
         Filelist = [
             {
                 Location   => 'Kernel/System/Lala.pm',
                 Permission => '644',
                 Content    => $FileInString,
             },
             {
                 Location   => 'Kernel/System/Lulu.pm',
                 Permission => '644',
                 Content    => $FileInString,
             },
         ],
     );



PackageParse()
==============


parse a package


.. code-block:: perl

     my %Structure = $PackageObject->PackageParse( String => $FileString );



PackageExport()
===============


export files of an package


.. code-block:: perl

     $PackageObject->PackageExport(
         String => $FileString,
         Home   => '/path/to/export'
     );



PackageIsInstalled()
====================


returns true if the package is already installed


.. code-block:: perl

     $PackageObject->PackageIsInstalled(
         String => $PackageString,    # Attribute String or Name is required
         Name   => $NameOfThePackage,
     );



PackageInstallDefaultFiles()
============================


returns true if the distribution package (located under ) can get installed


.. code-block:: perl

     $PackageObject->PackageInstallDefaultFiles();



PackageFileGetMD5Sum()
======================


generates a MD5 Sum for all files in a given package


.. code-block:: perl

     my $MD5Sum = $PackageObject->PackageFileGetMD5Sum(
         Name    => 'Package Name',
         Version => 123.0,
     );


returns:


.. code-block:: perl

     $MD5SumLookup = {
         'Direcoty/File1' => 'f3f30bd59afadf542770d43edb280489',
         'Direcoty/File2' => 'ccb8a0b86adf125a36392e388eb96778',
     };



AnalyzePackageFrameworkRequirements()
=====================================


Compare a framework array with the current framework.


.. code-block:: perl

     my %CheckOk = $PackageObject->AnalyzePackageFrameworkRequirements(
         Framework => $Structure{Framework},     # [ { 'Content' => '4.0.x', 'Minimum' => '4.0.4'} ]
         NoLog     => 1, # optional
     );
 
     %CheckOK = (
         Success                  => 1,           # 1 || 0
         RequiredFramework        => '5.0.x',
         RequiredFrameworkMinimum => '5.0.10',
         RequiredFrameworkMaximum => '5.0.16',
     );



PackageUpgradeAll()
===================


Updates installed packages to their latest version.


.. code-block:: perl

     my %Result = $PackageObject->PackageUpgradeAll(
         Force           => 1,     # optional 1 or 0, Upgrades packages even if validation fails.
         SkipDeployCheck => 1,     # optional 1 or 0, If active it does not check file deployment status
                                   #     for already updated packages.
     );
 
     %Result = (
         Updated => {                # updated packages to the latest remote repository version
             PackageA => 1,
             PackageB => 1,
             PackageC => 1,
             # ...
         },
         Installed => {              # packages installed as a result of missing dependencies
             PackageD => 1,
             # ...
         },
         AlreadyInstalled {          # packages that are already installed with the latest version
             PackageE => 1,
             # ...
         }
         Undeployed {                # packages not correctly deployed
             PackageK => 1,
             # ...
         }
         Failed => {                 # or {} if no failures
             Cyclic => {             # packages with cyclic dependencies
                 PackageF => 1,
                 # ...
             },
             NotFound => {           # packages not listed in the remote repositories
                 PackageG => 1,
                 # ...
             },
             WrongVersion => {       # packages that require a major version that is not available in the remote repositories
                 PackageH => 1,
                 # ...
             },
             DependencyFail => {     # packages with dependencies that fail on any of the above reasons
                 PackageI => 1,
                 # ...
             },
         },
     );



PackageInstallOrderListGet()
============================


Gets a list of packages and its corresponding install order including is package dependencies. Higher
    install order means to install first.


.. code-block:: perl

     my %Result = $PackageObject->PackageInstallOrderListGet(
         InstalledPackages => \@PackageList,      # as returned from RepositoryList(Result => 'short')
         OnlinePackages    => \@PackageList,      # as returned from PackageOnlineList()
     );
 
     %Result = (
         InstallOrder => {
             PackageA => 3,
             PackageB => 2,
             PackageC => 1,
             PackageD => 1,
             # ...
         },
         Failed => {                 # or {} if no failures
             Cyclic => {             # packages with cyclic dependencies
                 PackageE => 1,
                 # ...
             },
             NotFound => {           # packages not listed in the remote repositories
                 PackageF => 1,
                 # ...
             },
             WrongVersion => {        # packages that require a major version that is not available in the remote repositories
                 PackageG => 1,
                 # ...
             },
             DependencyFail => {     # packages with dependencies that fail on any of the above reasons
                 PackageH => 1,
                 # ...
             }
         },
     );



PackageUpgradeAllDataDelete()
=============================


Removes all Package Upgrade All data from the database.


.. code-block:: perl

     my $Success = $PackageObject->PackageUpgradeAllDataDelete();



PackageUpgradeAllIsRunning()
============================


Check if there is a Package Upgrade All process running by checking the scheduler tasks and the
system data.


.. code-block:: perl

     my %Result = $PackageObject->PackageUpgradeAllIsRunning();


Returns:


.. code-block:: perl

     %Result = (
         IsRunning      => 1,             # or 0 if it is not running
         UpgradeStatus  => 'Running',     # (optional) 'Running' or 'Finished' or 'TimedOut',
         UpgradeSuccess => 1,             # (optional) 1 or 0,
     );



CheckVersion()
==============


Compare the two version strings $VersionNew and $VersionInstalled.
The type is either 'Min' or 'Max'.
'Min' returns a true value if $VersionInstalled >= $VersionNew.
'Max' returns a true value if $VersionInstalled < $VersionNew.
Otherwise undef is returned in scalar context.


.. code-block:: perl

     my $CheckOk = $PackageObject->CheckVersion(
         VersionNew       => '1.3.92',
         VersionInstalled => '1.3.91',
         Type             => 'Min',     # 'Min' or 'Max'
         ExternalPackage  => 1,         # optional
     )



GetRequiredModules()
====================


This function returns an array of hashes that contains information
about \ ``RequiredModules``\  of the .sopm-file.


.. code-block:: perl

     my $ModuleRequired = $PackageObject->GetRequiredModules(
         Structure => \%Structure,       # return of PackageParse()
     );


Returns:


.. code-block:: perl

     my $ModuleRequired = (
         {
           'Name'        => 'GD::Graph',
           'Version'     => undef,
           'IsInstalled' => 'Problem',
         },
         {
           'Name'        => 'Data::Dumper',
           'Version'     => '2.179',
           'IsInstalled' => 'OK',
         }
     );



_CheckVersion()
===============


Deprecated. Please use the new CheckVersion() instead of this.


_PackageUninstallMerged()
=========================


ONLY CALL THIS METHOD FROM A DATABASE UPGRADING SCRIPT DURING FRAMEWORK UPDATES
OR FROM A CODEUPGRADE SECTION IN AN SOPM FILE OF A PACKAGE THAT INCLUDES A MERGED FEATURE ADDON.

Uninstall an already framework (or module) merged package.

Package files that are not in the framework ARCHIVE file will be deleted, DatabaseUninstall() and
CodeUninstall are not called.


.. code-block:: perl

     $Success = $PackageObject->_PackageUninstallMerged(
         Name        => 'some package name',
         Home        => 'OTRS Home path',      # Optional
         DeleteSaved => 1,                     # or 0, 1 Default, Optional: if set to 1 it also
                                               # delete .save files
     );



_PackageInstallOrderListGet()
=============================


Helper function for PackageInstallOrderListGet() to process the packages and its dependencies recursively.


.. code-block:: perl

     my $Success = $PackageObject->_PackageInstallOrderListGet(
         Callers           => {      # packages in the recursive chain
             PackageA => 1,
             # ...
         },
         InstalledVersions => {      # list of installed packages and their versions
             PackageA => '1.0.1',
             # ...
         },
         TargetPackages => {
             PackageA => '1.0.1',    # list of packages to process
             # ...
         }
         InstallOrder => {           # current install order
             PackageA => 2,
             PacakgeB => 1,
             # ...
         },
         Failed => {                 # current failed packages or dependencies
             Cyclic => {},
             NotFound => {},
             WrongVersion => {},
             DependencyFail => {},
         },
         OnlinePackageLookup => {
             PackageA => {
                 Name    => 'PackageA',
                 Version => '1.0.1',
                 PackageRequired => [
                     {
                         Content => 'PackageB',
                         Version => '1.0.2',
                     },
                     # ...
                 ],
             },
         },
         IsDependency => 1,      # 1 or 0
     );



_PackageOnlineListGet()
=======================


Helper function that gets the full list of available remote packages.


.. code-block:: perl

     my %OnlinePackages = $PackageObject->_PackageOnlineListGet();


Returns:


.. code-block:: perl

     %OnlinePackages = (
         PackageList => [
             {
                 Name        => 'Test',
                 Version     => '6.0.20',
                 File        => 'Test-6.0.20.opm',
                 ChangeLog   => 'InitialRelease',
                 Description => 'Test package.',
                 Framework   => [
                     {
                         Content => '6.0.x',
                         Minimum => '6.0.2',
                         # ... ,
                     }
                 ],
                 License => 'GNU GENERAL PUBLIC LICENSE Version 3, November 2007',
                 PackageRequired => [
                     {
                         Content => 'TestRequitement',
                         Version => '6.0.20',
                         # ... ,
                     },
                 ],
                 URL    => 'http://otrs.org/',
                 Vendor => 'OTRS AG',
             },
             # ...
         ];
         PackageLookup  => {
             Test => {
                    URL        => 'http://otrs.org/',
                     Version   => '6.0.20',
                     File      => 'Test-6.0.20.opm',
             },
             # ...
         },
     );



_RepositoryCacheClear()
=======================


Remove all caches related to the package repository.


.. code-block:: perl

     my $Success = $PackageObject->_RepositoryCacheClear();



_ConfigurationFilesDeployCheck()
================================


check if package configuration files are deployed correctly.


.. code-block:: perl

     my $Success = $PackageObject->_ConfigurationFilesDeployCheck(
         Name    => 'Application A',
         Version => '1.0',
     );