Walkthrough: Creating a custom form save action

Current version: 7.0

This topic shows you an example of how to set up a custom Data Exchange Framework (DEF) save action for Experience Forms.

This walkthrough describes how to:

Create a form
Create a tenant
Create value accessors
Create a pipeline
Create value readers
Create a pipeline context builder
Create a Tenant Service Endpoint
Configure the form.

Create a form

When a website visitor submits a form on the website it triggers the save action.

To prepare a form:

In Sitecore Forms, on the Forms dashboard, click Create. Select a template to base the form on.
Add at least one field by dragging an element from the Form elements pane onto the form.
On the toolbar, click Save to save and name the form.

Note

You can use the Form Designer to continue designing the form using various form elements, as required.
To make the form available on a web page, follow the instructions in Add a form to a webpage.

Note

If you have a Sitecore scaled deployment (XP1), you must ensure that the .cshtml file for the form is copied to your content delivery (CD) servers. For example, <CD server>\Views\Shared\<filename>.cshtml.

Create a tenant

The tenant is a container for the settings that must be configured for the save action.

To create a tenant:

In the Content Editor navigate to /sitecore/system/Data Exchange.
On the Folder tab, click Empty Data Exchange Tenant.
Select the created tenant and click the Data Exchange SDK tab in the top menu bar. On the ribbon, click Upgrade Tenant.
In the Upgrade Tenant dialog, in the Instruction Set field, click Tenant Service.
Make a note of the tenant ID. Add the tenant ID, host, and credentials in the <tenant service>\App_Config\ConnectionStrings.config file, in the connection string called Sitecore. For example:
RequestResponse
```
<connectionStrings>
    <add name="sitecore" connectionString="database=master;tenant id={841B0E94-4348-494D-B32D-CA5E94F26ACC};host=my-sitecore;password=b;user name=sitecore\admin;timeout=20" />
</connectionStrings>
```
Note

If you have a Sitecore scaled deployment (XP1), change the database parameter to web, and change the host parameter to the URL of your CD server.
On your Sitecore content management server, in the App_Config\connectionstring.config file, make sure you have a connection string for the tenant web service associated with the tenant. For example:
RequestResponse
```
<xmlversion="1.0" encoding="utf-8">
<connectionStrings>
    <add name="my-tenant" connectionString="https://my-tenant.service"/>
</connectionStrings>
```
If you have a Sitecore scaled deployment (XP1), you must also add the Tenant Service connection string to the connectionstring.config file on your CD server.

Create value accessors

Value accessors read the values of the fields in the form. Value accessors are collected in value accessor sets.

To create the value accessors:

Navigate to <tenant>/Data Access/Value Accessor Sets/Providers. If you already have a Forms folder, open it. If not, on the Folder tab, click Forms Value Accessor Set to create and open the Forms folder.
In the Forms folder, on the Folder tab, click Forms Value Accessor Set to create a new item. Name it, for example, Get in touch form.
Select the item you created and switch to the Content tab. Select the form you created and save the item.
On the top menu bar, click Data Exchange, and click Add Form Fields.
To create value accessors, select the form fields whose values you want to read, and click OK.

The value accessors are located under the value accessor set item.

Create a pipeline

Pipelines collect and organize the pipeline steps that are the individual processes that together perform the action.

To create a pipeline:

Navigate to <tenant>/Pipelines.
In the right-hand pane, on the Folder tab, click Pipeline. Name it, for example, Form Testing Pipeline.
On the Folder tab, click Write to Log Pipeline Step to create a new pipeline step. Name it, for example, Write to Log Pipeline Step.
Select the pipeline step and configure the Full Name value accessor as shown:
Save the changes.

Create value readers

You use value readers to read the values of the fields in the form.

To create value readers:

Navigate to <tenant>/Data Access/Value Readers/Common/.
On the Home tab, to create a new item, click Dot Net Object from HttpRequest Content Value Reader. Name it, for example, FormModel From Http Content.
Set the Type field to Sitecore.DataExchange.ExperienceForms.Models.FormModel, Sitecore.DataExchange.ExperienceForms.Models.
Navigate to <tenant>/Data Access/Value Readers/Common/.
On the Folder tab, click Raw Value Reader to create a new item. Name it, for example, Raw Value Reader.
Navigate to <tenant>/Data Access/Value Readers/Common/.
On the Folder tab, click Synchronization Settings Plugin Value Reader to create a new item. Name it Synchronization Settings Plugin Value Reader.
Set the Storage Location to Source.
Save the changes.

Create a pipeline context builder

The pipeline context builder component extracts request data in an appropriate format, builds the pipeline context, and provides context to the data from the request.

To create a pipeline context builder:

Navigate to <tenant>/Tenant Service Settings/Pipeline Context Builders.
On the Folder tab, click Pipeline Context Plugin Builder to create a new item. Name it, for example, Pipeline Context Plugin Builder.
Set the Value Transformer field to the http request value reader that you created in the previous step.
Set the Plugin Readers field to the synchronization settings plugin value reader that you created in the previous step.
Save the changes.

Create a Tenant Service Endpoint

You must have a Tenant Service Endpoint (TSE) to resolve incoming requests in order to push request data through the DEF pipeline.

To create a Tenant Service Endpoint:

Navigate to <tenant>/Tenant Service Endpoints.
On the Folder tab, click Pipeline Tenant Service Endpoint to create a new item. Call it, for example, Form submitted endpoint.

Configure the endpoint with the parameters in the following table:

Parameter	Content
Request Value Reader	Value Readers/Common/Raw Value Reader
Pipeline Context Builder	Pipeline Context Builders/Pipeline Context Plugin Builder
Pipeline	Pipelines/Form Testing Pipeline

Select the Enabled check box. Save the changes.

Configure the form

You must configure the form to trigger the Tenant Service Endpoint when a user saves the form.

To configure the form:

On the Sitecore Launchpad, click Forms and select the form that you created.
Select the Submit button in the form. On the General tab, in the Submit Actions section, click the plus sign to open a list of actions. In the list, click Trigger DEF Sync Process to add a submit action.
In the Select the tenant service endpoint dialog, in the Data Exchange structure, select the Tenant Service Endpoint that you want to trigger when the form is submitted.
In the Connection String Name field, enter the connection string that points to the URL for the tenant web service.
Attach the form to a webpage and publish it. Now, whenever a user submits the form, it triggers the Tenant Service Endpoint to run the selected pipeline.

If you want to troubleshoot the process, check the Tenant Service logs.

Do you have some feedback for us?

If you have suggestions for improving this article,