From 59e1dc4a4b64e618e1cb7dc90188662196079356 Mon Sep 17 00:00:00 2001 From: David mattei Date: Fri, 29 Mar 2024 07:32:30 +0100 Subject: [PATCH] feat(core/api): new submission view endpoint (#851) --- dev/common-bundle/core-api.md | 66 +++++++++++++------------ dev/submission-bundle/handlers/email.md | 28 ++++------- dev/submission-bundle/index.md | 14 +++--- 3 files changed, 52 insertions(+), 56 deletions(-) diff --git a/dev/common-bundle/core-api.md b/dev/common-bundle/core-api.md index d06c766..8c93362 100644 --- a/dev/common-bundle/core-api.md +++ b/dev/common-bundle/core-api.md @@ -10,8 +10,8 @@ If **EMS_BACKEND_API_KEY** is defined, the coreApi will be authenticated. ## Creating a Core API instance -Create a new service using the [CoreApiFactoryInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/CoreApiFactoryInterface.php) contract. -Your service will be an instance of: [CoreApiInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/CoreApiInterface.php) +Create a new service using the [CoreApiFactoryInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/CoreApiFactoryInterface.php) contract. +Your service will be an instance of: [CoreApiInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/CoreApiInterface.php) ```xml @@ -67,22 +67,22 @@ final class Example ## CoreApi ### Exceptions -> Each API interaction can throw the following **[CoreApiExceptionInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/CoreApiExceptionInterface.php)**: -* **[BaseUrlNotDefinedExceptionInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Exception/BaseUrlNotDefinedExceptionInterface.php)** -* **[NotAuthenticatedExceptionInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Exception/NotAuthenticatedExceptionInterface.php)** -* **[NotSuccessfulExceptionInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Exception/NotSuccessfulExceptionInterface.php)** +> Each API interaction can throw the following **[CoreApiExceptionInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/CoreApiExceptionInterface.php)**: +* **[BaseUrlNotDefinedExceptionInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Exception/BaseUrlNotDefinedExceptionInterface.php)** +* **[NotAuthenticatedExceptionInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Exception/NotAuthenticatedExceptionInterface.php)** +* **[NotSuccessfulExceptionInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Exception/NotSuccessfulExceptionInterface.php)** ### Authentication -* **authenticate**(string $username, string $password): [CoreApiInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/CoreApiInterface.php) - > Provide EMS login credentials, and it will return an authenticated Core API instance. Throws [NotAuthenticatedExceptionInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Exception/NotAuthenticatedExceptionInterface.php) +* **authenticate**(string $username, string $password): [CoreApiInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/CoreApiInterface.php) + > Provide EMS login credentials, and it will return an authenticated Core API instance. Throws [NotAuthenticatedExceptionInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Exception/NotAuthenticatedExceptionInterface.php) * **isAuthenticated**(): bool ### Endpoints -* **data**(string $contentType): [DataInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DataInterface.php) -* **user**(): [UserInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/User/UserInterface.php) -* **file**(): [FileInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/File/FileInterface.php) +* **data**(string $contentType): [DataInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DataInterface.php) +* **user**(): [UserInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/User/UserInterface.php) +* **file**(): [FileInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/File/FileInterface.php) ### Extra * **getBaseUrl**(): string - > Throws [BaseUrlNotDefinedExceptionInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Exception/BaseUrlNotDefinedExceptionInterface.php) + > Throws [BaseUrlNotDefinedExceptionInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Exception/BaseUrlNotDefinedExceptionInterface.php) * **getToken**(): string > Before call isAuthenticated, otherwise you will receive an error. * **setLogger**(LoggerInterface $logger): void @@ -91,24 +91,24 @@ final class Example > Test if the api available ## Endpoints -### Data ([DataInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DataInterface.php)) -* **create**(array $rawData, ?string $ouuid = null): [DraftInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DraftInterface.php) +### Data ([DataInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DataInterface.php)) +* **create**(array $rawData, ?string $ouuid = null): [DraftInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DraftInterface.php) > When no ouuid is provided elasticms will generate the ouuid. You can receive the generated ouuid by calling finalize. * **delete**(string $ouuid): bool * **discard**(int $revisionId): bool * **finalize**(int $revisionId): string > Return the ouuid if successfully finalized. -* **get**(string $ouuid): [RevisionInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/RevisionInterface.php) -* **replace**(string $ouuid, array $rawData): [DraftInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DraftInterface.php) -* **update**(string $ouuid, array $rawData): [DraftInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DraftInterface.php) +* **get**(string $ouuid): [RevisionInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/RevisionInterface.php) +* **replace**(string $ouuid, array $rawData): [DraftInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DraftInterface.php) +* **update**(string $ouuid, array $rawData): [DraftInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Data/DraftInterface.php) > Will merge the passed rawData with the current rawData. * **save**(string $ouuid, array $rawData, int $mode = DataInterface::MODE_UPDATE): int > Save (create, update or replace) the raw for the given ouuid. -### User ([UserInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/User/UserInterface.php)) +### User ([UserInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/User/UserInterface.php)) * **getProfiles**(): array - > Return an array of [ProfileInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/User/ProfileInterface.php) instances -* **getProfileAuthenticated**(): [ProfileInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/User/ProfileInterface.php) -### File ([FileInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/File/FileInterface.php)) + > Return an array of [ProfileInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/User/ProfileInterface.php) instances +* **getProfileAuthenticated**(): [ProfileInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/User/ProfileInterface.php) +### File ([FileInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/File/FileInterface.php)) * **hashFile**(string $filename): string > Return a hash for a given filename * **initUpload**(string $hash, int $size, string $filename, string $mimetype): int @@ -119,19 +119,23 @@ final class Example > Upload a file. If the mimetype is not provided a mimetype will be guessed. It returns the file's hash * **headFile**(string $realPath): ?string > Tests if a given file has been already uploaded -## From ([FormInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Form/FormInterface.php)) +## From ([FormInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Form/FormInterface.php)) * **createVerification**(string $value): string > Create a new form verification value * **getVerification**(string $value): string > Get a created form verification value - -### Search ([SearchInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Search/SearchInterface.php)) -* **search**([Search](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Search/Search.php) $search): ResponseInterface - > Perform a remote search based on the [Search](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Search/Search.php) object -* **count**([Search](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Search/Search.php) $search): int - > Count the document matching the [Search](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Search/Search.php) object -* **scroll**([Search](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Search/Search.php) $search, int $scrollSize = 10, string $expireTime = '3m'): [Scroll](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Common/CoreApi/Search/Scroll.php) - > Return a scroller looping on all documents match the [Search](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Search/Search.php) object +* **submit**(array $data): string + > Submit a form data return submission id +* **getSubmission**(string $submissionId, ?string $property = null): array + > Pass a property for filtering the response, for example '[expireData]', '[data][firstName]' or '[files][0][filename]' + +### Search ([SearchInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/Search/SearchInterface.php)) +* **search**([Search](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Search/Search.php) $search): ResponseInterface + > Perform a remote search based on the [Search](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Search/Search.php) object +* **count**([Search](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Search/Search.php) $search): int + > Count the document matching the [Search](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Search/Search.php) object +* **scroll**([Search](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Search/Search.php) $search, int $scrollSize = 10, string $expireTime = '3m'): [Scroll](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Common/CoreApi/Search/Scroll.php) + > Return a scroller looping on all documents match the [Search](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Search/Search.php) object * **version**(): string > Return the cluster version * **healthStatus**(): string @@ -145,6 +149,6 @@ final class Example * **getDocument**(string $index, ?string $contentType, string $id, string[] $sourceIncludes = [], string[] $sourcesExcludes = []): DocumentInterface > Return the aliases containing the index -### DataExtract ([DataExtractInterface](https://github.com/ems-project/elasticms/tree/4.x/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/File/DataExtractInterface.php)) +### DataExtract ([DataExtractInterface](https://github.com/ems-project/elasticms/blob/HEAD/EMS/common-bundle/src/Contracts/CoreApi/Endpoint/File/DataExtractInterface.php)) * **get**(string $hash): string > Return an associative array with all data extracted from an asset/file identified by the hash parameter diff --git a/dev/submission-bundle/handlers/email.md b/dev/submission-bundle/handlers/email.md index 5386711..df32273 100644 --- a/dev/submission-bundle/handlers/email.md +++ b/dev/submission-bundle/handlers/email.md @@ -10,14 +10,14 @@ incoming-email@example.com Or dynamically: ```twig -{%- spaceless -%} +{%- apply spaceless -%} {%- set destination = "incoming-email@example1.com" -%} {%- if data.my_destination_field is same as("my_destination_value") -%} {%- set destination = "incoming-email@example2.com" -%} {%- endif -%} -{%- endspaceless -%} +{%- endapply -%} {{- destination -}} ``` @@ -89,10 +89,11 @@ You can also define a `reply-to` option: } %} {% endautoescape %} {{ email|js +``` ### Attachments -Use the **formData** helper object to retreive all files that are attached to the form submission. +Use the **formData** helper object to retrieve all files that are attached to the form submission. You can override the default values for each file using the `map` filter as shown below. ```twig @@ -106,23 +107,14 @@ You can override the default values for each file using the `map` filter as show {% set email = { "from": data.email, "subject": "Email Form subject", - "body": body + "body": body, + "attachments": formData.allFiles|map(v => v.toArray)|map(f => { + filename: f.originalName|ems_webalize, + mimeType: f.mimeType, + pathname: f.pathname, + }) } %} -{%- set files = {} -%} -{% for file in formData.allFiles|map(v => v.toArray) %} - {%- set files = files|merge({(file.form_field):{ - filename: file.filename|ems_slug, - originalName: file.filename|ems_slug, - mimeType: file.mimeType, - pathname: file.pathname, - } }) -%} -{% endfor %} - -{% if files|length > 0 %} - {% set email = email|merge({"attachments": files}) %} -{% endif %} - {% endautoescape %} {{ email|json_encode|raw }} ``` diff --git a/dev/submission-bundle/index.md b/dev/submission-bundle/index.md index e1fc080..2a18edd 100644 --- a/dev/submission-bundle/index.md +++ b/dev/submission-bundle/index.md @@ -36,13 +36,13 @@ Both fields are rendered by twig and the following information is available in t ### Supported handlers -* [Email](handlers/email.md) -* [Http](handlers/http.md) -* [Pdf](handlers/pdf.md) -* [ServiceNow](handlers/service-now.md) -* [Sftp](handlers/sftp.md) -* [Soap](handlers/soap.md) -* [Zip](handlers/zip.md) +* [Email](/dev/submission-bundle/handlers/email.md) +* [Http](/dev/submission-bundle/handlers/http.md) +* [Pdf](/dev/submission-bundle/handlers/pdf.md) +* [ServiceNow](/dev/submission-bundle/handlers/service-now.md) +* [Sftp](/dev/submission-bundle/handlers/sftp.md) +* [Soap](/dev/submission-bundle/handlers/soap.md) +* [Zip](/dev/submission-bundle/handlers/zip.md) ## Configuration ```yaml