In endpoints.xml, <endpoint> has two sub-sections, <success> and <error>. What happens in the case of success or error depends on the tags being present. Details are described in the following subsections.

If the tag (<success> or <error>) is missing, or present and empty, this means the server returns an empty 200 OK in the success case and 400 error in the case of failure. This can be useful if the request should simply perform some tasks e.g. send emails.

This type of syntax specifies that the transformation named in the attribute is performed, and its contents are returned to the client in the HTTP response. For example, the transformation might produce HTML to be displayed in the browser, or a PDF to be downloaded.

Syntax

You can optionally add an attribute "download-filename".

If the download-filename="foo.pdf" attribute is present, then the header in the HTTP response is set indicating that the file should be downloaded as opposed to displayed in the browser window. Parameter values like ${foo} are replaced.

This type of syntax specifies that an HTTP request is performed and the result of this request is streamed back to the client as the response of the call to Endpoints.

Syntax

You can optionally add an attribute "download-filename".

If the download-filename="foo" attribute is present, then the header in the HTTP response is set indicating that the file should be downloaded as opposed to displayed in the browser window. Parameter Values like ${foo} are replaced.

In general <error> supports the same tags as <success>. But there are limitations.

No forward-to-endpoint

Placing <forward-to-endpoint> inside <error> is not supported, as this would require “auto increment” numbers to be assigned even in the case of <error> (as any arbitrary endpoint might be called, which might require them). It is an explicit design goal to only support auto-increment numbers (e.g. for invoice numbers) in the case of <success>.

Limited Support of Variables

On error the same tags can be used as for <success>, but placeholders for client generated parameter values are not supported. An error might have happened during parameter transformation, and therefore client generated parameters are not necessarily available.

System generated parameters may be used.

In addition, for the processing of the <error> tag the following additional parameters are available:

• ${internal-error-text} - This contains an internal error message. It is important this is not exposed to any end customer, as it might contain security-sensitive information such as “cannot connect to database at IP address 1.2.3.4” etc.

• ${parameter-transformation-error-text} - In case the request failed because the parameter transformation failed, and a message was set in the <error> tag in its output.

This feature can be used to download e.g. Word or Excel files.

Only e.g. DOCX and XLSX etc. are supported; old-style DOC and XLS files are not supported.

The body of the document may contain parameter references such as ${foo}, these are expanded to the parameters available through the endpoint processing.

<endpoint name="foo">
    <success>
        <ooxml-parameter-expansion
                source="foo.docx"
                download-filename="bar-${id}.docx"
        />
    </success>
</endpoint>

The endpoint application directory may contain an ooxml-responses directory and within that any referenced files must be present, for example foo.docx in the example above.

This type of syntax specifies that an endpoint "step-1" is executed and on success another endpoint "step-2" will be called.

The result of the original request (i.e. all parameters) is used as the request to the endpoints being forwarded to:

<endpoint name="step-1">
    <success>
        <forward-to-endpoint endpoint-name="step-2"/>
    </success>
</endpoint>

All parameter values are forwarded to the new endpoint.

System parameters such as user agent, client IP address and file uploads are all available at the endpoint forwarded to. They are inherited to the forwarded endpoint.

It’s possible to chain the execution of any number of endpoints in this manner (e.g. endpoint e1 forwards to e2 which itself forwards to e3). A circular chain of such references is not allowed as the processing of such a chain would never end.

The “redirect” from one endpoint to another happens within the Endpoints software; no redirect is actually sent to the user’s browser.

Request Log Behaviour

Only one “request log” gets written, despite a chain of multiple endpoints being processed. Only the first “parameter transformation input/output” is saved with that “request log” entry, despite each endpoint in the chain potentially having its own parameter transformation.

This type of syntax specifies that the response content is fetched from the named file within the static directory. Subdirectories such as filename="sub-dir/file.pdf" are supported.

Variables are not allowed in the filename attribute. This is to prevent accidentally making more files accessible (if the client guesses the right filename) than intended. But you can use Conditional Success Action to deliver different files depending on different parameter values.

<endpoint name="foo">
    <success>
        <response-from-static filename="path-to-file"/>
    </success>
</endpoint>

You can optionally add an attribute "download-filename".

If the download-filename="foo.pdf" attribute is present, then the header in the HTTP response is set indicating that the file should be downloaded as opposed to displayed in the browser window. Parameter Values like ${foo} are replaced.

<endpoint name="foo">
    <success>
        <response-from-static filename="path-to-file" download-filename="my-document.pdf"/>
    </success>
</endpoint>

This type of syntax specifies that a redirect of the request should be performed. The body of the <redirect-to> specifies where. Variables, if present, are replaced, in the body.

For example you can redirect a successful request to a "thank.you.html" url.

Parameters like ${foo} in the body are replaced.

If you use variables, we recommend to use this optional element to prevent a malicious request redirecting somewhere wrong:

If no such tag is present, redirect to any URL is allowed. If one or more are present, the URL being redirected to must start with the prefix of one of them; otherwise this is an error.

Different results may be required for the same endpoint based on certain criteria. It is possible to define any number of success elements such as:

The conditions are considered in the order they’re written in the file, so put more general “catch-all” items at the bottom and more specific “if...” items at the top.

Parameters may also be used in the "equals" or "notequals" attribute. You could for example create a condition like

Only if=".." equals=".." and if=".." notequals=".." are available.

If the parameter has a value like foo||bar i.e. created as a result of a request such as ?param=foo&param=bar then the equals=".." will check if any of the values match, and notequals=".." will check that none of the values match the value.