With a task you can

Each <task> is a set of commands embedded into an endpoint-definition in the endpoints.xml:

<endpoint name="foo">
    <success>...</success>
    <error>...</error>
    <!-- zero or many tasks -->
    <task class="...">
       ...
    </task>
    <task class="...">
       ...
    </task>
</endpoint>

Parallel or Subsequent Execution of Tasks

Intermediate Values

To send an email from OpenEndpoints you need to

1. Configure your email server

2. Create an email task

Configure Email Server

To send email from your application the file "email-sending-configuration.xml" must be present under application.

<email-sending-configuration>
    <server>hostname-to-connect-to</server>
    <!--optional-->
    <port>xxxx</port>
    <!--optional-->
    <username>xxxx</username>
    <password>xxxx</password>
    <!--optional: zero or many -->
    <header name='foo'>some-value</header>
</email-sending-configuration>

The file has the root element <email-sending-configuration> and have the following sets of sub-elements.

• If no username and password are set, TLS will not be used

• extra headers are written into every email sent via SMTP, for example authorization headers for a commercial email sending service

Any of the fields (apart from the header names) may use ${foo} parameters.

Alternative Set-Up:

An alternative option is to configure an MX address for the DNS lookup.

<email-sending-configuration>
    <mx-address>an address for MX DNS lookup.</mx-address>
</email-sending-configuration>

Create Email Task

The task <task class="endpoints.task.EmailTask"> sends an email. It has the following sub-elements configuring it:

<task class="endpoints.task.EmailTask">
    <from>me@my-email.com</from>
    <to>${client-email}</to>
    <subject>Message from OpenEndpoints</subject>
    <!-- one or many; "many" will create an multipart/alternative email part -->
    <body-transformation name="a-transformation-generating-text-or-html"/>
    <!-- zero or many -->
    <attachment-static filename="path-to-file-in-static"/>
    <!-- zero or many -->
    <attachment-transformation name="a-transformation" filename="invoice-${invoice-number}.pdf"/>
    <!-- zero or many -->
    <attachment-ooxml-parameter-expansion source="foo.docx" filename="invoice-${invoice-number}.pdf"/>
    <!-- zero or one -->
    <attachments-from-request-file-uploads/>
</task>

• <from> is mandatory (variables are expanded)

• <to> is mandatory (variables are expanded). There may be multiple <to> elements. Each <to> sends a separate email, to just this recipient. Per <to>, only one recipient address is allowed

• <subject> is mandatory (variables are expanded)

• <body-transformation name="a-transformation"/> is mandatory, and can appear multiple times. This references a transformation (see below). All the different results are placed into a ”multipart/alternative” email part. It would be normal for one referenced transformation to produce HTML and the other plain text.

• <attachment-static filename="path/foo.pdf"> takes the foo.pdf file out of the static directory and includes it as an attachment in the email. Variables are not allowed in the filename attribute.

• <attachment-transformation name="a-transformation" filename="invoice-${invoice-number}.pdf"/>. For each of the elements, the transformation is executed, and the resulting bytes are attached as a file to the sent email. The name of the file is specified in the filename attribute, variables are expanded.

• <attachment-ooxml-parameter-expansion source="foo.docx" filename="invoice-${invoice-number}.pdf"/> will read in the file “foo.docx” from the “ooxml-responses” directory under the Endpoint's configuration and replace any ${foo} variables in the document's body, and deliver it. Only DOCX is supported; DOC is not supported. The name of the file is specified in the filename attribute, parameters like ${foo} are expanded.

• <attachments-from-request-file-uploads/>. This includes as attachments all file uploads that have been uploaded to this request. Any attachment may (optionally) have attributes such as if="${foo}" equals="bar".

Embedding Images

If the 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 when its rendered in the email client.

Some email programs may have issues with long links. Links to endpoints (containing all parameters) may get long, so this can become a problem.

The “Short Link To Endpoint” feature allows shorter links to endpoints (including all parameters) to be created. This is analogous to Forwarding Between Endpoints, with the exception that rather than the destination endpoint getting executed immediately, a link is created to the processing of that endpoint.

The task creates a short-link in the database with a random code. The resulting full link, including the code and also including the base URL of the current installation of Endpoints.

The short link looks like this: [base-url]/shortlink/RANDOMCODE.

The generated link is written to an output intermediate variable. The concept of intermediate valriables is described here: Intermediate Values.

The shortlink will be auto-deleted in the database after the time specified in expires-in-minutes. For example, if you put expires-in-minutes="1440" then the link will be available for 1 day. After that time the link will not work any longer.

Use a syntax like the following to create a short link to an endpoint in the variable ${foo}. (You can choose any other variable name, of course).

<task id="create-link"
      class="endpoints.task.CreateShortLinkToEndpointTask"
      destination-endpoint-name="test"
      output-intermediate-value="foo"
      expires-in-minutes="1440"/>

The variable ${foo} can then be used as an input-intermediate-value in a subsequent task.

For example, you can send an email containing ${foo} in the email-body. The xslt (to create the email-body) would look like this:

<a>
  <xsl:attribute name="href" select="transformation-input/parameters/intermediate-value[@name eq 'foo']/@value"/>
  <xsl:text>Short Link</xsl:text>
</a>

You can add custom key/value pairs to your request-log.

For example, if you want to add the "country" submitted in your contact workflow to your request log, you simply create a parameter ${country} and add this task to your endpoint:

<task class="endpoints.task.RequestLogExpressionCaptureTask" key="Country" value="${county}" />

If an endpoint is forwarding the request to another endpoint, then the initial "parent" endpoint will remain the only entry in the log. However, you can add key/value pairs to this "parent" log entry in each subsequent step.

Any task can be made conditional, that means the task will only be executed if some parameter value matches a condition.

<task class="..." if="${foo}" equals="true">
    ...
<task>

The current set of operators supported are:

• if="..." equals="..."

• if="..." notequals="..."

• if="..." isempty="true"

• if="..." hasmultiple="true"

• if="..." gt="..."

• if="..." ge="..."

• if="..." lt="..."

• if="..." le="..."

Note the syntax of the if condition: Either side can use parameter placeholder.

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.

For the gt, ge, lt, le operators the comparison values will be treated as numbers (decimal). If either side are empty or not parseable as a number, the comparison is false.

The right hand side of isempty and hasmultiple can be true or false.

Offer-Ready uses multiple cores, if available. If not specified otherwise, tasks are executed in parallel and will be finished in an arbitrary order.

Paralell execution of primary action and tasks

Note that - as a default - the primary task (data transformation) and all tasks are executed in parallel.

Therefore if one HTTP request depends on another previous one having completed first, that will not work without declaring this dependency.

You may optionally assign an id attribute to the task element:

<task class="endpoints.task.HttpRequestTask" id="foo">
  ...
</task>

You may insert an element <after task-id="..."/> into any task that needs to be executed after foo…

<task class="endpoints.task.HttpRequestTask">
    <after task-id="foo"/>
    ...
</task>

Note that on using Intermediate Values the software will automatically determine the order of execution such that intermediate outputs are created before they are required as inputs. Intermediate values and “after” elements can be used in parallel.