NAME

Kernel::System::Ticket::Article::Backend::MIMEBase::ArticleStorageAmazonS3 – S3 compatible object file system based ticket article storage interface.

DESCRIPTION

This class provides functions to manipulate ticket articles in a S3 compatible object file system. Inherits from Kernel::System::Ticket::Article::Backend::MIMEBase::Base.

The S3 service and operations are based on https://metacpan.org/pod/Paws and the related subsystem.

    $Self->{'Ticket::Article::Backend::MIMEBase::ArticleStorage'} = 'Kernel::System::Ticket::Article::Backend::MIMEBase::ArticleStorageAmazonS3';

    $Self->{'Ticket::Article::Backend::MIMEBase::ArticleStorageAmazonS3'} = {
        'Active'            => 0,
        'Endpoint'          => 'http://127.0.0.1:9000',
        'Region'            => 'local',
        'AwsAccessKey'      => 'minioadmin',
        'AwsSecretKey'      => 'minioadmin',
        'Bucket'            => 'storage',
        'TestBucket'        => 'unit-test',
        'HealthCheck'       => '/minio/health/live',
        'MaxObjectSize'     => 1024 * 1024 * 20,
        'Reconnect'         => 2,
        'BackoffOnFailure'  => 1,
        'BackoffRetryCount' => 150,
    };

PUBLIC INTERFACE

has Config

Attribute that holds the object related configuration.

Active

Controls whether the setting is active or not.

Endpoint

An URL (string) representing HTTP requests base endpoint, optional.

Region

A string representing the region that service objects will be instantiated with.

AwsAccessKey

A string representing a "login" which grants programmatic access to your resources.

AwsSecretKey

A string representing a "secret" which grants programmatic access to your resources.

Bucket

A string representing the logical container of objects.

TestBucket

A string representing the logical container of objects for testing.

HealthCheck

A string representing a (relative) URL path for a service health / alive check, optional.

MaxObjectSize

An integer representing a value in bytes to limit the size of a single object, optional.

The size MUST fit between 5 MiB and default 100 MiB.

Reconnect

Maximum attempts to connect to the service.

BackoffOnFailure

Controls whether the back off is active or not.

BackoffRetryCount

Maximum attempts to retry.

has Service

Attribute that holds the instantiated Paws::S3 service object.

has Encode

Attribute that holds an encode object reference which handles methods DecodeBase64, EncodeBase64.

has _Available

indicates whether the Endpoint is available (reachable over the network)

has _Connected

indicates whether the Service Connection was established correctly

BUILD

Set maximal upload part size.

CAVEAT! Validation and default value setting should be configured in XML config when S3 compatible article storage is official supported.

Setup

Build and return Paws::S3 service object. Verify connection to storage Endpoint and create Bucket if not existing. On any service issue the construction of an object of this class will fail with an exception.

CheckAvailability

Check if service is reachable.

Returns true on success and false on failure (additional error logging).

This will populate the _Available Attribute

Returns: Returns 1 on Success and 0 on Error and logs an Error. Returns always 1 if HealtCheck or Endpoint configuration setting is not defined. If latter is missing, we assume it's an origin Amazon S3 service endpoint derived by the the Region configuration setting. Such an endpoint is "always" available. Returns always 0 if the Setting is not activated and does not produces an Error.

_Connect

Connect to Paws::S3 Bucket correctly.

This will populate the _Connected Attribute

Returns: Returns 1 on Success and 0 on Error and logs an Error. Returns always 0 if the Setting is not activated and does not produce an Error.

ArticleDelete

Delete all article related attachments and plain article file.

    $BackendObject->ArticleDelete(
        ArticleID => 42
    );

Returns: Returns 1 on Success and 0 on Error and logs an Error. Returns always 1 if the Setting is not activated and does not produce an Error.

ArticleDeletePlain

Delete plain article file.

    $BackendObject->ArticleDeletePlain(
        ArticleID => 42
    );

Returns: Returns 1 on Success and 0 on Error and logs an Error. Returns always 1 if the Setting is not activated and does not produce an Error.

ArticleDeleteAttachment

Delete all article related attachments.

    $BackendObject->ArticleDeleteAttachment(
        ArticleID => 42
    );

Returns: Returns 1 on Success and 0 on Error and logs an Error. Returns always 1 if the Setting is not activated and does not produce an Error.

ArticleWritePlain

Store plain article.

    $BackendObject->AerticleWritePlain(
        ArticleID => 42,
        Email     => '...'
    );

Returns true on success and false on any failure (see OTRS log for further information).

ArticleWriteAttachment

Store article attachment. The metadata will be also stored in the Database.

    $BackendObject->ArticleWriteAttachment(
        ArticleID   => 42,
        Filename    => 'nice.jpeg',
        ContentType => 'image/jpeg',
        Content     => '...',           # (optional) attachment content
        Disposition => 'attachment',    # (optional) 'inline' or 'attachment'
        ContentID   => ''               # (optional) content reference
    );

Returns true on success and false on any failure (see OTRS log for further information).

ArticlePlain

Fetch plain article file (email) content.

    my $PlainArticle = $BackendObject->ArticlePlain(
        ArticleID => 42,
    );

ArticleAttachmentIndexRaw

List meta information of all article related attachments. The Metadata will come from DB.

    my %AttachmentsMetaInfo = $BackendObject->ArticleAttachmentIndexRaw(
        ArticleID => 42,                # Required
        ArticleContentPath => '...',    # Optional
        Filename => '...',              # Optional
        SkipDatabaseCheck => 1,         # Optional, default 0
    );

Returns:

    %AttachmentsMetaInfo = {
        1 => {
            ContentAlternative   => "",
            ContentID            => "",
            ContentType          => "image/jpeg",
            Disposition          => "attachment",
            Filename             => "nicer.jpeg",
            FilesizeRaw          => 313001,
            Key                  => "576/attachments/35a3e518b4e1ea4bc5b6621a6b6a8b5b",
        },
        2 => {
            ContentAlternative   => "",
            ContentID            => "",
            ContentType          => "image/jpeg",
            Disposition          => "attachment",
            Filename             => "nice.jpeg",
            FilesizeRaw          => 3531669,
            Key                  => "576/attachments/d1ede6ce808b459f2484d53709c3dc7f",
        },
        3 => {
            ContentAlternative   => "",
            ContentID            => "",
            ContentType          => "text/plain; charset=utf-8",
            Disposition          => "inline",
            Filename             => "file-1",
            FilesizeRaw          => 14,
            Key                  => "576/attachments/df0f9df5365af2a12c38974f665500ac",
        }
    };

ArticleAttachment

Fetch single article attachment meta information and content.

    my %Attachment = $BackendObject->ArticleAttachment(
        ArticleID => 42,
        FileID    => 1,
    );

Returns:

    my %Attachment = {
        Content             => "...",
        ContentAlternative  =>  "",
        ContentID           =>  "",
        ContentType         =>  "image/jpeg",
        Disposition         =>  "attachment",
        Filename            =>  "nice.jpeg",
        FilesizeRaw         =>  3531669,
        Key                 =>  "576/attachments/d1ede6ce808b459f2484d53709c3dc7f",
    }

Execute

Thin wrapper around S3 service method with exception handling, debug and error logging.