Code4Lib - User contributions [en]

Umlaut URL parameters

2008-10-27T17:31:55Z

128.220.159.25:

[[Category:Umlaut]]

Umlaut has a few custom URL parameters (can also be sent in a POST request) to control Umlaut behavior. All start with the prefix "umlaut.". These are generally added onto an OpenURL GET request.

===umlaut.request_id===

Specify an already created OpenURL request to act upon. Without this, Umlaut will still try to connect to an already created request *within the same session* based on a cache of OpenURLs seen in that session. But this process is not perfect. With umlaut.request_id, you can assure you are operating on the same request, and even if the client does not have cookies or a session.

===umlaut.referent_id===

Specify an Umlaut Referent object to re-use. Umlaut referent object represents a particular citation. Unlike umlaut.request_id, won't re-use an entire request (with responses and state), but only the specified citation.

===umlaut.skip_resolve_menu===

Set to "false" to override umlaut's configuration for conditionally skipping the the resolve menu and going straight to content. umlaut.skip_resolve_menu=false forces display of full resolve menu.

===umlaut.skip_resolve_menu_for_type===

Set to the name(s) of [http://umlaut.rubyforge.org/svn/trunk/db/orig_fixed_data/service_type_values.yml Umlaut service types] (comma delimited), to force menu skipping (direct linking) for the first response found from any of the service types named.

===umlaut.link_with_frameset===

Set to "false" to force direct linking *without* the banner/frameset, just direct to vendor url.

===umlaut.response_format===

Generally used for API requests, value can be "xml", "json", or "jsonp". In case of jsonp, umlaut.jsonp=jsFunctionName can be used to determine the js function name that will be generated with the [http://ajaxian.com/archives/jsonp-json-with-padding jsonp output]

Umlaut

2008-10-16T19:04:20Z

128.220.159.25: /* More information */

Umlaut is OpenURL link resolving middleware that adds functions and services to commercial link resolving software such as SFX.

[[Category:Umlaut]]

==More information==

[[About Umlaut]] - A gentle introduction to what Umlaut is and what it can do for you.

[http://bibwild.wordpress.com/2008/10/16/umlaut-digital-book/ Digital Text Features] - A tour of some of the 'advanced' digital text features, with a demos pointing to JHU site, hosted on jrochkind's blog.

[http://rubyforge.org/mail/?group_id=4382 Umlaut Listserv]

[http://umlaut.rubyforge.org/ Rubyforge home page for developers]

[[Umlaut wishlist]]

==Installation and Configuration==

[[Umlaut Installation]]

[[Umlaut Setup]]

[[Umlaut_Deployment]]

==Documentation==

===Overview===

[http://umlaut.rubyforge.org/api/ Umlaut API Documentation]

[[Umlaut Technical Overview]]

[[Umlaut_Deployment]]

[[Umlaut Local Configuration Architecture]]

===Specific Topics===

[[Umlaut URL parameters]]

[[Umlaut logging]]

====APIs====

[[Umlaut full API]]

[[Umlaut partial html API]]

[[Umlaut partial html API javascript helper]]

Umlaut partial html API javascript helper

2008-10-02T20:24:24Z

128.220.159.25:

If you want to include Umlaut-generated HTML directly on a third party page via javascript, there is a javascript helper script to make that very easy. This helper uses the [[Umlaut partial html API]], but does everything for you. The helper will update your divs, and keep polling Umlaut for new results, continuing to re-update your divs until Umlaut is finished. How often it polls is configured by application config 'poll_wait_seconds', which defaults to 4 seconds.

== Overview ==

You need to specify your Umlaut base URL in a global javascript variable called umlaut_base. This is not your link resolver base url which for Umlaut ends in /resolve, but the actual Umlaut application base URL, which should be the same, without the /resolve. At JHU, it's "http://findit.library.jhu.edu".

You also need to put a URL-formatted (KEV) OpenURL context object in a global js variable called umlaut_openurl_kev_co.

You then specify mappings from Umlaut html sections to HTML divs on your page in global js variable called umlaut_section_map containing a hash. Umlaut html sections are configured in Umlaut in the "partial_html_map" configuration param, which by default is set to the "bg_update_map" config params :divs key. To see the sections in a default Umlaut installation, see: [http://umlaut.rubyforge.org/svn/trunk/config/environment.rb environment.rb in svn], look for bg_update_map. The :divs key of the hash there is an array of hashes, each individual hash has a :div_id key that corresponds to the html_sections id in this api response. For Umlaut developers, the :partial key tells you what Rails partial is used to generate this section.

You can also optionally use some javascript callbacks to perform behavior after or during loading. In the following example, we'll demo using a javascript callback to only show a div for search_inside functionality if there are search_inside tools provided.

The umlaut_embed.js script will check if the javascript Prototype library is loaded into the host page, and load it if not. Among other things, this means you can use Prototype in your callbacks.

The html loaded will sometimes include a "spinner" with a message "loading more", if the content is not yet loaded.

An example is best:

== Example ==

<pre>

<H1>Here is an article page. </h1>

<p>We're looking up Cytoplasmic Control of nuclear behavior by Masui. Of course normally this
would be dynamically generated, not in static html like this.<p>


<div id="my_fulltext">
<a href="http://umlaut.university.edu/resolve?url_ver=Z39.88-2004&rft_val_fmt=info:ofi/fmt:kev:mtx:journal&rft_id=info:doi/10.1002/jez.1401770202&rfr_id=info:sid/university.edu:myapplication&rft.genre=article&rft.jtitle=J.%20Exp.%20Zool&rft.date=1971&rft.atitle=Cytoplasmic%20control%20of%20nuclear%20behavior&rft.aulast=Masui">
Link to umlaut
</a>
</div>


<div id="my_search_inside" style="display:none;"></div>

<div id="my_cover"></div>

<div id="my_see_also"</div>

<div id="my_excerpts"></div>



<script type="text/javascript">
// You have to generate an OpenURL context object somehow, and set it in a js global var.
// Normally this would be generated dynamically, not static HTML like this, of course.
// You may want to include a rfr_id to identify your application as a source, demo below.

umlaut_openurl_kev_co = 'url_ver=Z39.88-2004&rft_val_fmt=info:ofi/fmt:kev:mtx:journal&rft_id=info:doi/10.1002/jez.1401770202&rfr_id=info:sid/university.edu:myapplication&rft.genre=article&rft.jtitle=J.%20Exp.%20Zool&rft.date=1971&rft.atitle=Cytoplasmic%20control%20of%20nuclear%20behavior&rft.aulast=Masui';

// set global js var to tell script where to find umlaut
umlaut_base = 'http://umlaut.university.edu';

// Map of umlaut section id to: div id we want to put it on the page
// Note the js call back for search_inside_wrapper, to only show the
// div on our page if there are elements. Js callback function gets one
// argument, which will be number of Umlaut responses in the section.
// Note also that we can use Prototype in the callback.

umlaut_section_map = {
'fulltext_wrapper': 'my_fulltext',
'highlighted_links': 'my_see_also',
'excerpts_wrapper': 'my_excerpts',
'cover_image': 'my_cover',
'search_inside_wrapper': {'host_div_id': 'my_search_inside',
'after_update':
function(count) {
if ( count > 0) {
$('my_search_inside').show();
}
}
}
};
</script>


<script type="text/javascript" src="http://umlaut.university.edu/javascripts/embed/umlaut-embed.js"></script>

</pre>

[[Category:Umlaut]]

Umlaut partial html API javascript helper

2008-10-02T20:23:19Z

128.220.159.25:

If you want to include Umlaut-generated HTML directly on a third party page via javascript, there is a javascript helper script to make that very easy. This helper uses the [[Umlaut partial html API]], but does everything for you. The helper will update your divs, and keep polling Umlaut for new results, continuing to re-update your divs until Umlaut is finished. How often it polls is configured by application config 'poll_wait_seconds', which defaults to 4.

== Overview ==

You need to specify your Umlaut base URL in a global javascript variable called umlaut_base. This is not your link resolver base url which for Umlaut ends in /resolve, but the actual Umlaut application base URL, which should be the same, without the /resolve. At JHU, it's "http://findit.library.jhu.edu".

You also need to put a URL-formatted (KEV) OpenURL context object in a global js variable called umlaut_openurl_kev_co.

You then specify mappings from Umlaut html sections to HTML divs on your page in global js variable called umlaut_section_map containing a hash. Umlaut html sections are configured in Umlaut in the "partial_html_map" configuration param, which by default is set to the "bg_update_map" config params :divs key. To see the sections in a default Umlaut installation, see: [http://umlaut.rubyforge.org/svn/trunk/config/environment.rb environment.rb in svn], look for bg_update_map. The :divs key of the hash there is an array of hashes, each individual hash has a :div_id key that corresponds to the html_sections id in this api response. For Umlaut developers, the :partial key tells you what Rails partial is used to generate this section.

You can also optionally use some javascript callbacks to perform behavior after or during loading. In the following example, we'll demo using a javascript callback to only show a div for search_inside functionality if there are search_inside tools provided.

The umlaut_embed.js script will check if the javascript Prototype library is loaded into the host page, and load it if not. Among other things, this means you can use Prototype in your callbacks.

The html loaded will sometimes include a "spinner" with a message "loading more", if the content is not yet loaded.

An example is best:

== Example ==

<pre>

<H1>Here is an article page. </h1>

<p>We're looking up Cytoplasmic Control of nuclear behavior by Masui. Of course normally this
would be dynamically generated, not in static html like this.<p>


<div id="my_fulltext">
<a href="http://umlaut.university.edu/resolve?url_ver=Z39.88-2004&rft_val_fmt=info:ofi/fmt:kev:mtx:journal&rft_id=info:doi/10.1002/jez.1401770202&rfr_id=info:sid/university.edu:myapplication&rft.genre=article&rft.jtitle=J.%20Exp.%20Zool&rft.date=1971&rft.atitle=Cytoplasmic%20control%20of%20nuclear%20behavior&rft.aulast=Masui">
Link to umlaut
</a>
</div>


<div id="my_search_inside" style="display:none;"></div>

<div id="my_cover"></div>

<div id="my_see_also"</div>

<div id="my_excerpts"></div>



<script type="text/javascript">
// You have to generate an OpenURL context object somehow, and set it in a js global var.
// Normally this would be generated dynamically, not static HTML like this, of course.
// You may want to include a rfr_id to identify your application as a source, demo below.

umlaut_openurl_kev_co = 'url_ver=Z39.88-2004&rft_val_fmt=info:ofi/fmt:kev:mtx:journal&rft_id=info:doi/10.1002/jez.1401770202&rfr_id=info:sid/university.edu:myapplication&rft.genre=article&rft.jtitle=J.%20Exp.%20Zool&rft.date=1971&rft.atitle=Cytoplasmic%20control%20of%20nuclear%20behavior&rft.aulast=Masui';

// set global js var to tell script where to find umlaut
umlaut_base = 'http://umlaut.university.edu';

// Map of umlaut section id to: div id we want to put it on the page
// Note the js call back for search_inside_wrapper, to only show the
// div on our page if there are elements. Js callback function gets one
// argument, which will be number of Umlaut responses in the section.
// Note also that we can use Prototype in the callback.

umlaut_section_map = {
'fulltext_wrapper': 'my_fulltext',
'highlighted_links': 'my_see_also',
'excerpts_wrapper': 'my_excerpts',
'cover_image': 'my_cover',
'search_inside_wrapper': {'host_div_id': 'my_search_inside',
'after_update':
function(count) {
if ( count > 0) {
$('my_search_inside').show();
}
}
}
};
</script>


<script type="text/javascript" src="http://umlaut.university.edu/javascripts/embed/umlaut-embed.js"></script>

</pre>

[[Category:Umlaut]]

Umlaut partial html API javascript helper

2008-10-02T19:56:42Z

128.220.159.25:

If you want to include Umlaut-generated HTML directly on a third party page via javascript, there is a javascript helper script to make that very easy. This helper uses the [[Umlaut partial HTML api]], but does everything for you. The helper will update your divs, and keep polling Umlaut for new results, continuing to re-update your divs until Umlaut is finished. How often it polls is configured by application config 'poll_wait_seconds', which defaults to 4.

== Overview ==

You need to specify your Umlaut base URL in a global javascript variable called umlaut_base. This is not your link resolver base url which for Umlaut ends in /resolve, but the actual Umlaut application base URL, which should be the same, without the /resolve. At JHU, it's "http://findit.library.jhu.edu".

You also need to put a URL-formatted (KEV) OpenURL context object in a global js variable called umlaut_openurl_kev_co.

You then specify mappings from Umlaut html sections to HTML divs on your page in global js variable called umlaut_section_map containing a hash. Umlaut html sections are configured in Umlaut in the "partial_html_map" configuration param, which by default is set to the "bg_update_map" config params :divs key. To see the sections in a default Umlaut installation, see: [http://umlaut.rubyforge.org/svn/trunk/config/environment.rb environment.rb in svn], look for bg_update_map. The :divs key of the hash there is an array of hashes, each individual hash has a :div_id key that corresponds to the html_sections id in this api response. For Umlaut developers, the :partial key tells you what Rails partial is used to generate this section.

You can also optionally use some javascript callbacks to perform behavior after or during loading. In the following example, we'll demo using a javascript callback to only show a div for search_inside functionality if there are search_inside tools provided.

The umlaut_embed.js script will check if the javascript Prototype library is loaded into the host page, and load it if not. Among other things, this means you can use Prototype in your callbacks.

The html loaded will sometimes include a "spinner" with a message "loading more", if the content is not yet loaded.

An example is best:

== Example ==

<pre>

<H1>Here is an article page. </h1>

<p>We're looking up Cytoplasmic Control of nuclear behavior by Masui. Of course normally this
would be dynamically generated, not in static html like this.<p>


<div id="my_fulltext">
<a href="http://umlaut.university.edu/resolve?url_ver=Z39.88-2004&rft_val_fmt=info:ofi/fmt:kev:mtx:journal&rft_id=info:doi/10.1002/jez.1401770202&rfr_id=info:sid/university.edu:myapplication&rft.genre=article&rft.jtitle=J.%20Exp.%20Zool&rft.date=1971&rft.atitle=Cytoplasmic%20control%20of%20nuclear%20behavior&rft.aulast=Masui">
Link to umlaut
</a>
</div>


<div id="my_search_inside" style="display:none;"></div>

<div id="my_cover"></div>

<div id="my_see_also"</div>

<div id="my_excerpts"></div>



<script type="text/javascript">
// You have to generate an OpenURL context object somehow, and set it in a js global var.
// Normally this would be generated dynamically, not static HTML like this, of course.
// You may want to include a rfr_id to identify your application as a source, demo below.

umlaut_openurl_kev_co = 'url_ver=Z39.88-2004&rft_val_fmt=info:ofi/fmt:kev:mtx:journal&rft_id=info:doi/10.1002/jez.1401770202&rfr_id=info:sid/university.edu:myapplication&rft.genre=article&rft.jtitle=J.%20Exp.%20Zool&rft.date=1971&rft.atitle=Cytoplasmic%20control%20of%20nuclear%20behavior&rft.aulast=Masui';

// set global js var to tell script where to find umlaut
umlaut_base = 'http://umlaut.university.edu';

// Map of umlaut section id to: div id we want to put it on the page
// Note the js call back for search_inside_wrapper, to only show the
// div on our page if there are elements. Js callback function gets one
// argument, which will be number of Umlaut responses in the section.
// Note also that we can use Prototype in the callback.

umlaut_section_map = {
'fulltext_wrapper': 'my_fulltext',
'highlighted_links': 'my_see_also',
'excerpts_wrapper': 'my_excerpts',
'cover_image': 'my_cover',
'search_inside_wrapper': {'host_div_id': 'my_search_inside',
'after_update':
function(count) {
if ( count > 0) {
$('my_search_inside').show();
}
}
}
};
</script>


<script type="text/javascript" src="http://umlaut.university.edu/javascripts/embed/umlaut-embed.js"></script>

</pre>

[[Category:Umlaut]]

Umlaut partial html API javascript helper

2008-10-02T19:32:55Z

128.220.159.25:

Umlaut full API

2008-10-02T19:28:33Z

128.220.159.25: /* <in_progress> */

Umlaut has a complete api for resolve actions, which can be delivered in XML or json. For simple uses of embedding Umlaut content on a page, you may find the [[Umlaut partial html API]] or [[Umlaut partial html API javascript helper]] easier to use.

[[Category:Umlaut]]

= Accessing the API =

The api can be accessed at the resolve/api action. For instance, if your umlaut is at umlaut.somewhere.edu/, http://umlaut.somewhere.edu/resolve/api?

Append an OpenURL context object to that URL. POST is also supported, including XML formatted context objects. You can also include the usual umlaut directive parameters.

This is exactly what you'd send to the ordinary Umlaut link resolver base url for link resolver service in html; you are just replacing /resolve? with /resolve/api?

By default, the API returns XML. To return json instead, include:

&umlaut.response_format=json

To return jsonp, wrapped in a javascript procedure call:

&umlaut.response_format=jsonp&umlaut.jsonp=desiredJavascriptFunctionName

= API Response =

== <request_id> ==

<pre>
<request_id>701544</request_id>
</pre>

Umlaut's internal request id. API clients usually don't need this, but can be useful if you want a unique identifier for this OpenURL request. May also be useful if you want to call other Umlaut actions on this same OpenURL request, ensuring that Umlaut matches to the same request, by including &umlaut.request_id in your request.

== <context_object_xml> ==

Contains an OpenURL context object in XML serialization. May include enhanced citation metadata from Umlaut.

== <complete> ==

When accessing Umlaut over an API, it's important to realize that the initial response from Umlaut may not include all Umlaut information. Umlaut continues to run services in the background that can generate responses and enhance metadata. <complete> will contain 'true' or 'false' depending on whether background services are still executing. Further elements in the response provide information on what is still executing, and how to retrieve further information.

== <in_progress> ==

'''example''':
<pre>
<in_progress>
<refresh_url>http://findit.library.jhu.edu/resolve/api?umlaut.request_id=701544&.....</refresh_url>
<refresh_url_path>/resolve/api?umlaut.request_id=701544&.....</refresh_url_path>
<requested_wait_seconds>4</requested_wait_seconds>
<services_in_progress>
<service name="fulltext" />
<service name="holding" />
<service name="table_of_contents" />
<service name="highlighted_link" />
<service name="audio" />
<service name="holding_search" />
</services_in_progress>
</in_progress>
</pre>

This block will only be present when <complete> is 'false'.

<refresh_url> provides a url the client can request again to see further results. If the client user agent does not support cookies, then this refresh_url must be used to continue retrieving results from the same Umlaut request, instead of accidentally creating a new request. Even if your client does support cookies, using the <refresh_url> is safest--simply refreshing the URL you loaded initially may accidentally create a new request. (The refresh_url given includes an umlaut.request_id parameter to ensure connection to the proper request). '''note well:''' The URL, like any other data in XML, is XML-escaped, and needs to be un-escaped before using.

<requested_wait_seconds> is a request from Umlaut for the client to wait this many seconds before asking for more results. Umlaut has no way to enforce this, it's only a request. Please wait a reasonable amount of time to avoid overloading Umlaut however.

<services_in_progress> lists the ServiceTypeValues that may still have responses coming, that may not be complete. A list of all possible ServiceTypeValues in a default Umlaut installation can be found in the [[http://umlaut.rubyforge.org/svn/trunk/db/orig_fixed_data/service_type_values.yml Umlaut code]].

== <service_statuses> ==

This block provides information on the internal service plug-ins involved in this Umlaut request, and what their status is. In most cases, an API client will not need this information.

<status> can be one of:
* in_progress : Currently executing
* queued : Background service which is queued up, but not yet running.
* succesful : completed succesfully (may or may not have generated any responses)
* failed_fatal: A fatal error condition was encountered, for instance a bug in Umlaut code.
* failed_temporary: An error condition was encountered, but Umlaut ''may'' try to run the service again, the error was not fatal, for instance an external service timed out.

These constants are defined in [http://umlaut.rubyforge.org/svn/trunk/app/models/dispatched_service.rb dispatched_service.rb]

If the <status> is failed_fatal or failed_temporary, there may be error information in an <exception_info> block.

== <responses> ==

The meat, the actual response or 'target' data generated by Umlaut. These responses are grouped by ServiceTypeValues. A given ServiceTypeValue identifies a certain type of service, like full text, or library holdings. The list of possible ServiceTypeValues in a default Umlaut installation can be found in the relevant Umlaut distribution data file [http://umlaut.rubyforge.org/svn/trunk/db/orig_fixed_data/service_type_values.yml service_type_values.yml]

The <responses> block contains 0 or more <type_group> blocks. Each type_group has a name attribute identifiying the ServiceTypeValue, also provides you with user-displayable label for this type, and tells you if all services that generate this type are complete or not. A type_group will only be present if it contains responses.

<pre>
<type_group name="abstract">
<display_name>Abstract</display_name>
<display_name_plural>Abstracts</display_name_plural>
<complete>true</complete>

[...]
</type>
</pre>

=== <response> ===

Each type_group will have one or more <response> blocks in it. A <response> represents an individual piece of data generated by umlaut. This is what most clients will be most interested in, but it's tricky to deal with because the contents of a <response> are quite variable. They can vary between responses for different ServiceTypeValues, and there can even be specialized data only in responses belong to a particular Service plug-in. All the data that Umlaut has is included here, including some really intended for internal use only.

However, don't despair, there are a few things you can count on. The <display_text> element will always include the label or heading that is to be used for the response. A <notes> element may be present with additional explanatory text. These alone, plus a linking url, will be enough for many clients.

Standard internal metadata includes a <service> element which will contain the name of the service plug-in that generated this response. (Match to services listed in <service_statuses> above).

==== Linking url: <umlaut_passthrough_url> ====

You may see the <url> element in the response and be tempted to use it to send the user to this response. '''You are strongly cautioned not to do so.''' In the Umlaut architecture, urls can be generated on-demand when the user clicks on an element, not at time of original response (this is because even generating the url is sometimes an expensive operation). This means that the <url> element is not guaranteed to be there, and when it is there is not guaranteed to be accurate. On top of all that, the application of a proxy pass through won't be applied yet to the url found here.

You should instead use the <umlaut_passthrough_url> element. This will contain a URL pointing to your umlaut installation, of the form: http://umlaut.university.edu/link_router/index/7447333

When this URL is accessed, Umlaut will '''redirect''' the user to the actual destination--after calculating that destination, and applying any proxy or other filters, etc. In some cases it may end up redirecting to the same destination as <url>, but in other cases it may be somewhat different, or may work even if <url> was not present.

'''Please use the umlaut_passthrough_url for linking.'''

==== Other Conventions ====

Each ServiceTypeValue has other conventions for elements that will be present in that ServiceTypeValue. These are documented in [http://umlaut.rubyforge.org/api/classes/ServiceResponse.html ServiceResponse] in the Conventional Keys section.

==== example ====

<pre>
<response id="7447899">
<service>JH_SFX</service>


<display_text>Free E- Journals</display_text>
<url>http://dl.lib.brown.edu/radicalamerica/shelf.html</url>
<notes></notes>
<coverage>
Available from 1967 volume: 1 issue: 2 until 1987 volume: 21 issue: 6.
</coverage>
<sfx_target_name>MISCELLANEOUS_FREE_EJOURNALS</sfx_target_name>
<sfx_base_url>http://sfx.library.jhu.edu:8000/sfxlcl3</sfx_base_url>
<sfx_obj_index>1</sfx_obj_index>
<sfx_target_index>1</sfx_target_index>
<source>SFX/FT::NO_FILL_IN</source>
<sfx_request_id>2688845</sfx_request_id>
<sfx_target_service_id>
110976638852341 </sfx_target_service_id>
<umlaut_passthrough_url>http://findit.library.jhu.edu/link_router/index/7447899</umlaut_passthrough_url>
</response>
</pre>

Umlaut partial html API

2008-10-02T19:07:00Z

128.220.159.25:

The Umlaut partial HTML API is meant for when you want Umlaut to generate HTML, but you want to embed that HTML on an external page. The API will deliver sections of generated HTML, that you can include elsewhere.

[[Category:Umlaut]]

If you plan to include it via javascript, you will likely find it even more convenient to use the [Umlaut partial html API javascript helper], saving you even more work. The javascript helper uses the API behind the scenes.

= Accessing the API =

Supplied via the resolve/partial_html_sections actions. Instead of accessing the ordinary resolver base URL, you replace "resolve?" in your query with "resolve/partial_html", eg http://umlaut.university.edu/resolve/partial_html? . You send the OpenURL context object the same as you would for an ordinary resolve action, in URL or POST XML, etc.

By default, the API returns XML. To return json instead, include:

&umlaut.response_format=json

To return jsonp, wrapped in a javascript procedure call:

&umlaut.response_format=jsonp&umlaut.jsonp=desiredJavascriptFunctionName

= Response =

== <complete> ==

When accessing Umlaut over an API, it's important to realize that the initial response from Umlaut may not include all Umlaut information. Umlaut continues to run services in the background that can generate responses and enhance metadata. <complete> will contain 'true' or 'false' depending on whether background services are still executing. Further elements in the response provide information on what is still executing, and how to retrieve further information.

== <in_progress> ==

This block will only be present when <complete> is 'false'. It provides information on completion status, and how to refresh the response for more information prepared in the background. For more information, see the documentation in [[Umlaut full API#<in_progress>]], the block is the same here.

== <html_section> ==

What you really want is contained in 0 or more html_section blocks. Each one contains some generated HTML, along with some metadata about it. The id attribute of <html_section> tells you which section it is. What sections exist is configured in Umlaut in the "partial_html_map" configuration param, which by default is set to the "bg_update_map" config params :divs key. To see the sections in a default Umlaut installation, see: [http://umlaut.rubyforge.org/svn/trunk/config/environment.rb environment.rb in svn], look for bg_update_map. The :divs key of the hash there is an array of hashes, each individual hash has a :div_id key that corresponds to the html_sections id in this api response. For Umlaut developers, the :partial key tells you what Rails partial is used to generate this section.

The sections and their contents can be customized by the Umlaut administrator by changing the partial_html_map config (and/or the bg_update_map config).

Inside an html_section in the response there is a bit of metadata for you:

=== <included_services> ===

What ServiceTypeValues are included in this html section. This specifies what type of data is in this block. For a list of possible ServiceTypeValues in a default Umlaut configuration, see [http://umlaut.rubyforge.org/svn/trunk/db/orig_fixed_data/service_type_values.yml service_type_values.yml] in umlaut SVN.

=== <service_load_complete> ===

true or false. False if this html_section might change as more background services run, true if this html_section is completely finished.

=== <response_count> ===

How many Umlaut response objects were used to generate this block? Can be useful if you want to do something different with 0 (no content) vs. non-0 (content).

=== <html_content> ===

The actual html content. It is of course standardly XML-escaped in XML, or json-escaped in json.

Umlaut full API

2008-10-02T19:06:35Z

128.220.159.25:

Umlaut has a complete api for resolve actions, which can be delivered in XML or json. For simple uses of embedding Umlaut content on a page, you may find the [[Umlaut partial html API]] or [[Umlaut partial html API javascript helper]] easier to use.

[[Category:Umlaut]]

= Accessing the API =

The api can be accessed at the resolve/api action. For instance, if your umlaut is at umlaut.somewhere.edu/, http://umlaut.somewhere.edu/resolve/api?

Append an OpenURL context object to that URL. POST is also supported, including XML formatted context objects. You can also include the usual umlaut directive parameters.

This is exactly what you'd send to the ordinary Umlaut link resolver base url for link resolver service in html; you are just replacing /resolve? with /resolve/api?

By default, the API returns XML. To return json instead, include:

&umlaut.response_format=json

To return jsonp, wrapped in a javascript procedure call:

&umlaut.response_format=jsonp&umlaut.jsonp=desiredJavascriptFunctionName

= API Response =

== <request_id> ==

<pre>
<request_id>701544</request_id>
</pre>

Umlaut's internal request id. API clients usually don't need this, but can be useful if you want a unique identifier for this OpenURL request. May also be useful if you want to call other Umlaut actions on this same OpenURL request, ensuring that Umlaut matches to the same request, by including &umlaut.request_id in your request.

== <context_object_xml> ==

Contains an OpenURL context object in XML serialization. May include enhanced citation metadata from Umlaut.

== <complete> ==

When accessing Umlaut over an API, it's important to realize that the initial response from Umlaut may not include all Umlaut information. Umlaut continues to run services in the background that can generate responses and enhance metadata. <complete> will contain 'true' or 'false' depending on whether background services are still executing. Further elements in the response provide information on what is still executing, and how to retrieve further information.

== <in_progress> ==

'''example''':
<pre>
<in_progress>
<refresh_url>http://findit.library.jhu.edu/resolve/api?umlaut.request_id=701544&.....</refresh_url>
<refresh_url_path>/resolve/api?umlaut.request_id=701544&.....</refresh_url_path>
<requested_wait_seconds>4</requested_wait_seconds>
<services_in_progress>
<service name="fulltext" />
<service name="holding" />
<service name="table_of_contents" />
<service name="highlighted_link" />
<service name="audio" />
<service name="holding_search" />
</services_in_progress>
</in_progress>
</pre>

This block will only be present when <complete> is 'false'.

<refresh_url> provides a url the client can request again to see further results. If the client user agent does not support cookies, then this refresh_url must be used to continue retrieving results from the same Umlaut request, instead of accidentally creating a new request. Even if your client does support cookies, using the <refresh_url> is safest--simply refreshing the URL you loaded initially may accidentally create a new request. (The refresh_url given includes an umlaut.request_id parameter to ensure connection to the proper request).

<requested_wait_seconds> is a request from Umlaut for the client to wait this many seconds before asking for more results. Umlaut has no way to enforce this, it's only a request. Please wait a reasonable amount of time to avoid overloading Umlaut however.

<services_in_progress> lists the ServiceTypeValues that may still have responses coming, that may not be complete. A list of all possible ServiceTypeValues in a default Umlaut installation can be found in the [[http://umlaut.rubyforge.org/svn/trunk/db/orig_fixed_data/service_type_values.yml Umlaut code]].

== <service_statuses> ==

This block provides information on the internal service plug-ins involved in this Umlaut request, and what their status is. In most cases, an API client will not need this information.

<status> can be one of:
* in_progress : Currently executing
* queued : Background service which is queued up, but not yet running.
* succesful : completed succesfully (may or may not have generated any responses)
* failed_fatal: A fatal error condition was encountered, for instance a bug in Umlaut code.
* failed_temporary: An error condition was encountered, but Umlaut ''may'' try to run the service again, the error was not fatal, for instance an external service timed out.

These constants are defined in [http://umlaut.rubyforge.org/svn/trunk/app/models/dispatched_service.rb dispatched_service.rb]

If the <status> is failed_fatal or failed_temporary, there may be error information in an <exception_info> block.

== <responses> ==

The meat, the actual response or 'target' data generated by Umlaut. These responses are grouped by ServiceTypeValues. A given ServiceTypeValue identifies a certain type of service, like full text, or library holdings. The list of possible ServiceTypeValues in a default Umlaut installation can be found in the relevant Umlaut distribution data file [http://umlaut.rubyforge.org/svn/trunk/db/orig_fixed_data/service_type_values.yml service_type_values.yml]

The <responses> block contains 0 or more <type_group> blocks. Each type_group has a name attribute identifiying the ServiceTypeValue, also provides you with user-displayable label for this type, and tells you if all services that generate this type are complete or not. A type_group will only be present if it contains responses.

<pre>
<type_group name="abstract">
<display_name>Abstract</display_name>
<display_name_plural>Abstracts</display_name_plural>
<complete>true</complete>

[...]
</type>
</pre>

=== <response> ===

Each type_group will have one or more <response> blocks in it. A <response> represents an individual piece of data generated by umlaut. This is what most clients will be most interested in, but it's tricky to deal with because the contents of a <response> are quite variable. They can vary between responses for different ServiceTypeValues, and there can even be specialized data only in responses belong to a particular Service plug-in. All the data that Umlaut has is included here, including some really intended for internal use only.

However, don't despair, there are a few things you can count on. The <display_text> element will always include the label or heading that is to be used for the response. A <notes> element may be present with additional explanatory text. These alone, plus a linking url, will be enough for many clients.

Standard internal metadata includes a <service> element which will contain the name of the service plug-in that generated this response. (Match to services listed in <service_statuses> above).

==== Linking url: <umlaut_passthrough_url> ====

You may see the <url> element in the response and be tempted to use it to send the user to this response. '''You are strongly cautioned not to do so.''' In the Umlaut architecture, urls can be generated on-demand when the user clicks on an element, not at time of original response (this is because even generating the url is sometimes an expensive operation). This means that the <url> element is not guaranteed to be there, and when it is there is not guaranteed to be accurate. On top of all that, the application of a proxy pass through won't be applied yet to the url found here.

You should instead use the <umlaut_passthrough_url> element. This will contain a URL pointing to your umlaut installation, of the form: http://umlaut.university.edu/link_router/index/7447333

When this URL is accessed, Umlaut will '''redirect''' the user to the actual destination--after calculating that destination, and applying any proxy or other filters, etc. In some cases it may end up redirecting to the same destination as <url>, but in other cases it may be somewhat different, or may work even if <url> was not present.

'''Please use the umlaut_passthrough_url for linking.'''

==== Other Conventions ====

Each ServiceTypeValue has other conventions for elements that will be present in that ServiceTypeValue. These are documented in [http://umlaut.rubyforge.org/api/classes/ServiceResponse.html ServiceResponse] in the Conventional Keys section.

==== example ====

<pre>
<response id="7447899">
<service>JH_SFX</service>


<display_text>Free E- Journals</display_text>
<url>http://dl.lib.brown.edu/radicalamerica/shelf.html</url>
<notes></notes>
<coverage>
Available from 1967 volume: 1 issue: 2 until 1987 volume: 21 issue: 6.
</coverage>
<sfx_target_name>MISCELLANEOUS_FREE_EJOURNALS</sfx_target_name>
<sfx_base_url>http://sfx.library.jhu.edu:8000/sfxlcl3</sfx_base_url>
<sfx_obj_index>1</sfx_obj_index>
<sfx_target_index>1</sfx_target_index>
<source>SFX/FT::NO_FILL_IN</source>
<sfx_request_id>2688845</sfx_request_id>
<sfx_target_service_id>
110976638852341 </sfx_target_service_id>
<umlaut_passthrough_url>http://findit.library.jhu.edu/link_router/index/7447899</umlaut_passthrough_url>
</response>
</pre>