The entire configuration of an application that is built with OpenEndpoints consists of files in a directory - we refer to this as the Application Directory.

An example directory structure is available on Github (public repository):

For each configuration file or directory, additional explanations are available in the subsections of this page.

Note that https://github.com/OpenEndpoints/xsd is not a working example application. The aim of the example directory is to present the expected syntax and directory structure.

Application loaded from Git

The application directory resides in your own Git repository. There are 2 Deployment Modes:

• Multi Application Mode (=default): The Service Portal provides a simple user interface to "publish" the latest version from Git into the software. An integrity check with meaningful error messages is carried out automatically. Most configuration errors are detected in this way.

• Single Application Mode: You create a new Docker image derived from the standard Docker image, which includes the application directory. You need to build a new Docker image each time your configuration has changed.

The multi-application mode also offers the possibility of simple staging - see Environments.

Expected XML sometimes less strict than XSD

The software is a little less strict than what is written in the XSD: Don’t be surprised if you find working examples where the order of elements is slightly different from what is described in the XSD.

Additional files silently ignored

Any additional files which are present in the application directory, but not required by the software, are silently ignored. For example, if you create an additional directory "project files" that will be ignored by the software without raising an error.

Minimum configuration requirement

Many configuration files are only required if the corresponding features are used.

In any case, these few files must be present for a working configuration:

• endpoints.xml having at least 1 endpoint

• security.xml having at least 1 secret key

• at least one transformer, which as a matter of facts also requires a data-source

The optional directory data-source-post-processing contains custom XSLT files.

See: Directory: data-source-post-processing.

Transformation Input

The root tag of the input xml (which is automatically provided by the software) is <data-source-post-processing-input>. Within that root tag OpenEndpoints will insert the data converted from the data-source-definition or - if applicable - the output from a previous data-source-post-processing step.

Transformation Output

The root tag of the output (=the file that is generated by your XSLT) must be <data-source-post-processing-output>.

The optional xml-from-application directory contains custom xml files that may be used as a data-source. There are no restrictions on how these files should be structured.

The idea behind locally stored content is to avoid unnecessary data load if content doesn't change often.

The optional directory data-source-xslt contains custom xslt files.

Each transformer references to a data-source, which can be transformed to any output having some custom data-source-xslt file.

See: Data Source Transformation

Transformation Input

The data-source will generate a file with a root tag <transformation-input> comprising of all content generated by the data-sources.

OpenEndpoints can interact with third party REST or SOAP APIs, either using such API as a data-source, or to execute a TASK.

The request body of such request can be either inline content (=directly written into endpoints.xml or into the data-source definition), or the body is generated by XSLT transformation.

This optional directory contains custom xslt to generate such request bodies.

The transformation input (=the XML generated by the software, which the XSLT is applied to) does not support arbitrary data-sources, but is limited to parameter values:

The values of the parameters inside that generated xml are different depending on the context:

Request Body Within Parameter Transformation

The input xml contains the parameters from the original request. Note that the original request could have different parameters than those declared in the endpoints.xml - which is possible when parameter transformation is used.

Request Body Within Data-Source or Task

HTTP requests that are part of a regular data-source definition or a task have the same parameters and parameter values in the input xml for generating a request body that are declared in endpoints.xml and whose values can be different after a parameter transformation than in the original request.

The mandatory file security.xml under the application directory comprises of one or many secret keys, which are used to calculate hash keys. See: Authentication

The optional file email-sending-configuration.xml under the application directory is required if emails are to be sent from OpenEndpoints.

OpenEndpoints supports two options for sending emails:

• Sending via SMTP

• Sending via MX address

For further details about how to send emails see: Email Task

The optionalstatic directory can be used to store any non-XML local content, for example images and prefabricated PDF. You may use subdirectories.

Images in PDF

On inserting images into PDF, the static directory serves as the local root path to the XSLT processor. So you can either use an absolute path (URL) or a relative (local) path that refers to this directory.

Images in Email Body

If the email-body has a content type like text/html; charset=utf-8 then it may include tags such as <img src="cid:foo/bar.jpg">. The tag is most commonly an <img>, but can be any tag. The system then searches in the static directory for any file with that path. The file is included with the image, as a “related” multi-part part, meaning the file is available to the HTML document as an "inline image" when its rendered in the email client. Don't forget the cid: text in the src attribute!

Return Static Files

Instead of returning content from XSLT transformation, you may also return “prefabricated” content from this directory. The syntax <response-from-static filename="path-to-file"/> returns a file from this directory.

The optional file service-portal-endpoint-menu-items.xml enables the creation of additional, user-defined pages in the service portal.

Pages of type form and content can be optionally organized under a menu-folder. The maximum supported depth of menu items is one.

Form

The form consists of two pages: the "form" to enter data, and the "result" of the form submit. Both pages are defined by a transformer returning an HTML page with mime-type application/html.

The "form" (=the page returned by calling the form-endpoint) may contain form elements, but without a <form> tag and without a submit button. The form data are submitted to the result-endpoint.

Content

The content consists of a single page defined by a transformer returning an HTML page with mime-type application/html.

You can embed custom fonts into your generated PDF.

In order for custom fonts to be embedded in a PDF, 2 steps must be set:

1. Upload the TTF files into the fonts directory. Only TTF fonts are supported.

2. Declare those fonts in the file apache-fop-config.xsd.

apache-fop-config.xml

Every combination of style and weight of a font must be declared as a font triplet in file apache-fop-config.xml:

Note that the file-name of the TTF font may be different from the name as used in the font-triplet attribute. The font-name as referred to in the XSLT must be the same as in the font-triplet name attribute (case sensitive).

The mandatory directory data-sources contains data-source definitions. A data-source-definition contains references to one or many data-sources, which you would like to load data from and convert to output using a transformer.

See: Data-Source.

The mandatory file endpoints.xml under the application directory comprises of one or many endpoint folders, each of which contains of

• one or many endpoint definitions

• zero or many Endpoint Parameter

Endpoint Folders

The root tag of the file is <endpoint-folder>. A simple endpoints.xml might have a single <endpoint-folder> only (in this case it is the root tag itself). But it is also possible to create a hierarchy of endpoint-folders:

Parameters may be defined at any level. If they are defined in an Endpoint they only apply to that Endpoint. If they are are defined in a folder they apply to all Endpoints under that folder.

Settings in the child folder will override the parent settings.

<endpoint-folder multiple-value-separator=";">
    <parameter name="foo"/>
    <parameter name="xyz" default-value="hello world"/>

    <endpoint name="my-action-1">
    ...
    </endpoint>

    <endpoint-folder>
        <endpoint name="my-action-2">
        ...
        </endpoint>
    <endpoint-folder>
</endpoint-folder>

Parameters

Parameters require to have a name attribute, which is unique within the endpoint-folder. The default value is optional, but using will change the behaviour of the application. See Endpoint Parameter.

Note that a GET or POST request allows multiple parameters with the same name. For example, a web form might have 2 or more form fields with the same name attribute. In contrast to this, the name attributes of the endpoint parameter must be unique. As a consequence - if parameter names are used multiple times in GET or POST requests - several values would be transferred for the same endpoint parameter. The solution is to separate multiple parameter values with a separator. The default separator is a double pipe ||. The attribute multiple-value-separator allows to define an alternative separator.

Endpoint

The basic syntax of any endpoint is:

<endpoint name="some-name-unique-within-same-application">
    <! -- optional: parameter-transformation -->
    <parameter-transformation xslt="path-to-xslt">
        <! -- optional: zero or many data-sources -->
    </parameter-transformation>

    <! -- optional: additional authentication requirements -->
    <include-in-hash> ... </include-in-hash>

    <! -- type of action unless an error was raised  -->
    <success> ... </success>

    <! -- type of action if an error was raised  -->
    <error> ... </error>

    <! -- optional: zero or many tasks to be executed after success-action has been executed -->
    <task class="xyz">...</task>
</endpoint>

Details for each property can be found in the related sections of this documentation:

• Parameter Transformation allows to optionally transform submitted parameter values, for example to validate, normalize or correct submitted values or to create new parameters by calculation or by loading additional data from any data source.

• Include-In-Hash Use Cases allows for advanced authentication requirements based on parameter values.

• Section Types of Endpoints describes all action types for <success> and <error>.

• Tasks include actions such as sending an email, sending a request to any kind of REST-API or logging data into a database.

This optional directory contains custom XSLT for .

Parameter Transformation Input

If an endpoint uses the parameter transformation, OpenEndpoints automatically generates the temporary XML parameter-transformation-input.xml, which is the input for the transformation. This is (unless debug is enabled) only stored in memory, and never written to disk. Depending on how data are submitted to the endpoint, the input XML might look slightly different.

• In case input was submitted as GET request or POST request containing parameters, the generated parameter-transformation-input.xml will include submitted parameters.

• In case data are submitted as a POST Request with application type application/xml, the input-from-request tag contains the XML request body instead of parameters.

• In case data are submitted as a POST Request with application type application/json, the input-from-request tag contains the json request body converted to xml:

Parameter Transformation Output

The expected output (generated by your custom xslt) requires values for any parameter not having a default value. Not doing so will raise an error. In addition the output might have an error tag. If present, an error will be raised an the text within the error tag will be available with the system parameter ${parameter-transformation-error-text}.

The mandatorytransformers directory contains one or many transformers defining a Data Source Transformation.

The only mandatory attribute is the data-source. Omitting all other tags will output the original data-source (xml) without any transformation.