getDataByPathAdded by IBM on October 10, 2012 | Version 1 (Original)
|Retrieves specific information from a signature in the form, such as the signer's name or the signer's e-mail address. Tags: getDataByPath function, utility
functions, signatures, data path, signature tags, digital signature
tags, electronic signature tags, certificate tags, digital certificate
tags, Clickwrap signature tags, HMAC signature tags, security engine
tags, tags, XFDL, 8.0, spec
Table 1. getDataByPath parameters
getDataByPath(type, ref, path)
|type||String||The type of object you are working with. The type is always signature.|
|ref||Reference string||A reference to the signature item in the form.|
|path||String||The path to the data you are retrieving from the signature. |
Returns A string containing the requested data.
About data paths Data paths describe the location of information within a signature, just like file paths describe the location of files on a disk. You describe the path with a series of colon separated tags. Each tag represents either a piece of data, or an object that contains further pieces of data (just like directories can contain files and subdirectories).
For example, to retrieve the version of a signature, you would use the following data path:
However, to retrieve the signer's common name, you first need to locate the signing certificate, then the subject, then finally the common name within the subject, as follows:
Some tags can contain more than one piece of information. For example, the issuer's organizational unit might contain a number of entries. You can either retrieve all of the entries as a comma-separated list, or you can specify a specific entry by using a zero-indexed element number.
For example, the following path would retrieve a comma-separated list:
Adding an element number of 0 would retrieve the first organizational unit in the list, as shown:
SigningCert: Issuer: OU: 0
Signature tags The following list describes the tags available in a signature object. Note that Clickwrap and Hash Message Authentication Code (HMAC) Clickwrap signatures have additional tags, as detailed in Clickwrap signature tags and HMAC Clickwrap Tags below.
The security engine used to create the signature.SigningCert The certificate used to create the signature. This object contains further information, as detailed in Certificate tags . Note that this object does not exist for Clickwrap or HMAC Clickwrap signatures.HashAlg The hash algorithm used to create the signature.CreateDate The date on which the signature was created.Demographics
A string describing the signature.
Clickwrap signature tags The following list describes additional tags available in both Clickwrap and HMAC Clickwrap signatures. Note that HMAC Clickwrap signatures have further tags, as detailed in HMAC Clickwrap Tags below.
The text for the Windows™ title bar of the signature dialog box.MainPrompt The text for the title portion of the signature dialog box.MainText The text for the text portion of the signature dialog box.Question1Text The first question in the signature dialog box.Answer1TextQuestion2Text The second question in the signature dialog box.Answer2TextQuestion3Text The third question in the signature dialog box.Answer3TextQuestion4Text The fourth question in the signature dialog box.Answer4TextQuestion5Text The fifth question in the signature dialog box.Answer5TextEchoPrompt Text that the signer must echo to create a signature.EchoText The signer's response to the echo text.ButtonPrompt The text that provides instructions for the Clickwrap signature buttons.AcceptText The text for the accept signature button.RejectText
The text for the reject signature button.
Certificate tags The following list describes the tags available in a certificate object. Note that Clickwrap and HMAC Clickwrap signatures do not contain these tags.
The subject's distinguished name. This object contains further information, as detailed in Distinguished Name Tags .Issuer The issuer's distinguished name. This object contains further information, as detailed in Distinguished Name Tags .IssuerCert The issuer's certificate. This object contains the complete list of certificate tags.Engine The security engine that generated the certificate. This object contains further information, as detailed in Security Engine Tags .VersionBeginDate The date on which the certificate became valid.EndDate The date on which the certificate expires.Serial The certificate's serial number.signatureAlg The signature algorithm used to sign the certificate.PublicKey The certificate's public key.FriendlyName
The certificate's friendly name.
Distinguished name tags The following list describes the tags available in a distinguished name object. Note that Clickwrap and HMAC Clickwrap signatures do not contain these tags.
The entire distinguished name.
HMAC Clickwrap Tags The following list describes the tags available in HMAC Clickwrap signature. Note that these tags are in addition to both the regular Signature tags and the Clickwrap signature tags .
A string indicating which answers store the signer's ID.HMACSecret A string indicating which answers store the signer's secret.Notarization The notarizing signatures. These signatures are one or more signature objects that contain further information, as detailed in Signature tags . There can be any number of notarizing signatures. Use an element number to retrieve a specific signature. For example, to get the first notarizing signature use:
If no element number is provided, the data is retrieved from the first valid notarizing signature found. If no valid notarizing signatures are found, the function returns an empty string ("").
Security engine tags The following list describes the tags available in the security engine object:
The name of the security engine.Help The help text for the security engine.HashAlg
A hash algorithm supported by the security engine.
Example The following example shows a label that displays the signer's e-mail address after the form is signed. In this case, the label's value is set using an if/then test to determine whether the signer option on the signature button is set to anything other than an empty string. If it is, then the form has been signed, and getDataByPath is called to get the e-mail address of the signer.
<value compute="Page1.sigButton.signer != '' ?
'SigningCert: Subject: E') : ''></value>