External Request Endpoint

Follow

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

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. All examples will use HTML form elements.

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.

Action Parameters

Action parameters are used to tell Aeon what we're doing, in this case creating requests through the ERE. These parameters must be query string parameters and must have the values given in the table below. Because of this, all of our examples will POST to http://localhost/aeon/aeon.dll?Action=11&Type=200.

Name Required Value Data Type

Notes

Action Yes 11 Integer The Action parameter must be included in the query string and must have a value of 11, which indicates a submission (POST).
Type Yes 200 Integer The Type parameter must be included in the query string and must have a value of 200, which indicates external requests.

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.

Name Notes
SystemID

This is the only request field that is required by the ERE and documents which RA submitted the requests. RAs should choose a consistent value that uniquely identifies their application.

ActivityID The activity a request is associated with cannot be set directly. Instead, use the ForActivity special parameter described in the Special Request Parameters section.
CancelNote This is only set as part of the Aeon Client request cancellation process.
CreationDate This is set by Aeon when the request is created.
InvoiceNumber This is set by Aeon as part of the billing process.
PhotoduplicationDate This is set by Aeon to the current UTC date when a request's photoduplication status is changed.
PhotoduplicationStatus This is set by Aeon during the normal Aeon workflow or when routed.
ReasonForCancellation This is only set as part of the Aeon Client request cancellation proeess.
ResearcherUsername The researcher a request is associated with cannot be set directly. Instead, use the ForResearcher special parameter described in the Special Request Parameters section.
TransactionDate This is set by Aeon to the current UTC date when a request's transaction status is changed.
TransactionNumber This is set by Aeon when the request is created.
TransactionStatus This is set by Aeon during the normal Aeon workflow or when routed.
Username This is set by Aeon when the request is created.

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 action parameters.

Example 1
<form action="http://localhost/aeon/aeon.dll?Action=11&Type=200" method="post">
	<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" value="Submit External 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. 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.

Example 2
<form action="http://localhost/aeon/aeon.dll?Action=11&Type=200" method="post">
	<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" value="Submit External 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.

Example 3
<form action="http://localhost/aeon/aeon.dll?Action=11&Type=200" method="post">
	<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" value="Submit External 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.

Example 4
<form action="http://localhost/aeon/aeon.dll?Action=11&Type=200" method="post">
	<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" value="Submit External 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.

Name Required Default DataType Notes
RequestType No Loan Loan/Copy This controls whether the request will be treated as a reading room request (Loan) or a photoduplication request (Copy). Photoduplication requests will be given a photoduplication status. This field is only relevant if the request is being submitted for processing and will be ignored otherwise.
UserReview No Yes Yes/No

When this value is No, the request will be submitted for processing. Otherwise, it will be left in Awaiting User Review.

ForResearcher No None String The username of the researcher this request will be associated with. If both ForResearcher and ForActivity are used, ForActivity will take precedence. A request may not be associated with both a researcher and an activity.
ForActivity No None Integer The ID of the activity this request will be associated with. If both ForResearcher and ForActivity are used, ForActivity will take precedence. A request may not be associated with both a researcher and an activity.

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.

Name Required Default DataType Notes
ReturnLinkUrl No None URL When provided, a link will be included on the User Review page that will allow the user to return to the referring application.
ReturnLinkUrlTimeout No 0 Integer When a value greater than zero is provided, this parameter specifies the number of seconds before the User Review page will automatically redirect the user back to the ReturnLinkUrl.
ReturnLinkSystemName No "external site" String When provided, this parameter may be used in tag replacements when generating the link back to the consuming application.

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.

URL_Ver rfr_id AeonAction AeonFieldName OpenURLFieldValues AeonValue
Default Aeon Docs Example Replace ItemVolume <#volume> NULL

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

Submitted for User Review

Any requests that are submitted for review (The UserReview parameter is set to Yes or not supplied) will be left in the Awaiting User Review status and will not be validated or routed.

Submitted for Processing by Staff

If the UserReview parameter is set to No and the RequestType parameter is set to Loan or not supplied, the request will be created, validated using WebValidation rules, and routed to Awaiting Request Processing, Awaiting Activity Processing, or Awaiting Future Request Processing based on the request's scheduled date and activity association.

Submitted for Photoduplication

If the UserReview parameter is set to No and the RequestType parameter is set to Copy, the request will be created, validated using WebValidation rules, and routed to a transaction status of Submitted by User and a photoduplication status of Awaiting Order Submittal, although these statuses could vary depending on the user's billing category. Additionally, when submitting a photoduplication request, the ScheduledDate parameter is ignored.

What Could Go Wrong?

Web Session Does Not Exist or is Expired

Most of the Aeon web pages require a user to be logged in. If an active session is not found, the user will be sent to the logon page. Once they've logged in, Aeon will process the external requests.

Web Validation Fails

The external request submission process starts by creating the requests with the provided data and then, if they are being submitted for processing, applies the relevant business logic to the newly-created requests, such as routing them to the appropriate queue. These steps include the requests being validated based on the WebValidation rules and confirming that the requests will not exceed the user's request limit. Any requests that fail these checks will be left in the Awaiting User Review status so that the user can correct and resubmit them.

Blocked or Disavowed User

If the user submitting the requests has been blocked or disavowed by staff, they will be prevented from logging in and will be shown an appropriate status line message.

 

0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.