API für Aktionen in edoc automate

Alle Aktionen in edoc automate sind eigenständige Plug-Ins. Sie können jederzeit eigene neue Aktionen hinzufügen.

In edoc automate sind zwei Arten von Aktionen definiert:

Aktionen, die standardmäßig in edoc automate app mitgeliefert werden.
Aktionen, die Sie als App-Entwickler:in selbst in edoc automate app einfügen. Sie können eigene Aktionen nur in edoc automate App verwenden.

Beide Aktionsarten sind gleichwertig, sie unterscheiden sich nur im verwendeten Namespace und dem Speicherort in der App.

Klassendiagramm für Aktionen

Schematische Darstellung des Klassendiagramms für Aktionen in edoc automate — UML-Klassendiagramm für Aktionen

“ActionHelper”-Hilfsfunktionen

In der Aktionsklasse stehen Ihnen mit der Eigenschaft $helper zusätzliche hilfreiche Methoden zur Verfügung.

PHP

class ActionHelper
{
    const ACTION_RETURN_TYPE_EMPTY = 'empty';
    const ACTION_RETURN_TYPE_VALUE = 'value';
    const ACTION_RETURN_TYPE_DATASET = 'dataset';
    
    /**
     * @param string $actionName The name of action including the group, "group\action".
     * @param array $params An array with the parameters of the action.
     * @param $returnFields An array with IDs for components, e.g. for the actions "default\SetValue" or "default\SetDataset".
     * @param $returnType The return type of called action (see constants ACTION_RETURN_TYPE_...).
     * @return The return of action. Can be a simple value or a dataset.
     */
    public function exec(string $actionName, array $params, ?array $returnFields = null, &$returnType = null);

    /**
     * @param $value The value to validate.
     * @return true, if the value is "SingleValue", otherwise "false".
     */
    public function isSingleValue($value): bool

    /**
     * @param $value The value to validate.
     * @return true, if the value is a dataset, otherwise "false".
     */
    public function isDataset($value): bool
}

Standard für Namespaces

Standardaktionen finden Sie unter: namespace edoc\appserver\app\actions\lib\app;
Ihre eigenen Plug-Ins speichern Sie unter: namespace edoc\appserver\app\actions\plugins;

Hinzufügen von eigenen App-Aktionen

Wenn Sie bestimmte Funktionen in eigenen Aktionen auslagern möchten, müssen Sie ein neues Plug-In im App-Ordner ../<app>/plugins/actions/ z.B. per WebDAV erstellen.

So geht’s

Erstellen Sie im Ordner ../<app>/plugins/actions/ einen neuen Ordner (z.B.: Replace). Der Name des Ordners muss den Namen der Aktion widerspiegeln.
Erstellen Sie in dem Ordner eine Datei mit demselben Namen mit der Endung .php (z.B.: Replace.php).
Öffnen Sie die Datei mit einem beliebigen Texteditor.

Fügen Sie folgenden Inhalt in die Datei ein:

PHP

<?php

namespace edoc\appserver\app\actions\plugins;

use edoc\appserver\app\AbstractAction;
use edoc\appserver\app\actions\SingleValueAction;

class Replace extends AbstractAction
{
    use SingleValueAction;

    protected function init()
    {
        $this->addParameter('String', self::ACTION_TYPE_TEXT);
        $this->addParameter('Search', self::ACTION_TYPE_TEXT);
        $this->addParameter('Replace', self::ACTION_TYPE_TEXT);
    }

    public function exec(): AbstractAction
    {
        $string = $this->param('String');
        $search = $this->param('Search');
        $replace = $this->param('Replace');
				
        $value = str_replace($search, $replace, $string);
				
        return $this->returnSingleValue($value);
    }
}

Speichern Sie die Datei mit dem korrekten Encoding: UTF-8 ohne BOM.

Sie können die neu erstellte Aktion jetzt im edoc automate-Editor verwenden.

Möglicherweise müssen Sie edoc automate erneut laden, damit Sie die Aktion verwenden können.

Traits: Die PHP-Methode zum Wiederverwenden von Code

edoc automate verwendet Traits, um zu steuern, ob eine Aktion Daten zurückgibt und welches Datenformat zurückgegeben wird.

Folgende Traits können Sie verwenden:

DatasetAction-Trait

Stellt den PHP-Trait für DatasetAction schematisch dar. — Trait “DatasetAction”

SingleValueAction-Trait

Beispiel: Verwenden einer Datenquelle

PHP

	<?php
	
	use edoc\appserver\app\AbstractAction;
	use edoc\appserver\app\actions\SingleValueAction;
	use edoc\appserver\datasources\Database;
	use edoc\appserver\datasources\DataSource;

	class DatasourceAction extends AbstractAction
	{
		use SingleValueAction;
		
		protected function init()
		{
			// define datasource parameter
			$this->addParameter("DS", self::ACTION_TYPE_DATASOURCE);
			
			$this->addParemeter("Search", self::ACTION_TYPE_TEXT);
			
		}
		
		public function exec(): AbstractAction
		{
			$selectedDatasource = $this->param("DS");
			
			try {
				// get datasource instance
				$ds = DataSource::getInstance($selectedDatasource);

				// validate datasource instance
				if ($ds instanceof Database) {
					// set query parameter
					$ds->setParams([
						"search" => $this->param('Search')
					]);
					$query = "SELECT `title` FROM `data` WHERE `value` = :search";
					// execute query
					$result = $ds->query($query);

					if (is_array($result) && count($result) !== 0) {
						$this->returnSingleValue($result[0]['title']);
					}
				} else {
					$this->returnError('cannot create instance of datasource "' . $selectedDatasource . '"');
				}
			} catch (\Exception $e) {
				$this->returnError($e->getMessage(), $e->getCode());
			}
		}
	}

Beispiel: Ausführen von Aktionen

PHP

<?php
	
	use edoc\appserver\app\AbstractAction;
	use edoc\appserver\app\actions\SingleValueAction;
	
	class ExecAction extends AbstractAction
	{
		use SingleValueAction;
		
		protected function init()
		{
			$this->addParameter('action', self::ACTION_TYPE_ACTION);
		}

		protected function exec(): AbstractAction
		{
			$actionConfig = $this->param('action');
			if (is_array($actions)) {
				// create action instance
				$action = AbstractAction::create($actionConfig, $this->parent(), $this->logger);
				if ($action instanceof AbstractAction) {
						try {
							// set options
							$action->setRenderResponse($this->renderResponse());
							
							// exec action
							$action->run();
							
							// validate result
              $uses = class_uses($action);
							if (isset($uses[SingleValueAction::class]) && $action->isSingleValueSet()) {
								return $this->returnSingleValueAction($action->singleValue());
							} else {
								// trigger warning/error, invalue action result!
							}
						} catch (\Exception $e) {
								// trigger warning/error, while exec action!
						}
				} else {
								// trigger warning/error, invalid action definition!
				}
					
			}

			return $this->returnEnd();
		}
	}

Sie können unabhängig von Parametern auch andere Aktionen aufrufen, indem Sie ActionHelper verwenden. Beispiel: $response = $this->helper->exec("app\\GetConstant", ["Name" => "APP_NAME"]);