Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

3 phase #13

Merged
merged 2 commits into from
Mar 20, 2024
Merged

3 phase #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a7183e8
Milestone with ContentTypes triggers, content workflows and actions f…
DanielJurcaBS Mar 18, 2024
9366ba9
labels validation fixes, update version to 0.1.0
DanielJurcaBS Mar 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,4 +139,5 @@ segments_2i
**/CMSModules/WebFarm/*

# Files Generated by this integration
**/App_Data/Zapier/*
**/App_Data/Zapier/*
/examples/DancingGoat/appsettings.Development.json
8 changes: 4 additions & 4 deletions Directory.Packages.props
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@
<DisableImplicitNuGetFallbackFolder>true</DisableImplicitNuGetFallbackFolder>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="Kentico.Xperience.Admin" Version="28.1.0" />
<PackageVersion Include="Kentico.Xperience.WebApp" Version="28.1.0" />
<PackageVersion Include="kentico.xperience.azurestorage" Version="28.1.0" />
<PackageVersion Include="kentico.xperience.imageprocessing" Version="28.1.0" />
<PackageVersion Include="Kentico.Xperience.Admin" Version="28.3.2" />
<PackageVersion Include="Kentico.Xperience.WebApp" Version="28.3.2" />
<PackageVersion Include="kentico.xperience.azurestorage" Version="28.3.2" />
<PackageVersion Include="kentico.xperience.imageprocessing" Version="28.3.2" />
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
<PackageVersion Include="SonarAnalyzer.CSharp" Version="9.6.0.74858" />
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
Expand Down
108 changes: 101 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,11 @@ Zapier integration enables seamless connectivity between a wide range of web app

## Library Version Matrix

This version supports content workflows added in version 28.3.0. Please ensure that your versions are up to date.

| Xperience Version | Library Version |
| ----------------- | --------------- |
| >= 28.1.0 | PREVIEW |
| >= 28.3.* | PREVIEW |

### Dependencies

Expand All @@ -41,7 +42,7 @@ Add the package to your application using the .NET CLI
dotnet add package Kentico.Xperience.Zapier
```

## Quick Start
## Quick Start (with trigger example)

1. Register required services into DI container.

Expand All @@ -62,10 +63,29 @@ dotnet add package Kentico.Xperience.Zapier
app.UseAuthorization() //place under app.UseKentico()
```

2. In the administration go to UI application 'Zapier'.
3. On the API Key menu generate new API key for your Zapier application.
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.

```csharp
// appsettings.json
"ZapierConfiguration": {
"WebAdminDomain": "myzapierapp.com",
"AllowedObjects": [
"cms.user",
"CMS.EventLog",
// ...
"DancingGoat.Banner",
"DancingGoat.ConfirmationPage",
// ...
"BizForm.DancingGoatContactUs",
]
}
```

3. In the administration go to UI application 'Zapier'.
4. On the API Key menu generate new API key for your Zapier application.
* Save the API key as it will appear only once.
4. Open your Zapier UI and create new Zap.
5. Open your Zapier UI and create new Zap.
* As a trigger pick Xperience by Kentico application
* Select Event "Catch Xperience by Kentico Webhook"
* Then you have to connect an Account using URL of your website (without trailing slash) and your generated API Key from previous step
Expand All @@ -74,12 +94,86 @@ dotnet add package Kentico.Xperience.Zapier
* Pick object in Xperience by Kentico which you want to set for an automation process
* Select type Event for your object
* Test your trigger
5. Now you can create your own workflow eg. connect with Gmail, Microsoft Teams, ...
6. Now you can create your own workflow eg. connect with Gmail, Microsoft Teams, ...
* You can find more information on https://zapier.com/workflows
6. After you finish your automation workflow... Publication of your Zap will create an object in your Xperience by Kentico application.
7. After you finish your automation workflow... 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


## Full Instructions

### Configure your application
Prerequisites for using this integration are a public application running on Xperience by Kentico 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 [here](./docs/Configuration-example.md).

### 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.


### 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

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.

**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.


**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.

**Activity**
* Trigger Create - Listening for some activity
* Set up similarly to the previous examples using a trigger 'Catch Xperience by Kentico Webhook'

**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'

**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


### 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).

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.

With this general settings it is possible to cover a large number of use cases.

## 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).
Expand Down
121 changes: 121 additions & 0 deletions docs/Configuration-example.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# Configuration of Zapier

This is example of ZapierConfiguration in appsettings.json.
The appropriate name of the allowed object corresponds to the ClassName in the CMS Class table.

```json
{
"ZapierConfiguration": {
"WebAdminDomain": "dancinggoatzapier.com",
"AllowedObjects": [
"cms.Role",
"cms.user",
"cms.UserRole",
"CMS.EventLog",
"cms.workflow",
"cms.workflowstep",
"cms.form",
"cms.ScheduledTask",
"cms.LicenseKey",
"cms.WebFarmServer",
"cms.WebFarmTask",
"CMS.SettingsKey",
"cms.FormRole",
"cms.settingscategory",
"CMS.ResourceString",
"CMS.ResourceTranslation",
"cms.AlternativeForm",
"cms.EmailAttachment",
"cms.email",
"cms.attachmentforemail",
"media.library",
"media.file",
"OM.Account",
"OM.AccountStatus",
"OM.Contact",
"OM.ContactStatus",
"OM.ContactRole",
"OM.AccountContact",
"OM.ContactGroup",
"OM.ContactGroupMember",
"OM.Activity",
"OM.ActivityType",
"CMS.WorkflowTransition",
"CMS.MacroRule",
"cms.workflowaction",
"CMS.AutomationHistory",
"CMS.ObjectWorkflowTrigger",
"CMS.AutomationState",
"cms.webfarmservertask",
"CMS.WebFarmServerMonitoring",
"CMS.WebFarmServerLog",
"OM.ActivityRecalculationQueue",
"CMS.ExternalLogin",
"OM.ContactChangeRecalculationQueue",
"OM.VisitorToContact",
"CMS.MacroIdentity",
"CMS.UserMacroIdentity",
"CMS.Consent",
"CMS.ConsentAgreement",
"CMS.ConsentArchive",
"Temp.PageBuilderWidgets",
"CMS.PageTemplateConfiguration",
"CMS.AutomationTemplate",
"CMS.FormFeaturedField",
"CMS.MacroRuleCategory",
"CMS.MacroRuleMacroRuleCategory",
"OM.TrackedWebsite",
"EmailLibrary.EmailConfiguration",
"EmailLibrary.EmailTemplate",
"CMS.ApplicationPermission",
"CMS.Channel",
"CMS.ContentItem",
"CMS.ContentLanguage",
"CMS.ContentTypeChannel",
"CMS.WebPageFormerUrlPath",
"CMS.WebPageItem",
"CMS.WebPageUrlPath",
"CMS.WebsiteCaptchaSettings",
"CMS.WebsiteChannel",
"EmailLibrary.EmailBounce",
"EmailLibrary.EmailChannel",
"EmailLibrary.EmailChannelSender",
"EmailLibrary.EmailLink",
"EmailLibrary.EmailMarketingRecipient",
"EmailLibrary.EmailStatistics",
"EmailLibrary.EmailStatisticsHits",
"EmailLibrary.EmailSubscriptionConfirmation",
"EmailLibrary.EmailTemplateContentType",
"EmailLibrary.RecipientListSettings",
"EmailLibrary.SendConfiguration",
"CMS.Member",
"CMS.MemberExternalLogin",
"CMS.HeadlessChannel",
"CMS.HeadlessItem",
"CMS.HeadlessToken",
"DancingGoat.ArticlePage",
"DancingGoat.ArticlesSection",
"DancingGoat.Banner",
"DancingGoat.Cafe",
"DancingGoat.Coffee",
"DancingGoat.ConfirmationPage",
"DancingGoat.Contact",
"DancingGoat.ContactsPage",
"DancingGoat.Email",
"DancingGoat.Event",
"DancingGoat.HomePage",
"DancingGoat.Image",
"DancingGoat.LandingPage",
"DancingGoat.NavigationItem",
"DancingGoat.PrivacyPage",
"DancingGoat.Reference",
"DancingGoat.SocialLink",
"BizForm.DancingGoatCoffeeSampleList",
"BizForm.DancingGoatContactUs",
"BizForm.DancingGoatSubscription",
"KenticoZapier.ZapierTrigger",
"DancingGoat.HeadlessUser"
]
}
}
```
1 change: 0 additions & 1 deletion examples/DancingGoat/Properties/launchSettings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@
},
"DancingGoat": {
"commandName": "Project",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
},
Expand Down
Loading
Loading