<commit_before><?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- $Id: operation.xml,v 1.1 2011-07-19 01:58:50 cr Exp $ -->

<section id="operation">
    <title>invoker</title>
    <para>
        The operation is used to perform an action within OTRS,
        this action is requested by the external system and can include special parameters in order
        that OTRS receives to correctly execute the action. After the action is performed, OTRS
        sends a defined confirmation the external system.
    </para>
    <section id="adding_operation">
        <title>Operation backend</title>
        <para>
            Next we will see how to develop a new Operation, each operation has to implement these
            subroutines
        </para>
        <para>
            <itemizedlist mark="round">
                <listitem>
                    <para>new</para>
                </listitem>
                <listitem>
                    <para>Run</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            We should implement each one of this methods in order to be able to execute the action
            handled by the provider ('Kernel/GenericInterface/Provider.pm').
        </para>
        <section id="operation_code_example">
            <title>Code example</title>
            <para>
                In this section a sample operation module is shown and each subroutine is explained.
            </para>
            <para>
                <programlisting><![CDATA[
# --
# Kernel/GenericInterface/Operation/Test/Test.pm - GenericInterface test operation backend
# Copyright (C) 2001-2011 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (AGPL). If you
# did not receive this file, see http://www.gnu.org/licenses/agpl.txt.
# --

package Kernel::GenericInterface::Operation::Test::Test;

use strict;
use warnings;

use Kernel::System::VariableCheck qw(IsHashRefWithData);

use vars qw(@ISA $VERSION);
$VERSION = qw($Revision: 1.1 $) [1];
                ]]></programlisting>
            </para>
            <para>
                This is common header that can be found in common OTRS modules. The class/package
                name is declared via the package keyword.
            </para>
            <para>
                We also include VariableCheck module to perform certain validation over some
                variables.
            </para>
            <para>
                <programlisting><![CDATA[
sub new {
    my ( $Type, %Param ) = @_;

    my $Self = {};
    bless( $Self, $Type );

    # check needed objects
    for my $Needed (qw(DebuggerObject)) {
        if ( !$Param{$Needed} ) {
            return {
                Success      => 0,
                ErrorMessage => "Got no $Needed!"
            };
        }

        $Self->{$Needed} = $Param{$Needed};
    }

    return $Self;
}
                ]]></programlisting>
            </para>
            <para>
                The constructor 'new' creates a new instance of the class. According to the coding
                guidelines objects of other classes that are needed in this module have to be
                created in "new".
            </para>
            <para>
                <programlisting><![CDATA[
sub Run {
    my ( $Self, %Param ) = @_;

    # check data - only accept undef or hash ref
    if ( defined $Param{Data} && ref $Param{Data} ne 'HASH' ) {
        return $Self->{DebuggerObject}->Error(
            Summary => 'Got Data but it is not a hash ref in Operation Test backend)!'
        );
    }

    if ( defined $Param{Data} && $Param{Data}->{TestError} ) {
        return {
            Success      => 0,
            ErrorMessage => "Error message for error code: $Param{Data}->{TestError}",
            Data         => {
                ErrorData => $Param{Data}->{ErrorData},
            },
        };
    }

    # copy data
    my $ReturnData;

    if ( ref $Param{Data} eq 'HASH' ) {
        $ReturnData = \%{ $Param{Data} };
    }
    else {
        $ReturnData = undef;
    }

    # return result
    return {
        Success => 1,
        Data    => $ReturnData,
    };
}
                ]]></programlisting>
            </para>
            <para>
                The 'Run' function is the main part of each operation, it receives all internal
                mapped data from remote system needed by the provider to execute the action,
                it performs the action and returns the result to the provider to be external mapped
                and deliver back to the remote system.
            </para>
            <para>
                This particular example returns the same data as came from the remote system,
                unless "TestError" parameter is passed in this case it returns an error.
            </para>
            <para>
                <programlisting><![CDATA[
1;

=back

=head1 TERMS AND CONDITIONS

This software is part of the OTRS project (L<http://otrs.org/>).

This software comes with ABSOLUTELY NO WARRANTY. For details, see
the enclosed file COPYING for license information (AGPL). If you
did not receive this file, see L<http://www.gnu.org/licenses/agpl.txt>.

=cut

=head1 VERSION

$Revision: 1.1 $ $Date: 2011-07-19 01:58:50 $

=cut
                ]]></programlisting>
            </para>
        </section>
    </section>
</section><commit_msg>Fixed title... sorry my fault ;-).<commit_after><?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- $Id: operation.xml,v 1.2 2011-07-19 20:09:11 cr Exp $ -->

<section id="operation">
    <title>operation</title>
    <para>
        The operation is used to perform an action within OTRS,
        this action is requested by the external system and can include special parameters in order
        that OTRS receives to correctly execute the action. After the action is performed, OTRS
        sends a defined confirmation the external system.
    </para>
    <section id="adding_operation">
        <title>Operation backend</title>
        <para>
            Next we will see how to develop a new Operation, each operation has to implement these
            subroutines
        </para>
        <para>
            <itemizedlist mark="round">
                <listitem>
                    <para>new</para>
                </listitem>
                <listitem>
                    <para>Run</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            We should implement each one of this methods in order to be able to execute the action
            handled by the provider ('Kernel/GenericInterface/Provider.pm').
        </para>
        <section id="operation_code_example">
            <title>Code example</title>
            <para>
                In this section a sample operation module is shown and each subroutine is explained.
            </para>
            <para>
                <programlisting><![CDATA[
# --
# Kernel/GenericInterface/Operation/Test/Test.pm - GenericInterface test operation backend
# Copyright (C) 2001-2011 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (AGPL). If you
# did not receive this file, see http://www.gnu.org/licenses/agpl.txt.
# --

package Kernel::GenericInterface::Operation::Test::Test;

use strict;
use warnings;

use Kernel::System::VariableCheck qw(IsHashRefWithData);

use vars qw(@ISA $VERSION);
$VERSION = qw($Revision: 1.2 $) [1];
                ]]></programlisting>
            </para>
            <para>
                This is common header that can be found in common OTRS modules. The class/package
                name is declared via the package keyword.
            </para>
            <para>
                We also include VariableCheck module to perform certain validation over some
                variables.
            </para>
            <para>
                <programlisting><![CDATA[
sub new {
    my ( $Type, %Param ) = @_;

    my $Self = {};
    bless( $Self, $Type );

    # check needed objects
    for my $Needed (qw(DebuggerObject)) {
        if ( !$Param{$Needed} ) {
            return {
                Success      => 0,
                ErrorMessage => "Got no $Needed!"
            };
        }

        $Self->{$Needed} = $Param{$Needed};
    }

    return $Self;
}
                ]]></programlisting>
            </para>
            <para>
                The constructor 'new' creates a new instance of the class. According to the coding
                guidelines objects of other classes that are needed in this module have to be
                created in "new".
            </para>
            <para>
                <programlisting><![CDATA[
sub Run {
    my ( $Self, %Param ) = @_;

    # check data - only accept undef or hash ref
    if ( defined $Param{Data} && ref $Param{Data} ne 'HASH' ) {
        return $Self->{DebuggerObject}->Error(
            Summary => 'Got Data but it is not a hash ref in Operation Test backend)!'
        );
    }

    if ( defined $Param{Data} && $Param{Data}->{TestError} ) {
        return {
            Success      => 0,
            ErrorMessage => "Error message for error code: $Param{Data}->{TestError}",
            Data         => {
                ErrorData => $Param{Data}->{ErrorData},
            },
        };
    }

    # copy data
    my $ReturnData;

    if ( ref $Param{Data} eq 'HASH' ) {
        $ReturnData = \%{ $Param{Data} };
    }
    else {
        $ReturnData = undef;
    }

    # return result
    return {
        Success => 1,
        Data    => $ReturnData,
    };
}
                ]]></programlisting>
            </para>
            <para>
                The 'Run' function is the main part of each operation, it receives all internal
                mapped data from remote system needed by the provider to execute the action,
                it performs the action and returns the result to the provider to be external mapped
                and deliver back to the remote system.
            </para>
            <para>
                This particular example returns the same data as came from the remote system,
                unless "TestError" parameter is passed in this case it returns an error.
            </para>
            <para>
                <programlisting><![CDATA[
1;

=back

=head1 TERMS AND CONDITIONS

This software is part of the OTRS project (L<http://otrs.org/>).

This software comes with ABSOLUTELY NO WARRANTY. For details, see
the enclosed file COPYING for license information (AGPL). If you
did not receive this file, see L<http://www.gnu.org/licenses/agpl.txt>.

=cut

=head1 VERSION

$Revision: 1.2 $ $Date: 2011-07-19 20:09:11 $

=cut
                ]]></programlisting>
            </para>
        </section>
    </section>
</section>
{'fraction_non_alphanumeric': 0.10677526179181956, 'fraction_numerical': 0.010024165398729079, 'mean_word_length': 1.801203309100025, 'pattern_counts': {'":': 0, '<': 137, '<?xml version=': 2, '>': 167, 'https://': 0, 'lorem ipsum': 0, 'www.': 6, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6641866', 'n_tokens_mistral': 3171, 'n_tokens_neox': 2962, 'n_words': 1052}