Help Center

Menu

Custom form submission actions screen

The Submission actions screen on a custom form allows you to create custom actions that run whenever the user submits the form. These actions can do things such as send an email or perform a database query.

Call REST resource

The Call REST resource action submission action communicates with a web service exposing itself using representational state transfer (REST) methods.

To add this action:

  1. Select the Create a new action of type option in the Add new action section.

  2. Select Call REST resource.

  3. Select Save.

The action is added to the existing actions section.

Additional fields also appear in the selected action section.

Read the Web services assets documentation for more information on these fields.

Validation rule

The Validation rule section of the Call REST resource action allows you to enable validation on the REST call response. The action will check the HTTP response code or body against a set validation rule.

The validation rule settings for the *Call REST resource submission* action

The fields available are as follows:

Enable validation

Selecting this field will enable validation checking on the REST call response as per the conditions specified in the validation rule field.

Validation rule

This field allows you to configure the rule against which to check the REST response. The fields available allow you to specify that All or One of either the HTTP code or Response body must:

  • Match or not match a specified regular expression value,

  • Be greater than a specified numerical value, or

  • Be less than a specified numerical value.

Global keyword replacements and keyword modifiers can be used when configuring this validation rule.

Custom error text

This field allows you to specify the error message displayed when the REST response does not meet the set conditions for validation. Form submission of the form will stop. The error message specified in this field will be displayed to the user (the error will also be logged to the Matrix database).

Create SharePoint list item

The Create SharePoint list item submission action submits form submissions as SharePoint list items. To add this action:

  1. Select the Create a new action of type option in the Add new action section.

  2. Select Create SharePoint list item.

  3. Select Save.

The action is added to the existing actions section.

Additional fields also appear in the selected action section.

For more information on the Create SharePoint list item action, refer to the Using a custom form to create SharePoint list items example in the SharePoint manual.

Make SOAP call

The Make SOAP call submission action sends a message to a remote SOAP server.

To add this action:

  1. Check the Create a new action of type option in the Add new action section.

  2. Select Make SOAP call.

  3. Select Save.

The make SOAP call action supports both SOAP 1.1 and SOAP 1.2 standards. However, WS-Security features and MIME multi-part attachments are not currently supported by this submission action.

The fields available in this section are as follows:

Action name

This is the name of the action that you have added. By default, it is set to Make SOAP call before submit. This name appears in the Action name / type field in the Existing actions section.

WSDL

Enter the URL to the WSDL of the SOAP server.

Authentication type

Select the authentication to use to access the SOAP server. The following authentication types are available:

HTTP basic

Basic HTTP authentication using specified username and password.

JSESSION ID cookie

Uses a JSESSIONID cookie to communicate with Oracle CRM On Demand web services.

WSS username token

User identity authentication using a WS-Security username token.

WSS password digest

Like the WSS username token authentication type, with the addition of a nonce token that includes a creation timestamp and sends the password as a digest hash.

Marketo signature

Allows integration with a Marketo service, allowing for the creation, retrieval, and removal of entities and stored data. For more information, refer to the Marketo developers site.

NTLM

Uses NTLM authentication using the specified username and password.

Authentication details

Enter the authentication details of the SOAP server connection. The fields available in this section will differ, depending on the authentication selected in the authentication type field. The following fields are available if you are using either the HTTP basic, WSS username token, or WSS password digest authorization types.

Username

Enter the username used to connect to the SOAP server.

Password

Enter the password used to connect to the SOAP server.

If you are using the JSESSIONID cookie authorization type, the following fields will also be available:

Auth URL

Enter the sign-in URL for the web service.

If you are using the Marketo signature authorization type, the following fields will be available:

Access key

Enter the access key (user ID) for the connection, as provided to you by Marketo.

Secret key

Enter the secret key (encryption key) for the connection, as provided to you by Marketo.

The following authentication options are available for SOAP servers used over HTTPS:

Local certificate

Select the local certificate for authentication on the SOAP server.

Passphrase

Enter the passphrase for authentication on the SOAP server. Once you have done this, select Save.

Additional fields will be displayed to view the SOAP server’s request and response messages and any generated keyword replacements.

Additional SOAP headers

This section allows you to configure additional request headers to be sent by the SOAP call. For each SOAP header that is added, you can configure the following fields:

Node name

The name of the node tag with which to construct the header.

Node value

The value of the header node tag.

Encoding

Select the encoding type to use for this header.

This setting will automatically convert the node value to the correct format for the encoding type when the SOAP call is made.

Namespace

The namespace to use for this header. This namespace is added to the SOAP envelope tag surrounding the whole SOAP XML request.

Type name

The name to use for the type namespace value in the node tag with which to construct the header.

Type namespace

The type namespace to use for this header. This namespace is added to the SOAP envelope tag surrounding the whole SOAP XML request.

Must understand

If enabled, this header element is considered mandatory, and the SOAP recipient must support it. The SOAP server endpoint should then not process the SOAP call if it does not recognize the header.

Delete

Click to delete this header from the SOAP call configuration.

The following is an example of an additional SOAP header and how each value is translated into the SOAP request with a WSDL URL value of http://www.webservicex.com/globalweather.asmx?WSDL.

Table 1. Example
Node name Node value Encoding Namespace Type name Type namespace Must understand

aaa

bbb

xsd_string

ccc

ddd

eee

yes

This will be translated into the following SOAP XML request:

<?XML version="1.0"  encoding="utf-8"?><soap-env:envelope XMLns:soap-env="http://schemas.XMLsoap.org/soap/envelope/" XMLns:ns1="http://www.webservicex.net" XMLns:ns2="eee" XMLns:xsi="http://www.w3.org/2001/XMLschema-instance" XMLns:ns3="ccc">    <soap-env:header>        <ns3:aaa xsi:type="ns2:ddd" soap:mustunderstand="1">bbb</ns3:aaa>    </soap-env:header>    <soap-env:body>      ...
   </soap-env:body></soap-env:envelope>

SOAP options section

This section allows you to configure additional options on the Make SOAP call submission action.

The fields available in this section are as follows:

Cache WSDL

Select the caching system for the retrieved WSDL file information of the SOAP server (as specified in the WSDL field). Caching the WSDL file is useful if this information is usually unaltered, allowing Matrix to instead retrieve the WSDL file information directly, potentially improving performance. The caching options available are:

  • Never cache (the default option)

  • Cache to disk

  • Cache to memory

  • Cache to both disk and memory.

Mute SOAP exceptions

If the SOAP client throws an exception, a response will not be returned by the submission action. This option allows you to select whether to disregard these SOAP exceptions. If this field is enabled, SOAP responses will be returned even if an exception is thrown.

Test response

This section allows you to test the response of the SOAP request specified in the SOAP request message section.

To do this:

  1. Select the Run test field.

  2. Select Save.

A sample SOAP request and response will be printed in this section:

Testing the response of the SOAP request

The tool is useful for testing purposes when configuring the SOAP call in the SOAP request message section.

SOAP request message

This section allows you to view the actions available and edit the request message of the SOAP call.

The fields available are as follows:

Action

Select the action to use on the request message. These actions are determined by the file that has been selected in the WSDL field.

Parameters

The default request message of the selected action will be listed in this section, allowing you to configure the action’s parameter values (marked as ??).
Field keyword replacements can be used in the request message, for example, %response_100_q1% , %question_name_100_q1% or %file_upload_100_q2%.
You can also use the %file_upload_100_q1% keyword to access the file uploaded into a file upload form field. Using the ^base64encode keyword modifier, you can then also print the contents of the uploaded file in base64 format, for example, %file_upload_100_q1^base64encode%.

XML namespaces are also supported.

Example
<?XML version="1.0"?><flt:fwtobjectid  XMLns:flt="http://www.example.com/WSDL/fltypes">  <flt:objecttype>foo</flt:objecttype></flt:fwtobjectid>

SOAP response message

This section displays the default response message from the SOAP call, displaying the parameter values that will be returned (marked as ??).

Check response

This section allows you to specify a field on the SOAP response for validation purposes. Matrix will display custom error messages if incorrect data is returned on the SOAP response.

The New field to check? field will list the available SOAP response fields, populated by the request message configured in the SOAP request message section.

To enable data validation on a response field:

  1. Select the field in this list.

  2. Select Save.

Additional fields will appear in this section.

Additional fields in the check response section

The following fields are available to configure the check response validation requirements:

Rule

Specify the rule that will evaluate whether or not data returned on the SOAP response is valid. The rule types available are:

  • Must contain

  • Must contain (case sensitive)

  • Must NOT contain

  • Must NOT contain (case sensitive)

  • Must be equal to

  • Must NOT be equal not

  • Must be less than

  • Must be less than or equal to

  • Must be more than

  • Must be more than or equal to.

Value

Enter a value used to evaluate whether or not data returned on the SOAP response is valid (as determined by the rule type selected in the Rule field).

Error message

Enter an error to display for users if data validation fails. You can use the keywords listed in the keywords available section on this error message.

For example, if you set the validation rule and value as Must NOT contain fail the result can only be valid if it does not contain the value Fail. If it contains this value, the returned data will be evaluated as invalid. The error configured in the error message field will be displayed.

Error messages defined in the check response section are displayed on the custom form through the %form_errors% keyword replacement. When the validation check fails, users will not be permitted to submit their form. Only when all errors have been addressed and validation succeeds can a form submission be made.

To delete a SOAP response field from the check response section:

  1. Select the corresponding Delete checkbox.

  2. Select Save.

Keywords available

The parameter values returned from the SOAP call will be stored as global session variables and can be printed using the keyword replacements listed in this section. These keyword replacements will differ depending on the parameters of the SOAP action.

An example of the keywords available section:

The *Keywords available* section of the make SOAP call submission action

Response to download as file

This section allows you to specify keywords (as listed in the keywords available section) that correspond to files on the SOAP response, temporarily storing them on the Matrix server.

To use this field, enter the field keywords that will return files on the SOAP response. When a file is returned on the SOAP response, Matrix will temporarily store this file on the server and replace the specified keyword with a relative URL to this file.

As you commit each keyword in this field, additional fields will appear, allowing you to configure multiple field keywords.

Log

This section allows you to enable custom logging for the SOAP requests. The following configuration options are available:

Enable log

Enable this to turn on the custom logging feature for this SOAP call.

Location

Enter the location on the file server under which the logs are to be created. The path is relative to your Matrix installation location unless prefixed with a /. This path must be allowed in the authorized file write paths setting under the External tools configuration screen.

Log name

Enter the name of the log file name.

Log format

Enter the format of each log entry.

Marketo submit form

This feature requires a Marketo bridge to be integrated and configured in your system.

The Marketo submit form submission action lets you perform a native form submission from Matrix, into a form configured in Marketo.

This feature is useful if you want to have triggers that fire marketing campaigns in Marketo whenever a form submission is made.

No fields need to be configured in the Marketo form to sync the attributes from the Matrix fields. You can manage all the form fields on the custom form asset in Matrix.

Connection details

Marketo bridge asset

Select the Marketo bridge to use as the integration point for the form submission action. For this submission action to work, the Pod URL and Munchkin account ID values must be set on the Marketo bridge.

Include munchkin cookie

If enabled, the form will try and send the value of the _mkt_trk cookie (if available on the frontend) and the form submission POST request to Marketo. This feature is useful if you want to link the form submission in Marketo with the munchkin user in Marketo. For more information about the Munchkin functionality, please refer to the developer documentation on the Marketo website.

Marketo form ID

The ID of the form in Marketo. For example, if the Marketo form’s embed code has a value of mktoform_48, the form’s ID is 48.

Submission referrer

The URL of the page on which the user submitted the form. By default, this is populated with %globals_asset_URL%%globals_server_query_string^prepend_if:?%. This default ensures that the URL and any query strings present will be included in the Marketo submission.

Attribute sync settings

This section lets you configure which attributes to send over to the Marketo form. You can either send values submitted to the various form fields of the custom form or use other global keywords to source values.

marketo submit form attributes
These fields do not require you to have the attributes set up as form fields in your Marketo form to sync them.

Run database query

The Run database query submission action performs a database query upon submission. To add this action:

  1. Select the Create a new action of type checkbox in the Add new action section.

  2. Select Run database query in the list provided.

  3. Select Save.

The action is added to the existing actions section.

Additional fields also appear in the selected action section.

The fields available in this section are as follows:

Action name

This is the name of the action that you have added. By default, it is set to Send email. This name appears in the Action name/type field in the existing actions section.

Database details

This section allows you to enter the connection details for the database. Select either Specify database details, Use a complete DSN, or Use the contents of a DB connector asset. If you use a DB connector asset the sign-in details entered into the section below are ignored. For more information on the DB connector asset, refer to the Data manual.

Login details

Enter the user name and password for the database.

SQL query

Enter the SQL query to be executed when a user submits the custom form. You can use keyword replacements to expose content from the submission within the SQL query, such as the user’s responses on the form, for example:

Insert into demotable values (%response_100_q1%, %response_100_q2%)

The keyword replacements available for use within the SQL query are the same as those available on the thank you bodycopy. For more information, refer to the Formatting the custom form chapter in this manual.

Select Save once you have entered this information. The submission action will be marked as valid in the existing actions section.

Save as XML

The save as XML submission action exports form submissions as an XML structure.

To add this action:

  1. Select the Create a new action of type box in the Add new action section.

  2. Select Save as XML in the list provided.

  3. Select Save.

The action is added to the existing actions section.

Additional fields also appear in the selected action section. The fields available in this section are as follows:

Action name

This is the name of the action that you have added. By default, it is set to Save as XML. This name appears in the action name/type field in the existing actions section.

Location

Enter a server file path as a destination for the saved XML files. A location must be specified for the submission action to work.

XML detail

Select whether the detail of the XML file will be simple or complex. Complex XML files include user’s IP addresses and asset ID details. By default, this is set to Simple.

XML value to store

Select whether the exported files will contain form answers in either key or value components. By default, this is set to Values.

Sort answers

Select this option to list submission details on the saved XML file in the order specified on the form. If this option is not selected, submission details will be listed based on the form questions' asset IDs.

Send email

The send email submission action sends an email upon submission.

To add this action:

  1. Select the Create a new action of type box in the Add new action section.

  2. Select Send email in the list provided.

  3. Select Save.

The action is added to the existing actions section.

Additional fields also appear in the selected action section.

The fields available in this section are as follows:

Action name

This is the name of the action that you have added. By default, it is set to Send email. This name appears in the Action name/type field in the existing actions section.

To

Enter the email address of a person who should receive the email. You can enter their email address in the text fields or select their user account in the asset finder field.

From

Enter the email address that will appear in the From field in the email.

Reply-to

Enter the email address to which a user will reply. If no reply-to address is configured, the header will not be sent on the email. If you have a field where the user has supplied their email address, use the corresponding response keyword replacement in this field to use this as the reply-to address. This configuration allows the recipient of the email to respond to the user who submitted the form directly.

Subject

Enter the text to be used as the subject of the recipient email. You can use keyword replacements for the responses to the questions the user entered on the form.

Attachments

Check the Include file attachments box to attach the files uploaded through a File upload field type to this email. The Attach to emails option on the Details screen of the file uploaded field must be set to Yes.

Body

Enter the body of the email. You can enter either the text or HTML version of the email in this field. Click on the edit icon to edit the HTML version. A WYSIWYG editor will appear. You can use the keyword replacements for the responses to the questions the user entered on the form within the email body. Along with these keyword replacements, you can also use the following:

%form_info%

This will show information about the custom form, including the asset ID, name and URL of the form, and the name and asset ID of the site.

%form_summary%

This will show the responses that the user entered on the form.

Once you have entered this information, select Save The submission action will be marked as valid in the existing actions section.

Set session variable

The Set session var submission action sets session variables from form submissions.

To add this action:

  1. Check the box Create a new action of type in the add new action section.

  2. Select Set session var in the list provided.

  3. Select Save.

The action is added to the existing actions section.

Additional fields also appear in the selected action section.

The fields available in this section are as follows:

Action name

This is the name of the action that you have added. By default, it is set to set session var. This name appears in the Action name/type field in the existing actions section.

Variable name

Enter the name of the variable in this field. This name can be used within the %global_session_<variable>% keyword replacement to display the session variable’s value.

Set value

Enter the value of the session variable in this field. Keyword replacements can be used in this field.

Once you have done this, select Save.

The submission action will be marked as valid in the existing actions section. The session variable will display the set value for the last submitted form.

For example: Assume a session variable is created with a variable name of IP and a set value of %form_submission_ip_address%. Using the keyword replacement %globals_session_ip% will display the IP address of the user who completed the most recent form submission.

Submit HPRM record & submit TRIM record

The submit TRIM record submission action submits form submissions as TRIM records.

To add this action:

  1. Check the Create a new action of type option in the add new action section.

  2. Select Create TRIM record.

  3. Select Save.

The action is added to the existing actions section.

Additional fields also appear in the selected action section.

For more information on the submit TRIM record action, refer to the Using a custom form to create TRIM records example in the TRIM manual.

Upload YouTube video

The upload YouTube video submission action uploads a submitted video file to YouTube. To add this action:

  1. Check the Create a new action of type box in the Add new action section.

  2. Select Upload YouTube video in the list provided.

  3. Select Save.

The action is added to the existing actions section.

Additional fields also appear in the selected action section.

The action name field displays the name of the action you have added. By default, this will be set to Upload video file. This name appears in the Action name/type field in the existing actions section.

Client credentials

This section allows you to authenticate your Matrix system to access the YouTube API.

To authorize your system, you will need to register your system’s root URL with Google. For more information, visit the Registration for web-based applications documentation. Please note that you will also need a YouTube-linked Google account for the authorization process.

The field available in this section is:

Oauth2 token asset

Matrix requires an Oauth2 token asset to be created to authenticate requests to the YouTube Data API.

YouTube video setup

The section defines the settings of the uploaded YouTube videos. The fields available in this section are as follows:

Privacy

Specify the privacy setting of the YouTube video. The options available are Public, Private, and Unlisted. This setting will determine who can view your video on YouTube.

Title

The title of the YouTube video. You can set a default value for this field in the video settings column. You can also specify a form question in the form question ID column to use a response on the form submission as the title value of the YouTube video.

Description

The description of the YouTube video. You can set a default value for this field in the video settings column. You can also specify a form question in the form question ID column to use a response on the form submission as the description value of the YouTube video.

Category

The category of the YouTube video. You can set a default value for this field in the video settings column. You can also specify a form question in the form question ID column to use a response on the form submission as the category value of the YouTube video. For more information on the available categories, view the YouTube category list documentation.

Video source

The source of the video to upload to YouTube. This field will be a File upload form field on the custom form.

Delete video from server?

Select whether to delete the temporary video files on the Matrix server, once uploaded to YouTube. Please note that this setting will only apply when a create location is not specified for the file upload form question. By default, this field is set to Yes.

Video upload timeout (sec)

Enter the amount of time (in seconds) that Matrix will attempt to upload the video file to YouTube before returning an error. By default, this field is set to 300 seconds.

Keyword replacements are available for use on the thank you bodycopy to print information of YouTube videos uploaded using the upload YouTube video submission action. Read the Keyword replacements documentation for links to more information about the bodycopy options available.