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.
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.
Potential Source of Error
Make sure that the filename does not contain empty characters, because this will raise an error.
Endpoint to Redirect Request
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.
<endpoint name="foo">
<success>
<redirect-to>${my-destination}</redirect-to>
<!-- optional zero or many prefeix whitlist entrie -->
<redirect-prefix-whitelist-entry>http://www.mywebsite.com</redirect-prefix-whitelist-entry>
<redirect-prefix-whitelist-entry>http://docs.mywebsite.com</redirect-prefix-whitelist-entry>
</success>
</endpoint>
Endpoint to Return Content From Url
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.
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.
Potential Source of Error
Make sure that the filename does not contain empty characters, because this will raise an error.
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.
Endpoint to Return XSLT Transformation
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.
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.
Potential Source of Error
The download-filename attribute will raise an error if it contains a blank or a special character. This is because browsers are inconsistent in how they handle download filenames with special characters. In order to create a "write once, works everywhere" experience special characters are not supported.
Error Case
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.
Limited Support of Variables
This limitation not only applies to the use of placeholders in the endpoint-definition, but also for any data-source or XSLT used within a transformation.
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.
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.
Conditional Success Action
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¶m=bar then the equals=".." will check if any of the values match, and notequals=".." will check that none of the values match the value.
Types of Endpoints
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.
<endpoint name="some-name-unique-within-same-application">
<success>
<! -- tag specifying the specific success action -->
</success>
<error>
<! -- tag specifying the specific error action -->
</error>
</endpoint>
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.