External Request Endpoint

Creating Aeon Requests Through the External Request Endpoint

The Aeon external request endpoint (ERE) allows users to submit one or more requests directly to Aeon from a third-party web application, which we'll designate as the referring application (RA). This documentation explains the technical details necessary to integrate an RA website with Aeon and contains examples that can be used with minimal modification.

Understanding the Aeon Web Environment | Form Parameters | OpenURL Mapping | What Happens When the Request is Submitted

Understanding the Aeon Web Environment

Atlas Dual Authentication Portal | Web Session and Cookies | Logon Page | Creating a New Account

The Aeon ERE is intended to be used in a web browser environment and is inherently user-centric. Requests are submitted to the Aeon web server via the HTTP POST method and presume a user will be in the loop to interpret and interact with the web pages sent in response. The RA is only responsible for building the initial POST request and doesn't need to worry about Aeon's response. It's the same as if the RA simply had a link to an external resource; any response is expected to be handled by the web browser.

All interaction with the Aeon website goes through the aeon.dll, an ISAPI extension, and define the actions to take by a standard set of query parameters that will be described in detail later. For the examples in this document, we'll treat the Aeon web URL as http://localhost/aeon/aeon.dll. Your actual system URL will differ depending on your hostname and protocol, or if you are using the Atlas Dual Authentication Portal (see the section below). All examples will use HTML form elements.

Atlas Dual Authentication Portal

If you are using the Atlas Dual Authentication Portal to offer RemoteAuth and non-RemoteAuth logon options for your users, then the Aeon web URL should point to the portal's URL, e.g., http://localhost/logon/. As noted above, your actual system URL will differ depending on your hostname and protocol. As the ERE uses the HTTP POST method to submit requests, the Dual Auth Portal will also need to be configured to support POST data handling. For details on configuring POST data handling, see Supporting POST Data.

Web Session and Cookies

The Aeon website requires users to have an account and to authenticate, which will generate a session token. Once a user has been authenticated, their session token will be stored in a cookie named AeonSessionID. The RA is not responsible for this session token. Instead, the RA should rely on the browser to submit the session cookie, if it exists, when POSTing to the ERE and leave the user authentication to Aeon.

Logon Page

If a session token does not exist or has expired, Aeon will respond to the ERE POST with the Aeon logon page. Aeon will continue processing the external request submission once the user has logged in.

Creating a New Account

If the user does not have an Aeon account, they may follow the link from the logon page to create one. Aeon will continue processing the external request submission once the user has submitted their account details.

Form Parameters

This section describes the parameters that are POSTed to the Aeon ERE. Parameters provide the data that will be used to populate the new requests, but they can also affect the manner in which the requests are created.

Request Parameters | Single Requests | Multiple Requests | Global Request Parameters | Special Request Parameters | Return Link Parameters

Request Parameters

Request parameters describe the data that is used to populate the requests being created. In the simplest case, the request parameter name simply corresponds with the request field of the same name. The available requests fields are detailed in the next section. Of these, only SystemID is required by the ERE. However, note that some fields may be required by the Aeon site's validation rules. This is explained further in the Web Validation Fails section.

Request Fields

The current request fields are listed under the Transactions table in the Aeon Database Tables. You may optionally submit values for all of these fields with the following exceptions.

Single Requests

Submitting a single request is the simplest implementation of this feature. We've now covered enough to demonstrate a minimal external request. We will use an HTML form to submit a SystemID, ItemTitle, and ItemAuthor to the aeon.dll with the appropriate hidden inputs for the AeonForm and SubmitButton values.

<form action="http://localhost/aeon/aeon.dll" method="post">
        <input type="hidden" name="AeonForm" value="ExternalRequest">
	<input type="hidden" name="SystemID" value="Aeon Docs Example">
	<input type="hidden" name="ItemTitle" value="Letters of Thomas Jefferson">
	<input type="hidden" name="ItemAuthor" value="Thomas Jefferson">
	<input type="submit" name="SubmitButton" value="Submit Request">
</form>

When testing this example, the response can depend on a few factors. We will likely be sent to the logon page if we don't already have an active session. The request may fail validation (particularly for the Site field, which is required by default but typically removed for single-site configurations), but in that case, the request will still be created and left in the Awaiting User Review status. The possible responses are explained further in the What Happens When the Request is Submitted section.

Multiple Requests

The ERE also allows us to submit multiple requests at once. To do so, we need to be able to differentiate the submitted request parameters so Aeon knows which field value is being set on which request. We do this by using the Request parameter to define each request we're creating. Request is an optional parameter when we're only submitting a single request, but is necessary when submitting multiples. For each request being submitted, we must provide a Request parameter with a unique identifier. This identifier can be any alphanumeric value, but for our examples we'll simply use ascending integers starting at one. The accepted values include colons and hyphens. We then use these identifiers to distinguish request parameters by appending them to the request field names using the convention {RequestFieldName}_{RequestIdentifier}, as demonstrated in the following example.

<form action="http://localhost/aeon/aeon.dll" method="post">
        <input type="hidden" name="AeonForm" value="ExternalRequest">
	<input type="hidden" name="SystemID" value="Aeon Docs Example">
	<input type="hidden" name="Request" value="1">
	<input type="hidden" name="ItemTitle_1" value="Letters of Thomas Jefferson">
	<input type="hidden" name="ItemAuthor_1" value="Thomas Jefferson">
	<input type="hidden" name="Request" value="2">
	<input type="hidden" name="ItemTitle_2" value="The Autobiography of Thomas Jefferson">
	<input type="hidden" name="ItemAuthor_2" value="Thomas Jefferson">
	<input type="submit" name="SubmitButton" value="Submit Request">
</form>    

This example will create two distinct requests. There are two things to note here. First, we are submitting the Request parameter twice, once for each distinct request identifier. Second, the SystemID parameter is only included once. This is a special case; Aeon will not look for SystemID parameters that use the multiple request naming convention and the single SystemID is applied to all requests being created. Parameters being applied to multiple requests is covered further in the section on global request parameters, but SystemID is unique in that you cannot specify different system IDs to different requests.

Global Request Parameters

If we are submitting multiple requests, individual parameters will be applied to each request if they don't use the multiple request naming conventions. This is useful when you want to set the same field to the same value across all of your requests. The following example will produce the same result as Example 2, but will only submit a single ItemAuthor parameter which will be applied to both requests.

<form action="http://localhost/aeon/aeon.dll" method="post">
    <input type="hidden" name="AeonForm" value="ExternalRequest">
    <input type="hidden" name="SystemID" value="Aeon Docs Example">
    <input type="hidden" name="Request" value="1">
    <input type="hidden" name="ItemTitle_1" value="Letters of Thomas Jefferson">
    <input type="hidden" name="Request" value="2">
    <input type="hidden" name="ItemTitle_2" value="The Autobiography of Thomas Jefferson">
    <input type="hidden" name="ItemAuthor" value="Thomas Jefferson">
    <input type="submit" name="SubmitButton" value="Submit Request">
</form>    

This behavior has rules for the specificity of the request parameters. A request parameter that uses the multiple request naming convention will take precedence over a global request parameter. We can build on example 3 by adding a third request that specifies a different author that the ItemAuthor parameter.

<form action="http://localhost/aeon/aeon.dll" method="post">
    <input type="hidden" name="AeonForm" value="ExternalRequest">
    <input type="hidden" name="SystemID" value="Aeon Docs Example">
    <input type="hidden" name="Request" value="1">
    <input type="hidden" name="ItemTitle_1" value="Letters of Thomas Jefferson">
    <input type="hidden" name="Request" value="2">
    <input type="hidden" name="ItemTitle_2" value="The Autobiography of Thomas Jefferson">
    <input type="hidden" name="ItemAuthor" value="Thomas Jefferson">
    <input type="hidden" name="Request" value="3">
    <input type="hidden" name="ItemTitle_3" value="The Letters of John and Abigail Adams">
    <input type="hidden" name="ItemAuthor_3" value="John and Abigail Adams">
    <input type="submit" name="SubmitButton" value="Submit Request">
</form>        

Special Request Parameters

There are some request parameter names that do not match Aeon request fields but do control how a request is treated when it's being created. Like the rest of the request fields, these can be specified for individual requests using the multiple request naming convention or can be applied globally to all requests. The effects of these settings are described in further detail in the What Happens When the Request is Submitted section.

Return Link Parameters

One of the features of the ERE allows us to specify a return link back to our web application. Once Aeon has finished processing and creating the submitted requests, the user will be taken to the ViewUserReviewRequests.html page. If the page has a <#RETURNLINK> tag, it will be replaced with a link back to ReturnLinkUrl. The relevant parameters are as follows.

OpenURL Mapping

When submitting external requests, the names of the request parameters are typically expected to match the names of Aeon request fields. However, we can also specify a mapping between submitted field names and Aeon request fields. When requests are submitted to the ERE, Aeon will use the OpenURLMapping table to map any submitted fields to their corresponding Aeon fields. It does so by looking for replacement rules where the rfr_id field matches the SystemID submitted by the external system and then applying the same logic used in OpenURL requests. For example, if we've chosen "Aeon Docs Example" as our SystemID and wanted to be able to set the ItemVolume field on requests using the field name "volume", we'd add the following row to the OpenURLMapping table.

Mapped fields that are submitted for multiple requests follow the same request naming convention as the default Aeon fields. Using the above example, we could submit parameters named "volume_1", "volume_2", etc, or we could just submit a "volume" parameter that would be applied to all requests. The OpenURL feature is covered in more detail in Submitting Requests via OpenURL.

What Happens When the Request is Submitted

When Things Go Right | What Could Go Wrong?