Request From Web Form

A simple web form to send data to OpenEndpoints could look like this:

<form method="post" action="[path-to-endpoint]">
  <!-- include the "hash" param as a separate hidden field, or simply as GET parameter in the form-action -->
  <input type="hidden" name="hash" value="the-calculated-sha256-hash-code" />

  <!-- this can be "live" or "preview". If param is missing, default is "live". -->
  <input type="hidden" name="environment" value="preview" />

  <!-- only required to activate debug-mode -->
  <input type="hidden" name="debug" value="true" />

  <!-- name-attributes for web inputs = endpoint parameters -->
  <input type="..." name="firstname" /> <input type="..." name="lastname" />
  <input type="..." name="email" />

  <input type="submit" value="Send Request" />
</form>

What shall happen after submit?

The form calls your endpoint, which might for example

• use an Email Task to forward an email to your back office, and also send a custom message to the email-address submitted with the form.

• use an HttpRequest Task to send data to your CRM.

The behaviour of your web form after pressing the submit button depends on both the actions defined in your endpoint (success and error actions), and the html code in your web form.

Option 1: Redirect to Success-Page / Error-Page

Configure your endpoint to redirect the request to a success or error page - see Endpoint to Redirect Request. Note that the absolute path to your page must be used, not a relative path.

<endpoint name="foo">
    <success>
        <redirect-to>https://myserver.com/path-to-success-page.html</redirect-to>
    </success>
    <error>
        <redirect-to>https://myserver.com/path-to-error-page.html</redirect-to>
    </error>
</endpoint>

On success (but not on error) you may use parameter placeholders. For example, you could add tracking information that is executed by your success page.

<success>
  <redirect-to>https://myserver.com/page.php?something=${foo}</redirect-to>
</success>

Option 2: Return HTTP-Status

Omitting a particular action on success or failure will simply return a status code of 200 for success or 400 for any type of failure.

<endpoint name="foo">
    <success/>
    <error/>
</endpoint>

Option 3: Return Custom JSON

If you want to return a user-defined JSON, then use a data source transformation to create that JSON using XSLT. For example, the JSON could contain some ID returned from your CRM (see: Intermediate Values):

{ "status": "ok", "customer-id": "12345" }

Use an Endpoint to Return XSLT Transformation:

<endpoint name="foo">
    <success>
        <response-transformation name="custom-json"/>
    </success>
</endpoint>

To output JSON, the XSLT should use the output method "text":

<xsl:output method="text"/>

The transformer should explicitly define the content type "application/json":

<transformer data-source="[name-of-data-source]">
    <xslt-file name="[path-to-xslt]"/>
    <content-type type="application/json"/>
</transformer>

Option 4: Download Document

In case you use an Endpoint to Return XSLT Transformation having a download-filename attribute, the user will stay on the form, while the document is downloaded:

<endpoint name="foo">
    <success>
        <response-transformation name="custom-document" download-filename="my-document.doc"/>
    </success>
</endpoint>

Form Inputs vs Endpoint Parameters

The form entries are passed to the endpoint parameters. Depending on whether these parameters have a default value and whether a Parameter Transformation is used, different things must be observed:

Option 1: Endpoint With Parameter Transformation

• The name attributes in the web form can be completely different from the names of the endpoint parameters.

• The parameter-transformation-xslt may only output parameter values of parameters that are declared in the endpoints.xml file. There are no restrictions as to how inputs from the web form are mapped with this output.

• The output generated by your XSLT requires values for any parameter not having a default value. Not doing so will raise an error.

Option 2: Endpoint Without Parameter Transformation

• Input from the web form is passed to endpoint parameters only if the name attribute in the web form matches the name attribute of the endpoint parameter. Note that names are case sensitive.

• Parameters without a default value must have an equivalent in the web form. Only parameters for which there is a default value are optional.

• Inputs from web forms for which there is no corresponding parameter are silently ignored.

Potential Source of Error

OpenEndpoints parameter names are case sensitive. For example, if the name of the parameter is "firstname", then it will not match with "Firstname".