Walkthrough: Creating a custom form save action

Current version: 8.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:

  1. In Sitecore Forms, on the Forms dashboard, click Create. Select a template to base the form on.

  2. Add at least one field by dragging an element from the Form elements pane onto the form.

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

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

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

  2. On the Folder tab, click Empty Data Exchange Tenant.

  3. Select the created tenant and click the Data Exchange SDK tab in the top menu bar. On the ribbon, click Upgrade Tenant.

  4. In the Upgrade Tenant dialog, in the Instruction Set field, click Tenant Service.

  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:

    RequestResponseshell
    <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 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:

    RequestResponseshell
    <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. Value accessors are collected in value accessor sets.

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.

    Get in touch form element in the content tree
  3. Select the item you created and switch to the Content tab. Select the form you created and save the item.

    Settings section on the Content tab on the Get in touch form item
  4. On the top menu bar, click Data Exchange, and click Add Form Fields.

    Add Form Fields button on the Data Exchange tab on the menu ribbon
  5. To create value accessors, select the form fields whose values you want to read, and click OK.

    Form field value accessors dialog

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

    Full name value accessor under the Get in touch form item in the content tree

Create a pipeline

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

To create a pipeline:

  1. Navigate to <tenant>/Pipelines.

  2. In the right-hand pane, on the Folder tab, click 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:

    Configuring the value accessor on the Write to Log Pipeline Step dialog
  5. Save the changes.

Create value readers

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

To create value readers:

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

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

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

    The Type field in the Settings section for the FormModel From Http Content item
  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.

    The Storage Location field in the Setting section for the Synchronization Settings Plugin Value Reader item
  9. 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:

  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.

    The Plugin Readers field in the Content tab of the Pipeline Context Plugin Builder item
  5. 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:

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

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

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

    The Trigger DEF Sync Process option in the list of Submit actions
  3. 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.

  4. In the Connection String Name field, enter the connection string that points to the URL for the tenant web service.

    The Select the tenant service endpoint dialog
  5. 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,