#######
Service
#######


****
NAME
****


Kernel::System::Service - service lib


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


All service functions.


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


new()
=====


create an object


.. code-block:: perl

     my $ServiceObject = $Kernel::OM->Get('Kernel::System::Service');



ServiceList()
=============


return a hash list of services


.. code-block:: perl

     my %ServiceList = $ServiceObject->ServiceList(
         Valid        => 0,   # (optional) default 1 (0|1)
         KeepChildren => 0,   # (optional) default 0 (0|1); when Valid=1 set to 1 if you want to include also valid child services of invalid services.
         UserID       => 1,
     );



ServiceListGet()
================


return a list of services with the complete list of attributes for each service


.. code-block:: perl

     my $ServiceList = $ServiceObject->ServiceListGet(
         Valid  => 0,   # (optional) default 1 (0|1)
         UserID => 1,
     );
 
     returns
 
     $ServiceList = [
         {
             ServiceID  => 1,
             ParentID   => 0,
             Name       => 'MyService',
             NameShort  => 'MyService',
             ValidID    => 1,
             Comment    => 'Some Comment',
             CreateTime => '2011-02-08 15:08:00',
             ChangeTime => '2011-06-11 17:22:00',
             CreateBy   => 1,
             ChangeBy   => 1,
 
             # ITSMCore (if installed)
             TypeID           => 16,
             Type             => 'Backend',
             Criticality      => '3 normal',
             CurInciStateID   => 1,
             CurInciState     => 'Operational',
             CurInciStateType => 'operational',
         },
         {
             ServiceID  => 2,
             ParentID   => 1,
             Name       => 'MyService::MySubService',
             NameShort  => 'MySubService',
             ValidID    => 1,
             Comment    => 'Some Comment',
             CreateTime => '2011-02-08 15:08:00',
             ChangeTime => '2011-06-11 17:22:00',
             CreateBy   => 1,
             ChangeBy   => 1,
 
             # ITSMCore (if installed)
             TypeID           => 16,
             Type             => 'Backend',
             Criticality      => '3 normal',
             CurInciStateID   => 1,
             CurInciState     => 'Operational',
             CurInciStateType => 'operational',
         },
         # ...
     ];



ServiceGet()
============


return a service as hash


.. code-block:: perl

     my %ServiceData = $ServiceObject->ServiceGet(
         ServiceID => 123,
         UserID    => 1,
     );
 
     my %ServiceData = $ServiceObject->ServiceGet(
         Name    => 'Service::SubService',
         UserID  => 1,
     );
 
     # With installed ITSM:
     my %ServiceData = $ServiceObject->ServiceGet(
         ServiceID     => 123,
         IncidentState => 1, # Optional, returns CurInciState etc.
         UserID        => 1,
     );


Returns:


.. code-block:: perl

     $ServiceData{ServiceID}
     $ServiceData{ParentID}
     $ServiceData{Name}
     $ServiceData{NameShort}
     $ServiceData{ValidID}
     $ServiceData{Comment}
     $ServiceData{CreateTime}
     $ServiceData{CreateBy}
     $ServiceData{ChangeTime}
     $ServiceData{ChangeBy}
 
     # ITSMCore (if installed)
     $ServiceData{TypeID}
     $ServiceData{Type}
     $ServiceData{Criticality}
     $ServiceData{CurInciStateID}    # Only if IncidentState is 1
     $ServiceData{CurInciState}      # Only if IncidentState is 1
     $ServiceData{CurInciStateType}  # Only if IncidentState is 1



ServiceLookup()
===============


return a service name and id


.. code-block:: perl

     my $ServiceName = $ServiceObject->ServiceLookup(
         ServiceID => 123,
     );
 
     or
 
     my $ServiceID = $ServiceObject->ServiceLookup(
         Name => 'Service::SubService',
     );



ServiceAdd()
============


add a service


.. code-block:: perl

     my $ServiceID = $ServiceObject->ServiceAdd(
         Name     => 'Service Name',
         ParentID => 1,              # (optional)
         ValidID  => 1,
         Comment  => 'Comment',      # (optional)
         UserID   => 1,
 
         # ITSMCore (if installed)
         TypeID      => 2,
         Criticality => '3 normal',
     );



ServiceUpdate()
===============


update an existing service


.. code-block:: perl

     my $True = $ServiceObject->ServiceUpdate(
         ServiceID => 123,
         ParentID  => 1,                 # (optional)
         Name      => 'Service Name',
         ValidID   => 1,
         Comment   => 'Comment',         # (optional)
         UserID    => 1,
 
         # ITSMCore (if installed)
         TypeID      => 2,
         Criticality => '3 normal',
     );



ServiceSearch()
===============


return service ids as an array


.. code-block:: perl

     my @ServiceList = $ServiceObject->ServiceSearch(
         Name   => 'Service Name', # (optional)
         Limit  => 122,            # (optional) default 1000
         UserID => 1,
 
         # ITSMCore (if installed)
         TypeIDs       => 2,
         Criticalities => [ '2 low', '3 normal' ],
     );



CustomerUserServiceMemberList()
===============================


returns a list of customeruser/service members


.. code-block:: perl

     ServiceID: service id
     CustomerUserLogin: customer user login
     DefaultServices: activate or deactivate default services
 
     Result: HASH -> returns a hash of key => service id, value => service name
             Name -> returns an array of user names
             ID   -> returns an array of user ids
 
     Example (get services of customer user):
 
     $ServiceObject->CustomerUserServiceMemberList(
         CustomerUserLogin => 'Test',
         Result            => 'HASH',
         DefaultServices   => 0,
     );
 
     Example (get customer user of service):
 
     $ServiceObject->CustomerUserServiceMemberList(
         ServiceID => $ID,
         Result    => 'HASH',
     );



CustomerUserServiceMemberAdd()
==============================


to add a member to a service

if 'Active' is 0, the customer is removed from the service


.. code-block:: perl

     $ServiceObject->CustomerUserServiceMemberAdd(
         CustomerUserLogin => 'Test1',
         ServiceID         => 6,
         Active            => 1,
         UserID            => 123,
     );



ServicePreferencesSet()
=======================


set service preferences


.. code-block:: perl

     $ServiceObject->ServicePreferencesSet(
         ServiceID => 123,
         Key       => 'UserComment',
         Value     => 'some comment',
         UserID    => 123,
     );



ServicePreferencesGet()
=======================


get service preferences


.. code-block:: perl

     my %Preferences = $ServiceObject->ServicePreferencesGet(
         ServiceID => 123,
         UserID    => 123,
     );



ServiceParentsGet()
===================


return an ordered list all parent service IDs for the given service from the root parent to the
current service parent


.. code-block:: perl

     my $ServiceParentsList = $ServiceObject->ServiceParentsGet(
         ServiceID => 123,
         UserID    => 1,
     );
 
     returns
 
     $ServiceParentsList = [ 1, 2, ...];



GetAllCustomServices()
======================


get all custom services of one user


.. code-block:: perl

     my @Services = $ServiceObject->GetAllCustomServices( UserID => 123 );



_ServiceGetCurrentIncidentState()
=================================


Returns a hash with the original service data,
enhanced with additional service data about the current incident state,
based on configuration items and other services.


.. code-block:: perl

     %ServiceData = $ServiceObject->_ServiceGetCurrentIncidentState(
         ServiceData => \%ServiceData,
         Preferences => \%Preferences,
         UserID      => 1,
     );