Walkthrough: Creating a custom form save action

Abstract

How to set up a custom Data Exchange Framework (DEF) save action for Experience Forms.

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

To set up a custom save action, you must:

Create a form

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

  1. In the Sitecore Launchpad, click Forms. Click Create, and click Blank form to create a new form. Name it, for example, Get in touch form.

  2. Add a single-line text field to the form and name it, for example, Full Name. Add a submit button.

    example form

  3. Save the form.

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:

  1. Open the Content Editor and navigate to /sitecore/system/Data Exchange.

  2. On the Folder tab, click Empty Data Exchange Tenant to create a new tenant.

  3. Select the created tenant and click on the Data Exchange SDK tab in the top menu bar.

  4. Click Upgrade Tenant. In the Instruction Set field, click the Tenant Service option.

  5. 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:

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

  6. On your Sitecore Content Management and Marketing Automation Service servers, 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:

    <xmlversion="1.0" encoding="utf-8">
<connectionStrings>
    <add name="my-tenant" connectionString="https://my-tenant.service"/>
</connectionStrings>

  7. 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. To create the value accessors:

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

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

    example form in content tree

  3. Select the item you created and switch to the Content tab. Select the form you created and save the item.

    settings for example form

  4. From top menu bar, select Data Exchange, and click Add Form Fields.

    add form fields button

  5. To create value accessors, select the form fields whose values you want to read, and click OK.

    form field value accessors

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

    form field in content tree

Create a pipeline

To create a pipeline:

  1. Navigate to <tenant>/Pipelines.

  2. On the Folder tab, click Pipeline to create a pipeline. Name it, for example, Form Testing Pipeline.

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

  4. Select the pipeline step and configure the Full Name value accessor as shown:

    object location for pipeline step

  5. Save the changes.

Create value readers

To create value readers:

  1. Navigate to <tenant>/Data Access/Value Readers/Common/.

  2. On the Home tab, click Dot Net Object from HttpRequest Content Value Reader to create new item. Name it, for example, FormModel From Http Content.

  3. Set the Type field to Sitecore.DataExchange.ExperienceForms.Models.FormModel, Sitecore.DataExchange.ExperienceForms.Models.

    settings for formmodel

  4. Navigate to <tenant>/Data Access/Value Readers/Common/.

  5. On the Folder tab, click Raw Value Reader to create a new item. Name it, for example, Raw Value Reader.

  6. Navigate to <tenant>/Data Access/Value Readers/Common/.

  7. On the Folder tab, click Synchronization Settings Plugin Value Reader to create a new item. Name it Synchronization Settings Plugin Value Reader.

  8. Set the Storage Location to Source.

    storage location for value reader

  9. Save the changes.

Create a pipeline context builder

To create a pipeline context builder:

  1. Navigate to <tenant>/Tenant Service Settings/Pipeline Context Builders.

  2. On the Folder tab, click Pipeline Context Plugin Builder to create a new item. Name it, for example, Pipeline Context Plugin Builder.

  3. Set the Value Transformer field to the http request value reader that you created in the previous step.

  4. Set the Plugin Readers field to the synchronization settings plugin value reader that you created in the previous step.

    settings for pipeline context plugin builder

  5. Save the changes.

Create a tenant service endpoint

To create a tenant service endpoint:

  1. Navigate to <tenant>/Tenant Service Endpoints.

  2. On the Folder tab, click Pipeline Tenant Service Endpoint to create a new item. Call it, for example, Form submitted endpoint.

  3. Configure the endpoint with the parameters in this 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

  4. Select the Enabled checkbox. Save the changes.

Configure the form

You must configure the form to trigger the tenant service endpoint when a user saves the form. To do so:

  1. From Sitecore Launchpad, click Forms and select the form that you created.

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

    select trigger def sync process

  3. In the Select the tenant service endpoint pop-up, 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.

    select the tenant service endpoint

  4. 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 need to troubleshoot the process, check the tenant web service logs.