Skip to content

Commit 2e4f1df

Browse files
acoumbacoumb
authored
Merge pull request #72 from umbraco/v10/docs/update-integrations-docs
Updated documentation
2 parents d7ffa9f + 788437e commit 2e4f1df

File tree

4 files changed

+4
-296
lines changed
  • src
    • Umbraco.Forms.Integrations.Automation.Zapier
    • Umbraco.Forms.Integrations.Commerce.EMerchantPay
    • Umbraco.Forms.Integrations.Crm.ActiveCampaign
    • Umbraco.Forms.Integrations.Crm.Hubspot

4 files changed

+4
-296
lines changed

‎src/Umbraco.Forms.Integrations.Automation.Zapier/readme.md

Lines changed: 1 addition & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,3 @@
11
# Umbraco.Forms.Integrations.Automation.Zapier
22

3-
This integration is an add-on to the Umbraco CMS integration available [here](https://github.com/umbraco/Umbraco.Cms.Integrations/tree/main/src/Umbraco.Cms.Integrations.Automation.Zapier), and provides necessary components for handling form submissions based on the registered subscription hooks.
4-
5-
A Zap is an automated workflow that connects various apps and services together. Each Zap consists of a trigger and one or more actions.
6-
7-
## Prerequisites
8-
9-
Requires minimum versions of Umbraco:
10-
11-
- CMS: 10.1.0
12-
- Forms: 10.1.0
13-
14-
## How To Use
15-
16-
### Authentication
17-
18-
For this integration, the authentication is managed on Zapier's side by using the Umbraco marketplace app.
19-
20-
The Umbraco app manages two types of events:
21-
* New Form Submission - triggers when a form is submitted
22-
* New Content Published - triggers when a new content has been published.
23-
24-
The trigger event to be used by this integration is _New Form Submission_.
25-
26-
When creating the Zap trigger, you will be prompted to enter a username, password and the URL for your Umbraco website, or you can use instead an API key.
27-
If the following setting is present, then the API key based authentication will take precendence and will be the main method of authorization.
28-
```
29-
"Umbraco": {
30-
...
31-
"Forms": {
32-
"Integrations": {
33-
"Automation": {
34-
"Zapier": {
35-
"Settings": {
36-
"ApiKey": "[your_api_key]"
37-
}
38-
}
39-
}
40-
}
41-
}
42-
...
43-
}
44-
```
45-
46-
If no API key is present, then the Umbraco application will validate the credentials entered and return a message in case the validation fails.
47-
48-
If you want to extend the security layer, you can also specify a user group that the user trying to connect needs to be a part of, by adding the following
49-
setting in `appsettings.json`:
50-
51-
```
52-
"Umbraco": {
53-
...
54-
"Settings": {
55-
"UserGroup": "[your_user_group]"
56-
}
57-
...
58-
}
59-
```
60-
61-
### Working With the Zapier Forms Integration
62-
In the _Content_ area of the backoffice, find the _Zapier Integrations_ dashboard.
63-
64-
The dashboard is composed of two sections:
65-
* Content Properties - Zapier details and input fields for adding content configurations
66-
* Registered Subscription Hooks - list of registered entities.
67-
68-
Subscription hooks are split in two categories:
69-
* 1 = Content
70-
* 2 = Form
71-
72-
The _Trigger Webhook_ action will send a test request to the Zap trigger, enabling the preview of requests in the Zap setup workflow.
3+
Documentation for the __Zapier__ integration is available at the [Umbraco documentation website](https://docs.umbraco.com/umbraco-dxp/integrations/zapier-with-umbraco-forms).

‎src/Umbraco.Forms.Integrations.Commerce.EMerchantPay/readme.md

Lines changed: 1 addition & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,3 @@
11
# Umbraco.Forms.Integrations.Commerce.emerchantpay
22

3-
This integration provides a custom workflow for handling online payments using a hosted payment page provided by emerchantpay.
4-
5-
## Prerequisites
6-
7-
Required minimum versions of Umbraco CMS:
8-
- CMS: 10.1.0
9-
- Forms: 10.1.0
10-
11-
## How To Use
12-
13-
To get started with _emerchantpay_ a merchant would need to be onboarded in order to get a merchant ID and obtain the keys
14-
required by the integration.
15-
16-
To begin the onboarding process an obtain the merchant account, you would need to fill out [this](https://www.emerchantpay.com/contact-us?utm_source__c=umbraco_referral&utm_medium__c=technical_blog&utm_campaign__c=Umbraco) form.
17-
Afterwards, a member of the _emerchantpay_ team will reach out to you.
18-
19-
### Customer journey map
20-
A merchant getting started with emerchantpay and Umbraco will need to make sure that they have an emerchantpay merchant account enabled and then cover these steps:
21-
22-
* Package Installation
23-
* Site Settings
24-
* Workflow Setup
25-
26-
### Authentication
27-
28-
All requests to emerchantpay API are authenticated by providing the merchant's username and password.
29-
30-
If the configuration is incomplete, the user will receive an error message.
31-
32-
### Configuration
33-
34-
The emerchantpay API endpoints accept and return XML data. When the form is submitted, two batches of payload data are exchanged: one for handling consumer information and the second one for creating the payment.
35-
36-
A consumer has the following available properties that can be mapped against form fields:
37-
* Email
38-
* FirstName
39-
* LastName
40-
* Address1
41-
* Address2
42-
* ZipCode
43-
* City
44-
* State
45-
* Country
46-
* Phone
47-
48-
The below configuration - consisting of authentication settings, merchant specific details and customizable payment fields - is required. Some configuration items
49-
are stored as an array of strings or a dictionary, and parsed using a specific service.
50-
51-
```
52-
{
53-
"Umbraco": {
54-
"Forms": {
55-
"Integrations": {
56-
"Commerce": {
57-
"Emerchantpay": {
58-
"Settings": {
59-
"GatewayBaseUrl": "https://staging.gate.emerchantpay.net/",
60-
"WpfUrl": "https://staging.wpf.emerchantpay.net/wpf/",
61-
"Username": "[your_merchant_username]",
62-
"Password": "[your_merchant_password]",
63-
"UmbracoBaseUrl": "[your_website_url]",
64-
"Supplier": "Umbraco",
65-
"Usage": "Payment Gateway using Umbraco Forms",
66-
"Currencies": {
67-
"USD": "US Dollar",
68-
"EUR": "Euro",
69-
"GBP": "British Pound",
70-
"DKK": "Danish Krone"
71-
},
72-
"TransactionTypes": [ "authorize", "sale" ],
73-
"MappingFields": [ "Email", "FirstName", "LastName" ]
74-
}
75-
}
76-
}
77-
}
78-
}
79-
}
80-
}
81-
```
82-
83-
### Working with the Umbraco Forms - emerchantpay integration
84-
85-
To use it you will need to attach the _emerchantpay Gateway_ to a form and map the _Amount_, _Currency_, _Number of Items_, _Record Status_, _Record Payment Unique ID_ and _Consumer Details_ with matching form fields, then configure the event handlers
86-
for payment sucessfully processed, failed or cancelled.
87-
88-
When a form is submitted on the website, the workflow will execute and based on it's settings, two data payloads will be sent to emerchantpay for creating or retrieving the details of a consumer, and for creating a payment.
89-
The response for the second request will provide the URL for the hosted payment page, and the user will the redirected there.
90-
91-
On completing the payment the emerchantpay API will return the user to the page provided in matching event handler of the worklow.
92-
93-
94-
### Version History
95-
* 2.0.3 - Add payment operations logging
96-
* 2.0.2 - Fix record approve bug
97-
* 2.0.1 - Add package icon
98-
* 2.0.0 - Initial release
99-
* 1.0.3 - Add payment operations logging
100-
* 1.0.2 - Fix record approve bug
101-
* 1.0.1 - Add package icon
102-
* 1.0.0 - Initial release
3+
Documentation for the __emerchantpay__ integration is available at the [Umbraco documentation website](https://docs.umbraco.com/umbraco-dxp/integrations/emerchantpay-with-umbraco-forms).

‎src/Umbraco.Forms.Integrations.Crm.ActiveCampaign/readme.md

Lines changed: 1 addition & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,3 @@
11
# Umbraco.Forms.Integrations.Crm.ActiveCampaign
22

3-
This integration provides a custom workflow, allowing form entries to be mapped to an ActiveCampaign contact record, a contact's custom fields or to associate a contact with an existing CRM account.
4-
5-
## Prerequisites
6-
7-
Required minimum versions of Umbraco CMS:
8-
- CMS: 10.1.0
9-
- Forms: 10.1.0
10-
11-
## How To Use
12-
13-
### Authentication
14-
15-
All requests to the ActiveCampaign API are authenticated by providing
16-
an API key. The API key is included as an HTTP header called _Api-Token_.
17-
18-
If the configuration is incomplete, the user will receive an error message.
19-
20-
### Configuration
21-
22-
An ActiveCampaign contact has four main properties: email, first name, last name and phone.
23-
To connect to your ActiveCampaign account, the following configuration is required:
24-
```
25-
"Umbraco": {
26-
"CMS": {
27-
"Integrations": {
28-
"Crm": {
29-
"ActiveCampaign": {
30-
"Settings": {
31-
"BaseUrl": "https://[YOUR_ACCOUNT_NAME].api-us1.com",
32-
"ApiKey": "[YOUR_API_KEY]",
33-
"ContactFields": [
34-
{
35-
"name": "email",
36-
"displayName": "Email",
37-
"required": true
38-
},
39-
{
40-
"name": "firstName",
41-
"displayName": "First Name",
42-
"required": false
43-
},
44-
{
45-
"name": "lastName",
46-
"displayName": "Last Name",
47-
"required": false
48-
},
49-
{
50-
"name": "phone",
51-
"displayName": "Phone",
52-
"required": true
53-
}
54-
]
55-
}
56-
}
57-
}
58-
}
59-
}
60-
}
61-
```
62-
Email property is mandatory by default through ActiveCampaign API rules. The
63-
required rule can be extended to the other properties as well, by explicitly specifying that in the ```required```
64-
property of each ```ContactFields``` node.
65-
66-
67-
### Working with the Umbraco Forms - ActiveCampaign integration
68-
69-
To use it you will need to attach the _ActiveCampaign Contacts Workflow_ to a form, configure the mappings between the contact properties and the form fields,
70-
select an account if you want to associate the contacts, and/or map any contact custom fields.
71-
72-
When a form is submitted on the website, the workflow will execute and based on the provided email, create or update an ActiveCampaign account. If custom fields mappings
73-
have been provided, the contact payload will contain custom fields values.
74-
75-
After the account data has been persisted, if an account has been provided in the workflow setup, then an association with the account will be created.
3+
Documentation for the __ActiveCampaign__ integration is available at the [Umbraco documentation website](https://docs.umbraco.com/umbraco-dxp/integrations/activecampaign-with-umbraco-forms).

‎src/Umbraco.Forms.Integrations.Crm.Hubspot/readme.md

Lines changed: 1 addition & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,3 @@
11
# Umbraco.Forms.Integrations.Crm.Hubspot
22

3-
This integration provides a custom workflow, allowing form entries to be mapped to a HubSpot contact record, and stored within the CRM platform.
4-
5-
## Prerequisites
6-
7-
Requires minimum versions of Umbraco:
8-
9-
- CMS: 10.1.0
10-
- Forms: 10.1.0
11-
12-
## How To Use
13-
14-
### Authentication
15-
16-
The package supports authentication using the OAuth protocol.
17-
18-
Using the workflow, the user will be made aware that the installation is not authenticated with HubSpot and can't currently be used.
19-
20-
They will be prompted to click a link which will take them to the HubSpot authentication page for the Umbraco Forms HubSpot app.
21-
22-
They will need to log into their HubSpot account and agree to the permissions that the app requires (which is to be able to read and write contact information).
23-
24-
They will then be redirected to a website hosted at https://hubspot-forms-auth.umbraco.com which will present an authorization code issued by HubSpot. It's necessary to copy that and paste into the field indicated within the Umbraco Forms installation.
25-
26-
Behind the scenes this will make a further request to HubSpot which will return two tokens - an access token and a refresh token. The former will be provided in further API calls to HubSpot to authenticate the request. The latter will be stored via Umbraco's key/value service (which writes to the `umbracoKeyValue` table) and will be used to retrieve a new access token when it expires.
27-
28-
A button is available to clear the authentication with HubSpot, following which the authentication process would need to be repeated before the integration can again be used.
29-
30-
When the OAuth authentication method is being used, the API call to retrieve the token is proxied via and endpoint on the same website, allowing the Umbraco Forms HubSpot app secret key to remain secret (i.e. not included in configuration or hard-coded into the dll).
31-
32-
##### OAuth Proxy Site
33-
34-
The website used for the OAuth proxy is defined as infrastructure as code in [these templates(https://github.com/umbraco/Umbraco.Cloud.Infrastructure/blob/master/tf-modules/azure/services/umbraco-forms-hubspot-auth/README.md)] (Umbraco HQ access only).
35-
36-
##### Hubspot App
37-
38-
The Hubspot App used for authentication is managed from [here](https://app-eu1.hubspot.com/developer/25171316/application/457256) (Umbraco HQ access only - account hubspot-developers-8usep1.com / 25171316).).
39-
40-
### Working With the HubSpot/Umbraco Forms Integration
41-
42-
Add the "Save Contact to Hubspot" workflow to a form and configure the mappings between the form and Hubspot fields.
43-
44-
![Select the HubSpot workflow](./img/select-workflow.png)
45-
46-
![Defining mappings](./img/mapping.png)
47-
48-
When a form is submitted on the website, the workflow will execute and create a new contact record in your Hubspot account, using the information mapped from the fields in the form submission.
49-
50-
![Hubspot contacts](./img/hubspot-contacts.png)
51-
52-
## For Further Consideration
53-
54-
- Currently the full set of contact properties are surfaced in the UI. Further research needed to see if we can restrict this to only those used within the account, or to add custom properties.
55-
- Validation in the Umbraco Forms form and the HubSpot contact record may not match (e.g. a field required by HubSpot may not be in the form).
3+
Documentation for the __HubSpot__ integration is available at the [Umbraco documentation website](https://docs.umbraco.com/umbraco-dxp/integrations/hubspot-with-umbraco-forms).

0 commit comments

Comments
 (0)