codebar-ag/laravel-docuware

DocuWare integration with Laravel.

This package was developed to give you a quick start to communicate with the DocuWare REST API. It is used to query the most common endpoints.

⚠️ This package is not designed as a replacement of the official DocuWare REST API. See the documentation if you need further functionality. ⚠️

Navigation

• 💡 What is DocuWare?
• 🛠 Requirements
• ⚙️ Installation
• 🏗 Usage
  • Getting Started with OAuth
  • Getting a new token via Username & Password:
  • Getting a new token via Username & Password (Trusted User):
  • Available Requests
• Extending the connector (EXAMPLE)
  • Create a new connector
  • Use the new connector
• 🖼 Make encrypted URLs
• 🏋️ Document Index Fields DTO showcase
• 📦 Caching requests
• 💥 Exceptions explained
• ✨ Events
• 🔧 Configuration file
• 🚧 Testing
• 📝 Changelog
• ✏️ Contributing
• 🧑‍💻 Security Vulnerabilities
• 🙏 Credits
• 🎭 License

💡 What is DocuWare?

DocuWare provides cloud document management and workflow automation software that enables you to digitize, secure and work with business documents, then optimize the processes that power the core of your business.

🛠 Requirements

Version Support

Version	PHP Version	Laravel Version	DocuWare Cloud Access
> v11.0 (alpha)	^8.2	^11.*	✅
> v4.0	^8.2	^11.*	✅
> v3.0	^8.2	^10.*	✅
> v2.0	^8.1	^9.*	✅
> v1.2	^8.1	^9.*	✅
< v1.2	^8.0	^8.*	✅

Current Support

Group	Request	Supported	TODO
Authentication/OAuth	1. Get Responsible Identity Service	✅
Authentication/OAuth	2. Get Identity Service Configuration	✅
Authentication/OAuth	3.a Request Token w/ Username & Password	✅
Authentication/OAuth	3.b Request Token w/ a DocuWare Token	🕣
Authentication/OAuth	3.c Request Token w/ Username & Password (Trusted User)	🕣
Authentication/OAuth	3.d.1 Obtain Windows Authorization (On Premises Only)	🕣
Authentication/OAuth	3.d.2 Request Token /w a Windows Account (On Premises Only)	🕣
General/Organisation	Get Login Token	✅
General/Organisation	Get Organization	✅
General/Organisation	Get All File Cabinets and Document Trays	✅
General/UserManagement	Get Users by ID	✅
General/UserManagement	Get Users of a Role	✅
General/UserManagement	Get Users of a Group	✅
General/UserManagement	Create User	✅
General/UserManagement	Update User	✅
General/UserManagement	Get Groups	✅
General/UserManagement	Get All Groups for a Specific User	✅
General/UserManagement	Add User to a Group	✅
General/UserManagement	Remove User from a Group	✅
General/UserManagement	Get Roles	✅
General/UserManagement	Get All Roles for a Specific User	✅
General/UserManagement	Add User to a Role	✅
General/UserManagement	Remove User from a Role	✅
FileCabinets/General	Get File Cabinet Information	✅
FileCabinets/General	Get Total Number of Documents	✅
FileCabinets/Dialogs	Get All Dialogs	✅
FileCabinets/Dialogs	Get a Specific Dialog	✅
FileCabinets/Dialogs	Get Dialogs of a Specific Type	✅
FileCabinets/Search	Get Documents from a File Cabinet	✅
FileCabinets/Search	Get a Specific Document From a File Cabinet	✅
FileCabinets/Search	Search for Documents in a Single File Cabinet	✅
FileCabinets/Search	Search for Documents in Multiple File Cabinets	✅
FileCabinets/CheckInCheckOut	Check-out & Download a Document	🕣
FileCabinets/CheckInCheckOut	Check-in a Document from the File System	🕣
FileCabinets/CheckInCheckOut	Undo Check-out	🕣
FileCabinets/SelectLists	Get Select Lists & Get Filtered Select Lists	✅
FileCabinets/Upload	Create Data Record	✅
FileCabinets/Upload	Append File(s) to a Data Record	✅
FileCabinets/Upload	Upload a Single File for a Data Record	❌	-
FileCabinets/Upload	Create a Data Record & Upload File	❌	-
FileCabinets/Upload	Create Data Record & Upload File Using Store Dialog	❌	-
FileCabinets/Upload	Append a Single PDF to a Document	❌	-
FileCabinets/Upload	Replace a PDF Document Section	❌	-
FileCabinets/BatchIndexFieldsUpdate	Batch Update Index Fields By Id	❌	-
FileCabinets/BatchIndexFieldsUpdate	Batch Update Index Fields By Search	❌	-
FileCabinets/BatchIndexFieldsUpdate	Batch Append/Update Keyword Fields By Id	❌	-
Documents/UpdateIndexValues	Update Index Values	✅
Documents/UpdateIndexValues	Update Table Field Values	❌	- ?
Documents/ModifyDocuments	Transfer Document	✅
Documents/ModifyDocuments	Delete Document	✅
Documents/ClipUnclip&StapleUnstaple	Clip	✅
Documents/ClipUnclip&StapleUnstaple	Unclip	✅
Documents/ClipUnclip&StapleUnstaple	Staple	✅
Documents/ClipUnclip&StapleUnstaple	Unstaple	✅
Documents/AnnotationsStamps	AddStampWithPosition	🕣
Documents/AnnotationsStamps	AddStampWithBestPosition	🕣
Documents/AnnotationsStamps	AddTextAnnotation	🕣
Documents/AnnotationsStamps	AddRectEntryAnnotation	🕣
Documents/AnnotationsStamps	AddLineEntryAnnotation	🕣
Documents/AnnotationsStamps	AddPolyLineEntryAnnotation	❌	-
Documents/AnnotationsStamps	DeleteAnnotation	❌	-
Documents/AnnotationsStamps	UpdateTextAnnotation	🕣
Documents/AnnotationsStamps	Get Stamps	❌	-
Documents/DocumentsTrashBin	Get Documents	✅
Documents/DocumentsTrashBin	Delete Documents	✅
Documents/DocumentsTrashBin	Restore Documents	✅
Documents/ApplicationProperties	Get Application Properties	✅
Documents/ApplicationProperties	Add Application Properties	✅
Documents/ApplicationProperties	Delete Application Properties	✅
Documents/ApplicationProperties	Update Application Properties	✅
Documents/Sections	Get All Sections from a Document	✅
Documents/Sections	Get a Specific Section	✅
Documents/Sections	Delete Section	✅
Documents/Sections/Textshot	Get Textshot for a Specific Section	✅
Documents/Download	Download Document	✅
Documents/Download	Download Section	✅
Documents/Download	Download Thumbnail	✅
Workflow	Get Document Workflow History	✅
Workflow	Get Document Workflow History Steps	✅

⚙️ Installation

You can install the package via composer:

composer require codebar-ag/laravel-docuware

Add the following environment variables to your .env file:

DOCUWARE_URL=https://domain.docuware.cloud
DOCUWARE_USERNAME=user@domain.test
DOCUWARE_PASSWORD=password
DOCUWARE_PASSPHRASE="passphrase"

With the passphrase we are able to encrypt the URLs.

⚠️ You need to escape backslashes in your passphrase with another backslash:

# ❌ Passphrase contains a backslash and is not escaped:
DOCUWARE_PASSPHRASE="a#bcd>2~C1'abc\#"

# ✅ We need to escape the backslash with another backslash:
DOCUWARE_PASSPHRASE="a#bcd>2~C1'abc\\#"

🏗 Usage

Getting Started with OAuth

This package automatically handles the generation of OAuth token for you and stores them in cache.

Getting a new token via Username & Password:

use CodebarAg\DocuWare\Connectors\DocuWareConnector;
use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentials;

$connector = new DocuWareConnector(
    configuration: new ConfigWithCredentials(
        username: 'username',
        password: 'password',
    )
);

Getting a new token via Username & Password (Trusted User):

use CodebarAg\DocuWare\Connectors\DocuWareConnector;
use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentialsTrustedUser;

$connector = new DocuWareConnector(
    configuration: new ConfigWithCredentialsTrustedUser(
        username: 'username',
        password: 'password',
        impersonatedUsername: 'impersonatedUsername',
    )
);

Available Requests

• General
  • Organisation
  • User Management
    • Get Users
    • Create/Update Users
    • Get/Modify Groups
    • Get/Modify Roles
• File Cabinets
  • General
  • Dialogs
  • Search
  • Check/In & Check/Out
  • Select Lists
  • Upload
  • Batch Index Fields Update
• Documents
  • Update Index Values
  • Modify Documents
  • Clip/Unclip & Staple/Unstaple
  • Annotations & Stamps
  • Documents Trash Bin
  • Application Properties
  • Sections
  • Download
• Workflow

Extending the connector (EXAMPLE)

We understand it may be repetitive to pass the configuration every time you create a new connector.

You can extend the connector and set the configuration once.

Create a new connector

<?php

namespace App\Connectors;

use CodebarAg\DocuWare\Connectors\DocuWareConnector;
use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentials;

class YourOwnDocuWareConnector extends DocuWareConnector
{
    public function __construct() {
        $configuration = new ConfigWithCredentials(
            username: 'username',
            password: 'password',
        );
    
        parent::__construct($configuration);
    }
}

Use the new connector

use App\Connectors\YourOwnDocuWareConnector;
use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentials;

$connector = new YourOwnDocuWareConnector();

🖼 Make encrypted URLs

• Encrypted URLs

🏋️ Document Index Fields DTO showcase

• Document Index Fields DTO

📦 Caching requests

• Caching Requests

💥 Exceptions explained

• Exceptions

✨ Events

The Following events will be fired:

use CodebarAg\DocuWare\Events\DocuWareResponseLog;

// Log each response from the DocuWare REST API.
DocuWareResponseLog::class => [
    //
],

🔧 Configuration file

You can publish the config file with:

php artisan vendor:publish --provider="CodebarAg\DocuWare\DocuWareServiceProvider" --tag="docuware-config"

This is the contents of the published config file:

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Cache driver
    |--------------------------------------------------------------------------
    | You may like to define a different cache driver than the default Laravel cache driver.
    |
    */

    'cache_driver' => env('DOCUWARE_CACHE_DRIVER', env('CACHE_DRIVER', 'file')),

    /*
    |--------------------------------------------------------------------------
    | Requests timeout
    |--------------------------------------------------------------------------
    | This variable is optional and only used if you want to set the request timeout manually.
    |
    */

    'timeout' => env('DOCUWARE_TIMEOUT', 15),

    /*
    |--------------------------------------------------------------------------
    | DocuWare Credentials
    |--------------------------------------------------------------------------
    |
    | Before you can communicate with the DocuWare REST-API it is necessary
    | to enter your credentials. You should specify a url containing the
    | scheme and hostname. In addition add your username and password.
    |
    */

    'credentials' => [
        'url' => env('DOCUWARE_URL'),
        'username' => env('DOCUWARE_USERNAME'),
        'password' => env('DOCUWARE_PASSWORD'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Passphrase
    |--------------------------------------------------------------------------
    |
    | In order to create encrypted URLs we need a passphrase. This enables a
    | secure exchange of DocuWare URLs without anyone being able to modify
    | your query strings. You can find it in the organization settings.
    |
    */

    'passphrase' => env('DOCUWARE_PASSPHRASE'),

    /*
    |--------------------------------------------------------------------------
    | Configurations
    |--------------------------------------------------------------------------
    |
    */
    'configurations' => [
        'search' => [
            'operation' => 'And',

            /*
             * Force Refresh
             * Determine if result list is retrieved from the cache when ForceRefresh is set
             * to false (default) or always a new one is executed when ForceRefresh is set to true.
             */

            'force_refresh' => true,
            'include_suggestions' => false,
            'additional_result_fields' => [],
        ],
        'cache' => [
            'driver' => env('DOCUWARE_CACHE_DRIVER', env('CACHE_DRIVER', 'file')),
            'lifetime_in_seconds' => env('DOCUWARE_CACHE_LIFETIME_IN_SECONDS', 60),
        ],
    ],
];

🚧 Testing

Copy your own phpunit.xml-file.

cp phpunit.xml.dist phpunit.xml

Modify environment variables in the phpunit.xml-file:

<env name="DOCUWARE_TOKEN" value=""/>
<env name="DOCUWARE_URL" value="https://domain.docuware.cloud"/>
<env name="DOCUWARE_USERNAME" value="user@domain.test"/>
<env name="DOCUWARE_PASSWORD" value="password"/>
<env name="DOCUWARE_PASSPHRASE" value="passphrase"/>
<env name="DOCUWARE_TIMEOUT" value="30"/>
<env name="DOCUWARE_CACHE_LIFETIME_IN_SECONDS" value="0"/>

<env name="DOCUWARE_TESTS_FILE_CABINET_ID" value=""/>
<env name="DOCUWARE_TESTS_DIALOG_ID" value=""/>
<env name="DOCUWARE_TESTS_BASKET_ID" value=""/>
<env name="DOCUWARE_TESTS_ORGANIZATION_ID" value=""/>

Run the tests:

composer test

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

✏️ Contributing

Please see CONTRIBUTING for details.

🧑‍💻 Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

🙏 Credits

• Sebastian Fix
• Rhys Lees
• All Contributors
• Skeleton Repository from Spatie
• Laravel Package Training from Spatie

🎭 License

The MIT License (MIT). Please see License File for more information.