Feat/zapier project description

.editorconfig

@@ -14,7 +14,7 @@ insert_final_newline                                                      = true
 dotnet_diagnostic.IDE0055.severity                                        = error
 
 dotnet_sort_system_directives_first                                       = true
-dotnet_separate_import_directive_groups                                   = false
+dotnet_separate_import_directive_groups                                   = true
 
 ## C# Formatting Rules https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/formatting-rules
 

.gitignore

@@ -141,3 +141,4 @@ segments_2i
 # Files Generated by this integration
 **/App_Data/Zapier/*
 /examples/DancingGoat/appsettings.Development.json
+/examples/DancingGoat/Properties/PublishProfiles/IISProfile.pubxml.user

README.md

@@ -1,26 +1,23 @@
 # Xperience by Kentico Zapier
 
 [![Kentico Labs](https://img.shields.io/badge/Kentico_Labs-grey?labelColor=orange&logo=data:image/svg+xml;base64,PHN2ZyBjbGFzcz0ic3ZnLWljb24iIHN0eWxlPSJ3aWR0aDogMWVtOyBoZWlnaHQ6IDFlbTt2ZXJ0aWNhbC1hbGlnbjogbWlkZGxlO2ZpbGw6IGN1cnJlbnRDb2xvcjtvdmVyZmxvdzogaGlkZGVuOyIgdmlld0JveD0iMCAwIDEwMjQgMTAyNCIgdmVyc2lvbj0iMS4xIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik05NTYuMjg4IDgwNC40OEw2NDAgMjc3LjQ0VjY0aDMyYzE3LjYgMCAzMi0xNC40IDMyLTMycy0xNC40LTMyLTMyLTMyaC0zMjBjLTE3LjYgMC0zMiAxNC40LTMyIDMyczE0LjQgMzIgMzIgMzJIMzg0djIxMy40NEw2Ny43MTIgODA0LjQ4Qy00LjczNiA5MjUuMTg0IDUxLjIgMTAyNCAxOTIgMTAyNGg2NDBjMTQwLjggMCAxOTYuNzM2LTk4Ljc1MiAxMjQuMjg4LTIxOS41MnpNMjQxLjAyNCA2NDBMNDQ4IDI5NS4wNFY2NGgxMjh2MjMxLjA0TDc4Mi45NzYgNjQwSDI0MS4wMjR6IiAgLz48L3N2Zz4=)](https://github.com/Kentico/.github/blob/main/SUPPORT.md#labs-limited-support)
-[![CI: Build and Test](https://github.com/Kentico/xperience-by-kentico-zapier/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Kentico/xperience-by-kentico-zapier/actions/workflows/ci.yml)
-[![NuGet Package](https://img.shields.io/nuget/vpre/Kentico.Xperience.Zapier.svg)](https://www.nuget.org/packages/Kentico.Xperience.Zapier)
 
 > [!WARNING]  
 > This integration is currently preview only with limited Kentico Labs support. The Zapier application is in public beta here: https://zapier.com/apps/xperience-by-kentico/integrations
 >
 > Updated and fully supported Zapier integration is coming in Xperience by Kentico April Refresh
 
-
 ## Description
 
 Zapier integration enables seamless connectivity between a wide range of web applications, allowing users to create automated workflows, or "Zaps," that trigger actions across different platforms based on specified conditions and triggers. This integration empowers users to streamline repetitive tasks, synchronize data, and improve productivity without requiring any coding knowledge, making it an invaluable tool for individuals and businesses alike.
 
 ## Screenshots
 
 ![List of zapier triggers](/images/screenshots/listofzapiertriggers.png "List of zapier triggers")
-![Trigger in zapier UI](/images/screenshots/zapieruitrigger.png "Zap creation in zapier UI: Triggers")
-![Actions in zapier UI](/images/screenshots/zapieruiactions.png "Zap creation in zapier UI: Actions")
-
-
+![Trigger events](/images/screenshots/zapieruitriggerevents.png "Available trigger events")
+![Action events](/images/screenshots/zapieruiactionevents.png "Available action events")
+![API Key page](/images/screenshots/zapierapikey.png "API Key page")
+![API Key generate page](/images/screenshots/zapierapikeygenerate.png "API Key generate page")
 
 ## Library Version Matrix
 
@@ -65,42 +62,42 @@ dotnet add package Kentico.Xperience.Zapier --prerelease
    ```
 
 2. Configure Zapier using ZapierConfiguration in appsettings.json of your application.
-    * Specify the domain of your application and the allowed objects that can interact with your Zapier triggers and handlers.
+
+   - Specify allowed objects that can interact with your Zapier triggers and handlers.
 
    ```csharp
        // appsettings.json
       "ZapierConfiguration": {
-        "WebAdminDomain": "myzapierapp.com",
         "AllowedObjects": [
           "cms.user",
           "CMS.EventLog",
            // ...
           "DancingGoat.Banner",
-          "DancingGoat.ConfirmationPage",      
+          "DancingGoat.ConfirmationPage",
            // ...
           "BizForm.DancingGoatContactUs",
         ]
       }
    ```
 
-3. In the administration go to UI application 'Zapier'.
+3. In the administration go to UI application 'Zapier' located at 'Configuration' section.
 4. On the API Key menu generate new API key for your Zapier application.
-    * Save the API key as it will appear only once.
+   - Save the API key as it will appear only once.
 5. Open your Zapier UI and create new Zap.
-    * Select Xperience by Kentico as your trigger or an action.
-    * Then you have to connect an Account using URL of your website (without trailing slash) and your generated API Key from previous step.
-    * After your connection, you can set configuration for your trigger or action. 
-    * Follow the Zapier UI. If you need more information, visit the [Usage Guide](./docs/Usage-Guide.md)
-    * Test your Zap.
-6. After you finish your Zap... Publication of your Zap will create an object in your Xperience by Kentico application.
-    * You can find it in administration -> Zapier UI application -> List of Zapier triggers
-
+   - As a trigger pick _Xperience by Kentico_ application
+   - In the first step select event of your choice
+   - Then you have to connect an Account using URL of your website (without trailing slash) and your generated API Key from previous step
+   - In the third step you need to set configuration for your trigger
+   - Test your trigger
+6. Now you can create your own workflow eg. connect with Gmail, Microsoft Teams, ...
+   - You can find more information on https://zapier.com/workflows
+7. Publication of your Zap will create an object in your Xperience by Kentico application.
+   - You can find the list of created triggers at Zapier application at page _List of Zapier triggers_
 
 ## Full Instructions
 
 View the [Usage Guide](./docs/Usage-Guide.md) for more detailed instructions.
 
-
 ## Contributing
 
 To see the guidelines for Contributing to Kentico open source software, please see [Kentico's `CONTRIBUTING.md`](https://github.com/Kentico/.github/blob/main/CONTRIBUTING.md) for more information and follow the [Kentico's `CODE_OF_CONDUCT`](https://github.com/Kentico/.github/blob/main/CODE_OF_CONDUCT.md).
@@ -120,4 +117,3 @@ This project has **Kentico Labs limited support** while in PREVIEW version. You
 See [`SUPPORT.md`](https://github.com/Kentico/.github/blob/main/SUPPORT.md#full-support) for more information.
 
 For any security issues see [`SECURITY.md`](https://github.com/Kentico/.github/blob/main/SECURITY.md).
-

docs/Configuration-example.md

@@ -6,7 +6,6 @@ The appropriate name of the allowed object corresponds to the ClassName in the C
 ```json
 {
   "ZapierConfiguration": {
-    "WebAdminDomain": "dancinggoatzapier.com",
     "AllowedObjects": [
       "cms.Role",
       "cms.user",

docs/Usage-Guide.md

@@ -1,75 +1,95 @@
-# Usage Guide
+### Configure your application
 
-## Configure your application
-Prerequisites for using this integration are a public application running on Xperience by Kentico and a Zapier account.
+Prerequisites for using this integration are a public Xperience by Kentico application and a Zapier account.
 
 In the beginning, it is necessary to **register services into the DI container** in your application and to **configure Zapier in the appropriate appsettings** file in your application.
-These steps are displayed in the first two points of our Quick Start section.
- * In the appsettings configuration, you need to specify the domain of your application in the correct format, e.g., 'myzapierapp.com', and list the allowed objects.
- * Setting the allowed objects list in appsettings.json affects the object selection in the Zapier UI. Make sure you set up the appropriate objects for your application.
 
-You can view [sample of such configuration](Configuration-example.md).
+```csharp
+// Program.cs
+var builder = WebApplication.CreateBuilder(args);
 
-## Zapier admin application
-After configuring your application, a new application named 'Zapier' should appear in your application's administration.
-This application provides a list of created Zapier triggers from the Zapier UI and a submodule for the API Key.
- * On the 'List Zapier Triggers' tab, you can view the list of active zapier triggers. Items cannot be manually changed in the Admin application. Therefore, you must (and should) manage your triggers directly from the Zapier UI.
- * On the 'API Key' tab, you can generate API Key for communication between your application and Zapier itself.
-    * **Note that there is only one API Key per application**. It is crucial to securely store it and share it only with your zapier editors. Once the API key is generated, you can only view it once.
+// ...
 
+builder.Services.AddKenticoZapier();
 
-## Authentication in Zapier
-To connect zapier with your application, you must authenticate your app first. 
- * In the Zapier UI, you will be asked for the **domain of your application**.
- * Also, you must provide the **API Key** for your application. 
+// ...
 
-The API Key is used consistently throughout the integration process. Only regenerate your API Key if you are aware of the potential consequences, such as invalidating existing Zapier triggers and actions connected to your application.
+var app = builder.Build();
+
+// ...
+
+app.UseAuthorization(); //place under app.UseKentico()
+```
+
+In the appsettings configuration, you need to specify the list of the allowed objects which affects the object selection in the Zapier UI. Make sure you set up the appropriate objects for your application.
+
+You can view a sample of such configuration [here](./docs/Configuration-example.md).
+
+### Zapier administration application
 
+After configuring your application, a new application named **Zapier** should appear in your application's administration.
+This application consists of two submodules: a listing page of created Zapier triggers from the Zapier UI and a submodule for managing the API Key.
+
+- On the _List Zapier Triggers_ tab, you can view the list of created Zapier triggers. Items cannot be manually changed or added in the Admin application. Therefore, you must (and should) manage your triggers directly from the Zapier UI. A trigger record appears in the list after Zapier's zap publication. After turning the zap off, the corresponding record is automatically deleted.
+- On the 'API Key' tab, you can generate an API Key for communication between your application and Zapier itself.
+  - **Note that there is only one API Key per application**. It is crucial to securely store it and share it only with your Zapier editors. Once the API key is generated, you can only view it once.
+  - Generation of a new API Key can be done by all global administrators of the system and the users with the assigned permission **Generate** for _Zapier_ application.
+    ![Generate permission](/images/screenshots/zapiergeneratepermission.png "Generate permission")
+
+### Authentication in Zapier
+
+To connect Zapier with your application, you must authenticate your app first.
+
+- In the Zapier UI, you will be asked for the **domain of your application**.
+- Also, you must provide the **API Key** for your application.
+
+The API Key is used consistently throughout the integration process. Only regenerate your API Key if you are aware of the potential consequences, such as invalidating existing Zapier triggers and actions connected to your application.
 
-## Supported scenarios
+### Supported scenarios
 
 In the Zapier user interface, two primary features are available: triggers and actions.
- * Zapier trigger is an event or an action that initiates a workflow or a sequence of actions in Zapier. 
-   * Event in your Xperince by Kentico is the starting point of automation workflow.
- * Zapier action is a task or operation that Zapier performs as part of an automated workflow, triggered by an event in one application.
-   * Action results in creating, updating or otherwise managing data in your Xperince by Kentico application.
 
-Several scenarios that this integration allows are described below. The 'Catch Xperience by Kentico Webhook' trigger allows for more complex scenarios, offering numerous possibilities due to its generic design.
+- A Zapier trigger is an event that initiates a workflow or a sequence of actions in Zapier.
+  - The event in your Xperience by Kentico is the starting point of the automation workflow.
+- A Zapier action is a task or operation that Zapier performs as part of an automated workflow, triggered by an event in one application.
+  - The action results in creating, updating, or otherwise managing data in your Xperience by Kentico application.
 
-**BizForm** - triggers and actions interacting with Xperience by Kentico forms.
- * Trigger Create - Listening for form submission
-   * 'Catch Xperience by Kentico Webhook' connected to specific form class and listening to 'Create' event.
- * Action 'Insert form record' - Enables to create a form submission based on third party apps eg. Google Forms or based on another source of data.
+#### Supported trigger events
 
+**Content moves to a workflow step**
 
-**Event Log** - interaction based on event logs insertion
- * Trigger Create - Listening for the creation of a record in the event log
-    * 'Catch Xperience by Kentico Webhook' connected to CMS.EventLog type and listening to 'Create' event.
+- _Triggers when content item moves to a step._
+- Only moves to a _custom_ workflow step (created in _Workflows_ application) are supported.
+- To set up a trigger, you need to choose a **specific content type** (page, headless item, or reusable item). After that, the relevant workflow steps are loaded, and you need to select one **specific workflow step**. The event triggers when any content item of the chosen content type is moved **to** the selected workflow step.
+- The trigger record consists of:
+  - DisplayName - content item's display name
+  - ContentTypeName - name of content type
+  - StepName - new workflow step's display name
+  - OriginalStepName - previous workflow step's display name
+  - UserID
+  - AdminLink - link to the moved content item in administration
+  - UserName
+  - DateTime
 
-**Activity**
- * Trigger Create - Listening for some activity
-   * Set up similarly to the previous examples using a trigger 'Catch Xperience by Kentico Webhook'
+**New Event Log Entry**
 
-**Contact**
- * Trigger Create - Listening for the creation of a contact eg. to send it to CRM
-   * Set up similarly to the previous examples using a trigger 'Catch Xperience by Kentico Webhook'
+- _Triggers when a new event log is inserted._
+- In the trigger configuration step, you need to select at least one event log **severity**. It is allowed to select multiple severities.
+- The trigger record contains all event log info detail fields.
+  ![Fields in trigger record](/images/screenshots/zapiereventlogdetail.png "Fields in trigger record")
 
-**Page, headless item, reusable item**
-* Trigger Create - Listening for creation page or reusable item
-  * Set up similarly to the previous examples using a trigger 'Catch Xperience by Kentico Webhook'
-* Trigger 'Move to step' - Listening for a workflow change of a specific object (custom content workflow)
-  * Set up similarly to the previous examples using a 'Catch Xperience by Kentico Webhook' trigger, but with a workflow step event.
-* Action 'Move to step' - Pages, headless items, or reusable items can be moved to a specific step within a custom content workflow for the respective object.
-* Action 'Publish' -  Pages, headless items, or reusable items can be published using this action
+**New Form Submission**
 
+- _Triggers when a new form submission is created._
+- In the trigger configuration step, you need to select a specific form.
+- The trigger record contains:
+  - common field _FormInserted_ - time of submission
+  - form fields specific for individual forms
 
-<!--
-## Trigger Catch Xperience by Kentico Webhook
-The 'Catch Xperience by Kentico Webhook' trigger, being a complex feature, facilitates listening on multiple events such as Create, Update, and Delete (Enabled for Info objects, BizForm objects, Pages, Headless, Reusable).
+#### Supported action events
 
-Additionally, Pages, headless items, and reusable items can also monitor the publish event.
-Furthermore, if any of these types are under custom workflows, you can also listen for specific custom step events.
-For instance, detecting when a Page is moved to the prepublished step in a custom content workflow step created manually.
+**Insert Form Record**
 
-With this general settings it is possible to cover a large number of use cases.
--->
+- _Inserts a record into an XbyK form._
+- In the action configuration step, a specific XbyK form needs to be selected. After that, the form fields are dynamically loaded. Usually, you want to map trigger record's fields to those form fields.
+- Note that only key–value fields are supported. It's not possible to attach or upload a file to the form record.

examples/DancingGoat/appsettings.json

@@ -18,7 +18,6 @@
   },
   "CMSHashStringSalt": "40974ad7-76dd-4d5d-a70e-4539d5410492",
   "ZapierConfiguration": {
-    "WebAdminDomain": "nf54t8h6-26547.euw.devtunnels.ms",
     "AllowedObjects": [
       "cms.Role",
       "cms.user",