##########
Webservice
##########


****
NAME
****


Kernel::System::DynamicField::Webservice - Dynamic field web service lib


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


new()
=====



.. code-block:: perl

     Don't use the constructor directly, use the ObjectManager instead:
 
     my $DynamicFieldWebserviceObject = $Kernel::OM->Get('Kernel::System::DynamicField::Webservice');



Test()
======


Tests given web-service configuration by connecting and querying the web-service.


.. code-block:: perl

     my $Result = $DynamicFieldWebserviceObject->Test(
         Config   => {
             Webservice               => $Param{Webservice},
             InvokerSearch            => $Param{InvokerSearch},
             InvokerGet               => $Param{InvokerGet},
             Backend                  => $Param{Backend},
             StoredValue              => $Param{StoredValue},
             DisplayedValues          => $Param{DisplayedValues},
             DisplayedValuesSeparator => $Param{DisplayedValuesSeparator},
             Limit                    => $Param{Limit},
             SearchTerms              => $Param{SearchTerms},
         },
         DynamicFieldName => 'DFName1',      # optional
         FieldType        => 'WebserviceDropdown',
         TicketID         => 65, # optional
         UserID           => 1,
         UserType         => 'Agent',                                        # optional 'Agent' or 'Customer'
     );



Autocomplete()
==============


Retrieves data for auto-complete list of given dynamic field config.


.. code-block:: perl

     my $Results = $DynamicFieldWebserviceObject->Autocomplete(
         DynamicFieldConfig => {},
         SearchTerms        => 'my search',
         TicketID           => 65, # optional
         UserID             => 1,
         UserType           => 'Agent',                # optional 'Agent' or 'Customer'
     );
 
     $Results is an (empty) array ref or undef on failure.



AutoFill()
==========


Retrieves data for auto-fill list of given dynamic field config.


.. code-block:: perl

     my $Results = $DynamicFieldWebserviceObject->AutoFill(
         DynamicFieldConfig => {},
         SearchTerms        => 'my search',
         TicketID           => 65, # optional
         UserID             => 1,
         UserType           => 'Agent',                # optional 'Agent' or 'Customer'
     );
 
     $Results is an (empty) array ref or undef on failure.



Search()
========


Executes search in configured dynamic field web-service.


.. code-block:: perl

     my $Results = $DynamicFieldWebserviceObject->Search(
         DynamicFieldConfig => $DynamicFieldConfig,
         SearchTerms        => 'searchstring',   # or array
         SearchType         => 'LIKE',           # LIKE | EQUALS
         SearchKeys         => 'Key',            # id, depends on web service
         Attributes         => [
             'Key',
             'Value',
             # or
 
             'Name',
             'ID',
         ],
         TicketID => 65, # optional
         UserID   => 1,
     );
 
     $Results is an (empty) array ref of the follwing form or undef on failure.
 
     my $Results = [
         {
             'Key'   => 'Znuny3',
             'Value' => 'Znuny3'
         },
         {
             'Key'   => 'Rocks4',
             'Value' => 'Rocks4'
         }
         # ...
     ];
 
     # or
 
     my $Results = [
         {
             'Key'  => 'Znuny3',
             'ID'   => 'Znuny3',
             'Name' => 'Znuny3'
         },
         {
             'Key'  => 'Rocks4',
             'ID'   => 'Rocks4',
             'Name' => 'Rocks4'
         }
         # ...
     ];



AdditionalRequestDataGet()
==========================


Returns additional data for request. Agent (User) or Customer (CustomerUser) data.


.. code-block:: perl

     my %Data = $DynamicFieldWebserviceObject->AdditionalRequestDataGet(
         UserID   => 123,
         UserType => 'Agent',            # optional (Agent|Customer)
     );


Returns:


.. code-block:: perl

     my %Data = $DynamicFieldWebserviceObject->AdditionalRequestDataGet(
         UserID   => 123,
         UserType => 'Agent',            # optional (Agent|Customer)
     );
 
     my %Data = (
         'UserID'                       => 1,
         'UserEmail'                    => 'root@localhost',
         'UserFirstname'                => 'Admin',
         'UserFullname'                 => 'Admin OTRS',
         'UserLastLogin'                => '1629733655',
         'UserLastname'                 => 'OTRS',
         'UserLogin'                    => 'root@localhost',
         [...]
     );
 
     # or
 
     my %Data = $DynamicFieldWebserviceObject->AdditionalRequestDataGet(
         UserID   => 123,
         UserType => 'Customer',            # optional (Agent|Customer)
     );
 
     my %Data = (
         'UserLogin'              => '9326500963200000',
         'UserID'                 => '9326500963200000',
         'UserFirstname'          => 'Firstname',
         'UserLastname'           => 'Lastname',
         'UserFullname'           => 'Firstname Lastname',
         'UserEmail'              => 'znuny@localunittest.com',
         'UserCustomerID'         => 'znuny',
         'Source'                 => 'CustomerUser',
         [...]
     );



AdditionalDynamicFieldValuesStore()
===================================


stores additional values from web-service in dynamic fields


.. code-block:: perl

     my $Success = $DynamicFieldWebserviceObject->AdditionalDynamicFieldValuesStore(
         DynamicFieldConfig => {},
         TicketID           => 1234,
         UserID             => 1234,
     );
 
     my $Success = 1;



DisplayValueGet()
=================


Fetches display value(s) for given dynamic field config and value(s).
Hashref is used for BuildSelection or input fields.


.. code-block:: perl

     my $DisplayValue = $DynamicFieldWebserviceObject->DisplayValueGet(
         DynamicFieldConfig => {},
         Value              => 'My value', # or array of values
         TicketID           => 65, # optional
         UserID             => 1, # optional
     );
 
     If one value was given, it returns its display value as a string
     or the given value if no display value could be found.
 
     If an array of values was given (even with only one element), it returns a hash reference:
     my $DisplayValues = {
         'My value 1' => 'My display value 1',
         'My value 2' => 'My value 2', # if display value was not found
     };



_DisplayValueAssemble()
=======================


Assembles display value for given web-service result hash (after search).


.. code-block:: perl

     my $DisplayValue = $DynamicFieldWebserviceObject->_DisplayValueAssemble(
         DynamicFieldConfig => {},
         Result             => {
             Key   => 'value col 1',
             Value => 'value col 2',
             # ...
         },
     );
 
     my $DisplayValue = 'value col 1 - value col 2';



_DisplaySeparatorGet()
======================


Returns the display keys separator to use.


.. code-block:: perl

     my $DisplaySeparator = $DynamicFieldWebserviceObject->_DisplaySeparatorGet(
         DisplaySeparator => '', # this (or omitting the parameter) will be turned into ' '
     );



Template()
==========


Returns the current value or values as string according to the desired template.
This function is only needed for WebserviceMultiselect (multiselect).


.. code-block:: perl

     my $Value = $DynamicFieldWebserviceObject->Template(
         DynamicFieldConfig => \%DynamicFieldConfig,
         Value              => ['first','second', 'third'], # or a scalar value
         Type               => 'Value', # optional; or 'Title'
         ContentType        => 'ASCII', # optional; 'HTML' is default,
         TemplateType       => 'default', # optional; or: 'separator', 'wordwrap', 'list'
     );


Returns:


.. code-block:: perl

     my $Value = 'first, second, third';                                     # default
     my $Value = 'first second third';                                       # separator '<space>'
     my $Value = 'first<br>second<br>third';                                 # wordwrap 'HTML'
     my $Value = 'first\nsecond\nthird';                                     # wordwrap 'ASCII'
     my $Value = '<ul><li>first<\li><li>second<\li><li>third<\li></ul>';     # list 'HTML'
     my $Value = '- first\n- second\n- third';                               # list 'ASCII'



TemplateTypeList()
==================


Returns a list of template types.
This function is only needed for WebserviceMultiselect (multiselect).


.. code-block:: perl

     my %TemplateTypeList = $Object->TemplateTypeList();


Returns:


.. code-block:: perl

     my %TemplateTypeList = (
         default   => 'default',
         separator => 'separator',
         wordwrap  => 'wordwrap',
         list      => 'list',
     );



BackendList()
=============


Returns a list of backends which can be used for this dynamic field web service.


.. code-block:: perl

     my %BackendList = $DynamicFieldWebserviceObject->BackendList();


Returns:


.. code-block:: perl

     my %BackendList = (
         DirectRequest => DirectRequest,
     );



BackendListGet()
================


Returns a list of backends which can be used for this dynamic field web service.


.. code-block:: perl

     my %BackendListGet = $DynamicFieldWebserviceObject->BackendListGet();


Returns:


.. code-block:: perl

     my %BackendListGet = (
         DirectRequest => DirectRequest,
     );



_BackendConfigGet
=================


Fetches backend config (web-service) of dynamic field.


.. code-block:: perl

     my $BackendConfig = $DynamicFieldWebserviceObject->_BackendConfigGet(
         DynamicFieldConfig => {},
     );
 
     my $BackendConfig = {
         Backend       => 'DirectRequest',
         InvokerSearch => 'TestSearch',
         InvokerGet    => 'TestGet',
         Webservice    => 'DynamicFieldWebserviceTest'
     };



_BackendObjectGet
=================


Fetches backend object (web-service) to access web-service of dynamic field.


.. code-block:: perl

     my $BackendObject = $DynamicFieldWebserviceObject->_BackendObjectGet(
         BackendConfig => {
             Backend       => 'DirectRequest',
             InvokerSearch => 'TestSearch',
             InvokerGet    => 'TestGet',
             Webservice    => 'DynamicFieldWebserviceTest'
         },
     );