Added new workflows and activities service functionalities

This commit introduces new functionalities for workflows and activities services. It includes adding methods to enable recording data in the workflow log, retrieval of installed activities, option to update activity fields, add and delete activities. Also, added necessary result classes and updated the access token method name.

Signed-off-by: mesilov <mesilov.maxim@gmail.com>

CHANGELOG.md

@@ -8,7 +8,8 @@
     * `Template`
     * `Robot`
     * `Event`
-* add method `Bitrix24\SDK\Core\Credentials\AccessToken::initFromRobotRequest`
+* add `WorkflowActivityDocumentType`
+* add method `Bitrix24\SDK\Core\Credentials\AccessToken::initFromWorkflowRequest`
 * 
 
 ## 2.0-beta.2 — 1.04.2024

src/Core/Credentials/AccessToken.php

@@ -79,7 +79,7 @@ public static function initFromArray(array $request): self
         );
     }
 
-    public static function initFromRobotRequest(Request $request): self
+    public static function initFromWorkflowRequest(Request $request): self
     {
         $requestFields = $request->request->all();
         return self::initFromArray($requestFields['auth']);

src/Services/Workflows/Activity/Result/AddedActivityResult.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Workflows\Activity\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class AddedActivityResult extends AbstractResult
+{
+    public function isSuccess(): bool
+    {
+        return $this->getCoreResponse()->getResponseData()->getResult()[0];
+    }
+}

src/Services/Workflows/Activity/Result/AddedMessageToLogResult.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Workflows\Activity\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class AddedMessageToLogResult extends AbstractResult
+{
+    public function isSuccess(): bool
+    {
+        return $this->getCoreResponse()->getResponseData()->getResult()[0];
+    }
+}

src/Services/Workflows/Activity/Result/UpdateActivityResult.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Workflows\Activity\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class UpdateActivityResult extends AbstractResult
+{
+    public function isSuccess(): bool
+    {
+        return $this->getCoreResponse()->getResponseData()->getResult()[0];
+    }
+}

src/Services/Workflows/Activity/Result/WorkflowActivitiesResult.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Workflows\Activity\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class WorkflowActivitiesResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function getActivities(): array
+    {
+        return $this->getCoreResponse()->getResponseData()->getResult();
+    }
+}

src/Services/Workflows/Activity/Service/Activity.php

@@ -0,0 +1,200 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Workflows\Activity\Service;
+
+use Bitrix24\SDK\Core\Contracts\CoreInterface;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\TransportException;
+use Bitrix24\SDK\Core\Result\DeletedItemResult;
+use Bitrix24\SDK\Services\AbstractService;
+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 Psr\Log\LoggerInterface;
+
+class Activity extends AbstractService
+{
+    public Batch $batch;
+
+    public function __construct(
+        Batch           $batch,
+        CoreInterface   $core,
+        LoggerInterface $log
+    )
+    {
+        parent::__construct($core, $log);
+        $this->batch = $batch;
+    }
+
+    /**
+     * This method records data in the workflow log.
+     * @param string $eventToken
+     * @param string $message
+     * @return Workflows\Activity\Result\AddedMessageToLogResult
+     * @throws BaseException
+     * @throws TransportException
+     * @see https://training.bitrix24.com/rest_help/workflows/app_activities/bizproc_activity_list.php
+     */
+    public function log(string $eventToken, string $message): Workflows\Activity\Result\AddedMessageToLogResult
+    {
+        return new Workflows\Activity\Result\AddedMessageToLogResult($this->core->call('bizproc.activity.log', [
+            'EVENT_TOKEN' => $eventToken,
+            'LOG_MESSAGE' => $message
+        ]));
+    }
+
+    /**
+     * This method returns list of activities, installed by the application.
+     *
+     * @throws BaseException
+     * @throws TransportException
+     * @see https://training.bitrix24.com/rest_help/workflows/app_activities/bizproc_activity_list.php
+     */
+    public function list(): Workflows\Activity\Result\WorkflowActivitiesResult
+    {
+        return new Workflows\Activity\Result\WorkflowActivitiesResult($this->core->call('bizproc.activity.list'));
+    }
+
+    /**
+     * Adds new activity to a workflow.
+     *
+     * @param string $code Internal activity ID, unique within the application framework. Permissible symbols are a-z, A-Z, 0-9, period, hyphen and underscore.
+     * @param string $handlerUrl URL, to which the activity will send data (via bitrix24 queue server), when workflow has reached its completion. Shall reference to the same domain, where the app is installed.
+     * @param int $b24AuthUserId ID of the user, whose token will be passed to the application.
+     * @param array $localizedName Name of activity, associative array of localized strings.
+     * @param array $localizedDescription Description of activity, associative array of localized strings.
+     * @param bool $isUseSubscription Use of subscription. It is possible to specify, whether the activity should or should not await for a response from the application. If the parameter is empty or not specified - user himself/herself can configure this parameter in settings of the activity in the workflows designer.
+     * @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 array $limitationFilter Activity limitation rules by document type and revision.
+     *
+     * @return AddedActivityResult
+     * @throws BaseException
+     * @throws TransportException
+     * @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,
+    ): Workflows\Activity\Result\AddedActivityResult
+    {
+        return new Workflows\Activity\Result\AddedActivityResult($this->core->call('bizproc.activity.add', [
+            'CODE' => $code,
+            'HANDLER' => $handlerUrl,
+            'AUTH_USER_ID' => $b24AuthUserId,
+            'NAME' => $localizedName,
+            'DESCRIPTION' => $localizedDescription,
+            'USE_SUBSCRIPTION' => $isUseSubscription ? 'Y' : 'N',
+            'PROPERTIES' => $properties,
+            'USE_PLACEMENT' => $isUsePlacement ? 'Y' : 'N',
+            'RETURN_PROPERTIES' => $returnProperties,
+            'DOCUMENT_TYPE' => $documentType->toArray(),
+            'FILTER' => $limitationFilter
+        ]));
+    }
+
+    /**
+     * This method deletes an activity.
+     *
+     * @param string $activityCode
+     * @return DeletedItemResult
+     * @throws BaseException
+     * @throws TransportException
+     * @see https://training.bitrix24.com/rest_help/workflows/app_activities/bizproc_activity_delete.php
+     */
+    public
+    function delete(string $activityCode): DeletedItemResult
+    {
+        return new DeletedItemResult(
+            $this->core->call('bizproc.activity.delete', [
+                'CODE' => $activityCode
+            ]));
+    }
+
+    /**
+     * This method allows to update activity fields. Method parameters are similar to bizproc.activity.add.
+     *
+     * @param string $code Internal activity ID, unique within the application framework. Permissible symbols are a-z, A-Z, 0-9, period, hyphen and underscore.
+     * @param string|null $handlerUrl URL, to which the activity will send data (via bitrix24 queue server), when workflow has reached its completion. Shall reference to the same domain, where the app is installed.
+     * @param int|null $b24AuthUserId ID of the user, whose token will be passed to the application.
+     * @param array|null $localizedName Name of activity, associative array of localized strings.
+     * @param array|null $localizedDescription Description of activity, associative array of localized strings.
+     * @param bool|null $isUseSubscription Use of subscription. It is possible to specify, whether the activity should or should not await for a response from the application. If the parameter is empty or not specified - user himself/herself can configure this parameter in settings of the activity in the workflows designer.
+     * @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 array|null $limitationFilter Activity limitation rules by document type and revision.
+     *
+     * @return UpdateActivityResult
+     * @throws BaseException
+     * @throws TransportException
+     * @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,
+    ): Workflows\Activity\Result\UpdateActivityResult
+    {
+        $fieldsToUpdate = [];
+        if ($handlerUrl !== null) {
+            $fieldsToUpdate['HANDLER'] = $handlerUrl;
+        }
+        if ($b24AuthUserId !== null) {
+            $fieldsToUpdate['AUTH_USER_ID'] = $b24AuthUserId;
+        }
+        if ($localizedName !== null) {
+            $fieldsToUpdate['NAME'] = $localizedName;
+        }
+        if ($localizedDescription !== null) {
+            $fieldsToUpdate['DESCRIPTION'] = $localizedDescription;
+        }
+        if ($isUseSubscription !== null) {
+            $fieldsToUpdate['USE_SUBSCRIPTION'] = $isUseSubscription ? 'Y' : 'N';
+        }
+        if ($properties !== null) {
+            $fieldsToUpdate['PROPERTIES'] = $properties;
+        }
+        if ($isUsePlacement !== null) {
+            $fieldsToUpdate['USE_PLACEMENT'] = $isUsePlacement ? 'Y' : 'N';
+        }
+        if ($returnProperties !== null) {
+            $fieldsToUpdate['RETURN_PROPERTIES'] = $returnProperties;
+        }
+        if ($documentType !== null) {
+            $fieldsToUpdate['DOCUMENT_TYPE'] = $documentType->toArray();
+        }
+        if ($limitationFilter !== null) {
+            $fieldsToUpdate['FILTER'] = $limitationFilter;
+        }
+        return new Workflows\Activity\Result\UpdateActivityResult($this->core->call(
+            'bizproc.activity.update',
+            [
+                'CODE' => $code,
+                'FIELDS' => $fieldsToUpdate
+            ]));
+    }
+}

src/Services/Workflows/Activity/Service/Batch.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Workflows\Activity\Service;
+
+use Bitrix24\SDK\Core\Contracts\BatchOperationsInterface;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AddedItemBatchResult;
+use Bitrix24\SDK\Core\Result\DeletedItemBatchResult;
+use Bitrix24\SDK\Core\Result\UpdatedItemBatchResult;
+use Generator;
+use Psr\Log\LoggerInterface;
+
+readonly class Batch
+{
+    public function __construct(
+        protected BatchOperationsInterface $batch,
+        protected LoggerInterface          $log)
+    {
+    }
+}

src/Services/Workflows/Common/WorkflowActivityDocumentType.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Workflows\Common;
+
+readonly class WorkflowActivityDocumentType
+{
+    public function __construct(
+        public string $moduleId,
+        public string $entityId,
+        public string $targetDocumentType,
+    )
+    {
+    }
+
+    public function toArray(): array
+    {
+        return [$this->moduleId, $this->entityId, $this->targetDocumentType];
+    }
+
+    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']

src/Services/Workflows/Workflow/Service/Workflow.php

@@ -44,6 +44,7 @@ public function start(
         int                                   $smartProcessId = null
     ): Workflows\Workflow\Result\WorkflowInstanceStartResult
     {
+        $documentId = null;
         switch ($workflowDocumentType) {
             case Workflows\Common\WorkflowDocumentType::crmLead:
                 $documentId = ['crm', $workflowDocumentType->value, sprintf('LEAD_%s', $entityId)];

src/Services/Workflows/WorkflowsServiceBuilder.php

@@ -35,6 +35,19 @@ public function robot(): Workflows\Robot\Service\Robot
         return $this->serviceCache[__METHOD__];
     }
 
+    public function activity(): Workflows\Activity\Service\Activity
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Workflows\Activity\Service\Activity(
+                new Workflows\Activity\Service\Batch($this->batch, $this->log),
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
+
     public function template(): Workflows\Template\Service\Template
     {
         if (!isset($this->serviceCache[__METHOD__])) {