Articles in this section

Passing parameters

Parameter passing permits data placed on an outbound DOI link to pass along to the target publisher. There are two procedures for passing parameters: The first uses an undocumented feature of the DOI resolver while the second is a robust implementation based on OpenURL structured to prevent name collisions that would result in the loss of data.

Procedure 1

For very limited situations where parameter passing is needed, you can use the name-value pair called "urlappend". You can construct outbound links by placing parameter values in this single URL variable. However, before constructing the link, you must know if the registered URL for the DOI already has parameters.

For example, suppose DOI 10.5555/unique_doi_060103-01 has no parameters on its registered URL. You can then pass parameters as follows:

https://doi.org/10.5555/unique_doi_060103-01?urlappend=%3fpassed_param=<VALUE>

DOI 10.5555/unique_doi_060103-01 does have parameters on its registered URL , passed parameter are added as follows:

https://doi.org/10.5555/unique_doi_060103-01?urlappend=%26passed_param=<VALUE>

Because the urlappend function is primitive, you must insert the correct character—either a question mark (%3F) or an ampersand (%26)—before the name-value pair information you want to pass. In addition, if the target's publisher is not be expecting incoming parameters, the values placed in urlappend may conflict with names of parameters already on the registered URL.

Procedure 2

This more robust solution based on OpenURL is a bit more complicated, but it has several advantages:

  • It works whether or not the DOI's registered URL already has parameters.
  • It prevents parameter name collisions.
  • It lets the recipient of the link (the host of the target) control whether it receives passed parameters.
  • It establishes a common vocabulary for passed parameters, reducing the need for bi-lateral coordination.

OpenURL 1.0 defines a set of parameters to use when conveying information in a hyperlink. Procedure 2 depends on two of these parameters—rft_dat and rfr_dat—to act as wrappers for both the passed parameters and the existing parameters on the DOI's registered URL. Parameter rft_dat (referent data) contains the entire registered URL's parameter set as a nested string. Parameter rfr_dat (referrer data) contains another nested string with the information the source wants to pass to the target. Data inside the rfr_dat should conform to the controlled vocabulary described in the Parameter Passing white paper (PDF). Because the DOI's registered URL parameters are safely nested inside rft_dat, parameter passing also forwards any non-OpenURL parameters found on the source link to the target.

Crossref strongly encourages the use of rfr_dat due to the controlled vocabulary.

For example, this in-bound link:

https://doi.org/openurl?url_ver=Z39.88-2003&rft_id=doi:10.5555/unique_doi_060103-01&rfr_dat=rfr_dat=cr_setver=01&cr_pub=Source Publisher&cr_work=Source Journal Title&cr_src=SRC-NAME

is combined with the registered URL:

http://www.crossref.org/paramEcho?param=done&param2=two

to create the following outbound link:

http://www.crossref.org/paramEcho?url_ver=Z39.88-2003&rft_id=doi:10.5555/unique_doi_060103-01&rft_dat=param1=done&param2=two&rfr_dat=rfr_dat=cr_setver=01&cr_pub=Source Publisher&cr_work=Source Journal Title&cr_src=SRC-NAM

For readability, this example is not shown in encoded form. If they were, the rft_dat portion would look like this: rft_dat=param1%3Ddone%26param2%3Dtwo.

More Examples

Example 1

This link uses a DOI without parameter passing:

https://doi.org/10.5555/unique_doi_060103-01

The target system would receive the following incoming information:

(name) param1 (value) one (name) param2 (value) two -----------------Using request.getParameter()

where the values of param1 and param2 are part of the URL registered for the DOI.

Example 2

This link uses the same DOI with parameter passing:

https://doi.org/openurl?url_ver=Z39.88-2003&rft_id=doi:10.5555/unique_doi_060103-01&rfr_data=stuff%3dgood

The source of the link wants to send the name-value pair of stuff=good to the target system. The param1 and param2 variables are still passed to the target, as shown here, but they are wrapped inside the rft_dat parameter:

(name) url_ver (value) Z39.88-2003 (name) rft_id (value) doi:10.5555/unique_doi_060103-01 (name) rfr_data (value) stuff%3dgood Nested Parameters (name) stuff (value) good (name) rft_dat (value) param1%3Done%26param2%3Dtwo Nested Parameters (name) param1 (value) one (name) param2 (value) two -----------------Using request.getParameter()

The data stuff=good is also passed to the target inside the rfr_dat parameter. This demonstrates good practice by avoiding name conflicts.

Example 3

This link demonstrates that any top-level paramater will also be passed to the target, but it will not be wrapped in any OpenURL containers:

https://doi.org/openurl?url_ver=Z39.88-2003&rft_id=doi:10.5555/unique_doi_060103-01&rfr_data=stuff%3dgood&santa=claus

In this case, the name-value pair santa=claus is appended to the link in a way that is not consistent with (but no explicitly prohibited by) the OpenURL specification. The target receives this data:

(name) url_ver (value) Z39.88-2003(name) rft_id (value) doi:10.5555/unique_doi_060103-01 (name) rfr_data (value) stuff%3dgood Nested Parameters (name) stuff (value) good (name) santa (value) claus (name) rft_dat (value) param1%3Done%26param2%3Dtwo Nested Parameters (name) param1 (value) one (name) param2 (value) two -----------------Using request.getParameter()

Example 4

This link shows how the OpenURL based parameter passing handles potential conflicts in parameter names:

https://doi.org/openurl?url_ver=Z39.88-2003&rft_id=doi:10.5555/unique_doi_060103-01&param1=five

In this case, the variable param1 is passed to the target twice:

(name) url_ver (value) Z39.88-2003 (name) rft_id (value) doi:10.5555/unique_doi_060103-01 (name) five?url_ver (value) Z39.88-2003 (name) rft_id (value) doi:10.5555/unique_doi_060103-01 (name) param1 (value) five (name) rft_dat (value) param1%3Done%26param2%3Dtwo Nested Parameters (name) param1 (value) one (name) param2 (value) two -----------------Using request.getParameter()

Here, the param1 nested inside rft_dat is known to be the one registered with the DOI's URL.

If, on the other hand, you used the primitive urlappend function instead, as shown here:

https://doi.org/10.5555/unique_doi_060103-01?urlappend=%26param1=five

the target wouldn't be able to tell which value of param1 came from the DOI or from the source link:

(name) param1 (value) one (name) param2 (value) two (name) param1 (value) five -----------------Using request.getParameter()

Comments

0 comments

Please sign in to leave a comment.