Refactor Workflows services and add new features

Updated the structure of Workflows services and incorporated new functionalities. This includes the ability to delete and launch workflows, and stop active ones. Additionally, implemented workflow templates add and delete features. Introduced Base64 encoding within the file system and now handle file not found exception. Signed-off-by: mesilov <mesilov.maxim@gmail.com>
mesilov · May 3, 2024 · 3ff8abf · 3ff8abf
1 parent 1f71b1a
commit 3ff8abf
Show file tree

Hide file tree

Showing 13 changed files with 263 additions and 106 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,16 +19,24 @@
     * `Event` – service for work with return parameters¨
         * `send` – Returns the output parameters to the activity
     * `Providers` — deprecated methods, not implemented
-    * `Workflow` — 🛠️ WIP
+    * `Workflow` — service for work with workflow instances
+        * `instances` – returns list of launched workflows
+        * `kill` – delete a launched workflow
+        * `start` – launches a workflow
+        * `terminate` – stops an active workflow
     * `Template` — 🛠️ WIP
     * `Tasks` — 🛠️ WIP
     * add `WorkflowActivityDocumentType`
 * add method `Bitrix24\SDK\Core\Credentials\AccessToken::initFromWorkflowRequest`
 * add dependencies
-  * require
-    * `symfony/console` version `^6 || ^7` 
-    * `symfony/dotenv` version `^6 || ^7` 
-
+    * require
+        * `symfony/console` version `^6 || ^7`
+        * `symfony/dotenv` version `^6 || ^7`
+        * `symfony/filesystem` version `^6 || ^7`,
+        * `symfony/mime` version `^6 || ^7`,
+* add `\Bitrix24\SDK\Infrastructure\Filesystem\Base64Encoder` for work with base64 encoding
+* add `\Bitrix24\SDK\Core\Exceptions\FileNotFoundException` if file not found
+
 ## 2.0-beta.2 — 1.04.2024
 
 ### Changed

diff --git a/composer.json b/composer.json
@@ -32,6 +32,8 @@
     "symfony/http-client": "^6 || ^7",
     "symfony/console": "^6 || ^7",
     "symfony/dotenv": "^6 || ^7",
+    "symfony/filesystem": "^6 || ^7",
+    "symfony/mime": "^6 || ^7",
     "symfony/http-client-contracts": "^2 || ^3",
     "symfony/http-foundation": "^6 || ^7",
     "symfony/event-dispatcher": "^6 || ^7",

diff --git a/src/Core/ApiLevelErrorHandler.php b/src/Core/ApiLevelErrorHandler.php
@@ -81,9 +81,14 @@ private function handleError(array $responseBody, ?string $batchCommandId = null
         if ($batchCommandId !== null) {
             $batchErrorPrefix = sprintf(' batch command id: %s', $batchCommandId);
         }
+        // fix error code responses
+        if ($errorCode === '' && strtolower($errorDescription) === strtolower('You can delete ONLY templates created by current application')) {
+            $errorCode = 'bizproc_workflow_template_access_denied';
+        }
 
         switch ($errorCode) {
             case 'access_denied':
+            case 'bizproc_workflow_template_access_denied':
                 throw new AuthForbiddenException(sprintf('%s - %s', $errorCode, $errorDescription));
             case 'query_limit_exceeded':
                 throw new QueryLimitExceededException(sprintf('query limit exceeded - too many requests %s', $batchErrorPrefix));

diff --git a/src/Core/Exceptions/FileNotFoundException.php b/src/Core/Exceptions/FileNotFoundException.php
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Core\Exceptions;
+
+class FileNotFoundException extends BaseException
+{
+}
diff --git a/src/Infrastructure/Filesystem/Base64Encoder.php b/src/Infrastructure/Filesystem/Base64Encoder.php
@@ -0,0 +1,41 @@
+<?php
+
+namespace Bitrix24\SDK\Infrastructure\Filesystem;
+
+use Bitrix24\SDK\Core\Exceptions\FileNotFoundException;
+use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\Filesystem\Filesystem;
+
+readonly class Base64Encoder
+{
+    public function __construct(
+        private Filesystem                                    $filesystem,
+        private \Symfony\Component\Mime\Encoder\Base64Encoder $base64Encoder,
+        private LoggerInterface                               $log
+    )
+    {
+    }
+
+    /**
+     * @throws FileNotFoundException|InvalidArgumentException
+     */
+    public function encodeFile(string $filename): string
+    {
+        $this->log->debug('encodeFile.start', ['filename' => $filename]);
+
+        if (!$this->filesystem->exists($filename)) {
+            throw new FileNotFoundException(sprintf('file %s not found', $filename));
+        }
+
+        $fileBody = file_get_contents($filename);
+        if (false === $fileBody) {
+            throw new InvalidArgumentException(sprintf('cannot read file %s', $filename));
+        }
+
+        $fileBody = $this->base64Encoder->encodeString($fileBody);
+
+        $this->log->debug('encodeFile.finish¨');
+        return $fileBody;
+    }
+}
diff --git a/src/Services/Workflows/Activity/Service/Activity.php b/src/Services/Workflows/Activity/Service/Activity.php
@@ -12,7 +12,7 @@
 use Bitrix24\SDK\Services\Workflows;
 use Bitrix24\SDK\Services\Workflows\Activity\Result\AddedActivityResult;
 use Bitrix24\SDK\Services\Workflows\Activity\Result\UpdateActivityResult;
-use Bitrix24\SDK\Services\Workflows\Common\WorkflowActivityDocumentType;
+use Bitrix24\SDK\Services\Workflows\Common\WorkflowDocumentType;
 use Psr\Log\LoggerInterface;
 
 class Activity extends AbstractService
@@ -70,7 +70,7 @@ public function list(): Workflows\Activity\Result\WorkflowActivitiesResult
      * @param array $properties Array of activity parameters.
      * @param bool $isUsePlacement Enables option to open additional settings for activity in the app slider.
      * @param array $returnProperties Array of returned activity values.
-     * @param WorkflowActivityDocumentType $documentType Tip of document, which will determine type of data for parameters.
+     * @param WorkflowDocumentType $documentType Tip of document, which will determine type of data for parameters.
      * @param array $limitationFilter Activity limitation rules by document type and revision.
      *
      * @return AddedActivityResult
@@ -79,17 +79,17 @@ public function list(): Workflows\Activity\Result\WorkflowActivitiesResult
      * @see https://training.bitrix24.com/rest_help/workflows/app_activities/bizproc_activity_add.php
      */
     public function add(
-        string                                        $code,
-        string                                        $handlerUrl,
-        int                                           $b24AuthUserId,
-        array                                         $localizedName,
-        array                                         $localizedDescription,
-        bool                                          $isUseSubscription,
-        array                                         $properties,
-        bool                                          $isUsePlacement,
-        array                                         $returnProperties,
-        Workflows\Common\WorkflowActivityDocumentType $documentType,
-        array                                         $limitationFilter,
+        string                                $code,
+        string                                $handlerUrl,
+        int                                   $b24AuthUserId,
+        array                                 $localizedName,
+        array                                 $localizedDescription,
+        bool                                  $isUseSubscription,
+        array                                 $properties,
+        bool                                  $isUsePlacement,
+        array                                 $returnProperties,
+        Workflows\Common\WorkflowDocumentType $documentType,
+        array                                 $limitationFilter,
     ): Workflows\Activity\Result\AddedActivityResult
     {
         return new Workflows\Activity\Result\AddedActivityResult($this->core->call('bizproc.activity.add', [
@@ -137,7 +137,7 @@ function delete(string $activityCode): DeletedItemResult
      * @param array|null $properties Array of activity parameters.
      * @param bool|null $isUsePlacement Enables option to open additional settings for activity in the app slider.
      * @param array|null $returnProperties Array of returned activity values.
-     * @param WorkflowActivityDocumentType|null $documentType Tip of document, which will determine type of data for parameters.
+     * @param WorkflowDocumentType|null $documentType Tip of document, which will determine type of data for parameters.
      * @param array|null $limitationFilter Activity limitation rules by document type and revision.
      *
      * @return UpdateActivityResult
@@ -146,17 +146,17 @@ function delete(string $activityCode): DeletedItemResult
      * @see https://training.bitrix24.com/rest_help/workflows/app_activities/bizproc_activity_update.php
      */
     public function update(
-        string                                         $code,
-        ?string                                        $handlerUrl,
-        ?int                                           $b24AuthUserId,
-        ?array                                         $localizedName,
-        ?array                                         $localizedDescription,
-        ?bool                                          $isUseSubscription,
-        ?array                                         $properties,
-        ?bool                                          $isUsePlacement,
-        ?array                                         $returnProperties,
-        ?Workflows\Common\WorkflowActivityDocumentType $documentType,
-        ?array                                         $limitationFilter,
+        string                                 $code,
+        ?string                                $handlerUrl,
+        ?int                                   $b24AuthUserId,
+        ?array                                 $localizedName,
+        ?array                                 $localizedDescription,
+        ?bool                                  $isUseSubscription,
+        ?array                                 $properties,
+        ?bool                                  $isUsePlacement,
+        ?array                                 $returnProperties,
+        ?Workflows\Common\WorkflowDocumentType $documentType,
+        ?array                                 $limitationFilter,
     ): Workflows\Activity\Result\UpdateActivityResult
     {
         $fieldsToUpdate = [];

diff --git a/src/Services/Workflows/Common/DocumentType.php b/src/Services/Workflows/Common/DocumentType.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Workflows\Common;
+
+enum DocumentType: string
+{
+    // lead
+    case crmLead = 'CCrmDocumentLead';
+    // company
+    case crmCompany = 'CCrmDocumentCompany';
+    // contact
+    case crmContact = 'CCrmDocumentContact';
+    // deal
+    case crmDeal = 'CCrmDocumentDeal';
+    // drive file
+    case discBizProcDocument = 'Bitrix\\Disk\\BizProcDocument';
+    //  Drive file
+    case listBizProcDocument = 'BizprocDocument';
+    case listBizProcDocumentLists = 'BizprocDocumentLists';
+    // smart process
+    case smartProcessDynamic = 'Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic';
+    case task = 'Bitrix\\Tasks\\Integration\\Bizproc\\Document\\Task';
+    case invoice = 'Bitrix\\Crm\\Integration\\BizProc\\Document\\SmartInvoice';
+}
diff --git a/src/Services/Workflows/Common/WorkflowActivityDocumentType.php b/src/Services/Workflows/Common/WorkflowActivityDocumentType.php
diff --git a/src/Services/Workflows/Common/WorkflowDocumentType.php b/src/Services/Workflows/Common/WorkflowDocumentType.php
@@ -4,23 +4,38 @@
 
 namespace Bitrix24\SDK\Services\Workflows\Common;
 
-enum WorkflowDocumentType: string
+readonly class WorkflowDocumentType
 {
-    // lead
-    case crmLead = 'CCrmDocumentLead';
-    // company
-    case crmCompany = 'CCrmDocumentCompany';
-    // contact
-    case crmContact = 'CCrmDocumentContact';
-    // deal
-    case crmDeal = 'CCrmDocumentDeal';
-    // drive file
-    case discBizProcDocument = 'Bitrix\\Disk\\BizProcDocument';
-    //  Drive file
-    case listBizProcDocument = 'BizprocDocument';
-    case listBizProcDocumentLists = 'BizprocDocumentLists';
-    // smart process
-    case smartProcessDynamic = 'Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic';
-    case task = 'Bitrix\\Tasks\\Integration\\Bizproc\\Document\\Task';
-    case invoice = 'Bitrix\\Crm\\Integration\\BizProc\\Document\\SmartInvoice';
+    public function __construct(
+        public string $moduleId,
+        public string $entityId,
+        public string $targetDocumentId,
+    )
+    {
+    }
+
+    public function toArray(): array
+    {
+        return [$this->moduleId, $this->entityId, $this->targetDocumentId];
+    }
+
+    public static function buildForLead(): self
+    {
+        return new self('crm', 'CCrmDocumentLead', 'LEAD');
+    }
+
+    public static function buildForContact(): self
+    {
+        return new self('crm', 'CCrmDocumentContact', 'CONTACT');
+    }
+
+    public static function buildForDeal(): self
+    {
+        return new self('crm', 'CCrmDocumentDeal', 'Deal');
+    }
 }
+
+// ['crm', 'CCrmDocumentLead', 'LEAD']
+// ['lists', 'BizprocDocument', 'iblock_22']
+// ['disk', 'Bitrix\Disk\BizProcDocument', 'STORAGE_490']
+// ['tasks', 'Bitrix\Tasks\Integration\Bizproc\Document\Task', 'TASK_PROJECT_13']
diff --git a/src/Services/Workflows/Template/Service/Template.php b/src/Services/Workflows/Template/Service/Template.php
@@ -7,6 +7,9 @@
 use Bitrix24\SDK\Core\Contracts\CoreInterface;
 use Bitrix24\SDK\Core\Exceptions\BaseException;
 use Bitrix24\SDK\Core\Exceptions\TransportException;
+use Bitrix24\SDK\Core\Result\AddedItemResult;
+use Bitrix24\SDK\Core\Result\DeletedItemResult;
+use Bitrix24\SDK\Infrastructure\Filesystem\Base64Encoder;
 use Bitrix24\SDK\Services\AbstractService;
 use Bitrix24\SDK\Services\Workflows;
 use Psr\Log\LoggerInterface;
@@ -15,15 +18,67 @@
 class Template extends AbstractService
 {
     public Batch $batch;
+    private Base64Encoder $base64Encoder;
 
     public function __construct(
         Batch           $batch,
         CoreInterface   $core,
+        Base64Encoder   $base64Encoder,
         LoggerInterface $log
     )
     {
         parent::__construct($core, $log);
         $this->batch = $batch;
+        $this->base64Encoder = $base64Encoder;
+    }
+
+    /**
+     * Add a workflow template, requires administrator access permissions
+     *
+     * @param Workflows\Common\WorkflowDocumentType $workflowDocumentType
+     * @param string $name
+     * @param string $description
+     * @param Workflows\Common\WorkflowAutoExecutionType $workflowAutoExecutionType
+     * @param string $filename
+     * @return AddedItemResult
+     * @throws BaseException
+     * @throws TransportException
+     * @see https://training.bitrix24.com/rest_help/workflows/wirkflow_template/bizproc_workflow_template_add.php
+     */
+    public function add(
+        Workflows\Common\WorkflowDocumentType      $workflowDocumentType,
+        string                                     $name,
+        string                                     $description,
+        Workflows\Common\WorkflowAutoExecutionType $workflowAutoExecutionType,
+        string                                     $filename
+    ): AddedItemResult
+    {
+        return new AddedItemResult($this->core->call('bizproc.workflow.template.add', [
+            'DOCUMENT_TYPE' => $workflowDocumentType->toArray(),
+            'NAME' => $name,
+            'DESCRIPTION' => $description,
+            'AUTO_EXECUTE' => (string)$workflowAutoExecutionType->value,
+            'TEMPLATE_DATA' => $this->base64Encoder->encodeFile($filename)
+        ]));
+    }
+
+    /**
+     * The method deletes workflow template. Requires the administrator access permissions.
+     *
+     * This method deletes only the templates created via the method bizproc.workflow.template.add,
+     * because such templates are bound to an app and only they can be deleted.
+     *
+     * @param int $templateId
+     * @return DeletedItemResult
+     * @throws BaseException
+     * @throws TransportException
+     * @see https://training.bitrix24.com/rest_help/workflows/wirkflow_template/bizproc_workflow_template_delete.php
+     */
+    public function delete(int $templateId): DeletedItemResult
+    {
+        return new DeletedItemResult($this->core->call('bizproc.workflow.template.delete', [
+            'ID' => $templateId
+        ]));
     }
 
     /**