Photos and Certificates

Web Center supports photos and certificates.

Web Center is delivered with three pre-defined renderers for photos:

  • photo – Displays a photo.

  • photoDownload – Displays an icon to display a photo.

  • photos – Displays one or more photos.

  • documents – Displays one or more photos.

Web Center is delivered with two pre-defined renderers for certificates:

  • certificateDownload – Displays a download icon for a certificate.

  • certificate – Displays one or more certificates, along with icons to download them.

Downloads are, in fact, supported for any binary attribute, not just photos and certificates, though there are no pre-defined renderers for other attributes.

The current version does not include pre-defined renderers for integrating binary attributes in entry lists.

Prerequisites

A binary attribute must be appropriately defined in a DirX Identity object description before you can access its values from within Web Center:

  • Its type must be set to byte array: type=“[b”.

  • In order to access multiple values, its multi value flag must be set to true: multivalue="true".

The following sample defines two single valued binary attributes (userCertificate and jpegPhoto), and a multivalued one (photo):

<property name="userCertificate" label="Certificate"
          type="[B" multivalue="false" editor="..."/>

<property name="photo" label="Photo"
          type="[B" multivalue="true" editor="..."/>

<property name="jpegPhoto" label="Photo"
          type="[B" editor="..."/>

Renderers

This section provides information about the pre-defined renderers for photos and certificates.

Photo

The renderer downloads a photo immediately when the HTML page is loaded, and displays a small thumbnail of it.When the user moves the mouse over the thumbnail, the photo is displayed in its actual size on top of the page.When the user moves the mouse off of the actual-sized photo, it is hidden again.

The renderer cannot handle more than one photo; if several photos are available, the first one is rendered.

Form Field Configuration Sample

<form-property name="jpegPhoto" type="byte[]"
               label="ldap.attribute.photo"
               readonly="true"
               fieldRenderer="photo"/>

Change the type to “java.lang.Object[]” if the property is defined as multi-valued in the DirX Identity object descriptions.

Renderer Configuration

The following sections provide information about how to configure the renderer for photos.

Attributes

The following table lists the attributes for renderer configuration:

Name Value

Id

Photo

type

java.lang.Object[]

className

com.siemens.webMgr.taglib.view.renderers.DownloadRenderer

defURL

/WEB-INF/snippets/binary/photo.htm
Properties

The renderer does not support any properties in addition to the ones described in the section “DownloadRenderer” in the section “Java Renderer Classes”.

Sample
<renderer id="photo" type="java.lang.Object[]"
    className=
  "com.siemens.webMgr.taglib.view.renderers.DownloadRenderer"
    defURL="/WEB-INF/snippets/binary/photo.htm">
  <renderer-property name="servletPath"
                     value="binaryReader"/>
  <renderer-property name="contentType" value="image/jpeg"/>
  <renderer-property name="prefix"      value="jpegPhoto"/>
  <renderer-property name="extension"   value=".jpg"/>
</renderer>

The generated download URI is “binaryReader/jpegPhoto_0.jpg?…​”.

HTML/Javascript Rendering

The HTML code snippet is defined in binary/photo.htm. It invokes a JavaScript function of the photos variable in documentFuncs.js.

PhotoDownload

The renderer displays just a small icon when the HTML page is loaded. When the user clicks the icon, the photo is downloaded from the server and displayed in its actual size on top of the page. Moving the mouse off of the photo hides it again.

The renderer cannot handle more than one photo; if several photos are available, just the first one is rendered. The renderer saves resources since the photo is downloaded only on specific request.

Form Field Configuration Sample

<form-property name="photo" type="byte[]"
               label="ldap.attribute.photo" readonly="true"
               fieldRenderer="photoDownload"/>

Change the type to “java.lang.Object[]” if the property is defined as multi-valued in the DirX Identity object descriptions.

Renderer Configuration

The following sections provide information on how to configure the renderer for photo download displaying an icon first.

Attributes

The following table lists the attributes for renderer configuration for photo download:

Name Value

id

photoDownload

type

java.lang.Object[]

className

com.siemens.webMgr.taglib.view.renderers.DownloadRenderer

defURL

/WEB-INF/snippets/binary/photoDownload.htm
Properties

The renderer supports the following properties in addition to the properties described in the section “DownloadRenderer” of section “Java Renderer Classes”:

Name Value

downloadImage

The icon to be displayed when the HTML page is loaded.

downloadText

The message key for the icon tooltip.
Sample
<renderer id="photoDownload" type="java.lang.Object[]"
    className=
  "com.siemens.webMgr.taglib.view.renderers.DownloadRenderer"
    defURL="/WEB-INF/snippets/binary/photoDownload.htm">
  <renderer-property name="servletPath"
                     value="binaryReader"/>
  <renderer-property name="contentType" value="image/gif"/>
  <renderer-property name="prefix"      value="photo"/>
  <renderer-property name="extension"   value=".gif"/>
  <renderer-property name="downloadImage"
                     value="resources/images/photo.gif"/>
  <renderer-property name="downloadText"
                     value="photo.display"/>
</renderer>

The generated download URI is “binaryReader/photo_0.gif?…​”.

HTML/Javascript Rendering

The HTML code snippet is defined in binary/photoDownload.htm. It invokes a Javascript function of the photos variable in documentFuncs.js.

Photos

The renderer downloads and displays one or more photos when the HTML page is loaded. The photos are either displayed in their original size, or as thumbnails. A user can view a thumbnail photo in its original size by clicking on it or by moving the mouse onto it. The photos can be aligned vertically or horizontally.

Form Field Configuration Sample

<form-property name="photo" type="byte[]" y="+1" spanX="6"
               label="ldap.attribute.photo" readonly="true"
               fieldRenderer="photos"/>

Change the type to “java.lang.Object[]” if the property is defined as multi-valued in the DirX Identity object descriptions.

Renderer Configuration

The following sections provide information on how to configure the renderer for photo download displaying the photo in its actual size.

Attributes

The following table lists the attributes for renderer configuration:

Name Value

id

Photos

type

java.lang.Object[]

className

com.siemens.webMgr.taglib.view.renderers.DownloadRenderer

defURL

/WEB-INF/snippets/binary/photos.htm
Properties

The renderer supports the following properties in addition to the ones described in the section “DownloadRenderer” of the section “Java Renderer Classes”:

Name Value

direction

Whether to display the photos one below each other (vertical) or in a single row (horizontal).

thumbNailClass

The CSS classes for the photos. Can be used to define the display width and height of a thumbnail, or the gap between adjacent thumbnails.

event

Whether to display a photo in its original size when a user clicks onto its thumbnail (click) or moves the mouse onto it (mouseover).

hint

A message key indicating to the user how to enlarge a thumbnail.
Sample
<renderer id="photos" type="java.lang.Object[]"
    className=
  "com.siemens.webMgr.taglib.view.renderers.DownloadRenderer"
    defURL="/WEB-INF/snippets/binary/photos.htm">
  <renderer-property name="servletPath"
                     value="binaryReader"/>
  <renderer-property name="contentType" value="image/gif"/>
  <renderer-property name="prefix"      value="photo"/>
  <renderer-property name="extension"   value=".gif"/>
  <renderer-property name="max"         value="0"/>
  <renderer-property name="direction"
                     value="horizontal"/>
  <renderer-property name="thumbNailClass"
              value="photoThumbnail thumbnailHori"/>
  <renderer-property name="event"
                     value="mouseover"/>
  <renderer-property name="hint"
                     value="photo.enlarge.mouseover"/>
</renderer>

The generated download URIs are “binaryReader/photo_0.gif?…​”, “binaryReader/photo_1.gif?…​” and so on.

HTML/Javascript Rendering

The HTML code snippet is defined in binary/photos.htm. It invokes a JavaScript function of the photos variable in documentFuncs.js.

Documents

The renderer is a variant of renderer Photos with different values for some renderer properties.

Sample

<renderer id="documents" extends="photos">
  <renderer-property name="direction"
                     value="vertical"/>
  <renderer-property name="thumbNailClass"
              value="documentThumbnail thumbnailVert"/>
  <renderer-property name="event"
                     value="click"/>
  <renderer-property name="hint"
                     value="photo.enlarge.click"/>
</renderer>

Certificate Download

The renderer displays a small icon when the HTML page is loaded. When the user clicks the icon, the certificate is downloaded from the server and the browser opens its standard dialog to let the user view the certificate or save it as a file on the client.

The renderer cannot handle more than one certificate; if several certificates are available, the first one is rendered.

Form Field Configuration Sample

<form-property name="userCertificate" type="byte[]"
               label="ldap.attribute.certificate"
               readonly="true"
               fieldRenderer="certificateDownload"/>

Change the type to “java.lang.Object[]” if the property is defined as multi-valued in the DirX Identity object descriptions.

Renderer Configuration

The following sections provide information on how to configure the renderer for certificate download displaying a small icon first.

Attributes

The following table lists the attributes for renderer configuration:

Name Value

id

certificateDownload

type

java.lang.Object[]

className

com.siemens.webMgr.taglib.view.renderers.DownloadRenderer

defURL

/WEB-INF/snippets/binary/certificateDownload.htm
Properties

The renderer supports the following properties in addition to the properties described in the section “DownloadRenderer” of the section “Java Renderer Classes”:

Name Value

downloadImage

The icon to be displayed when the HTML page is loaded.

downloadText

The message key for the icon tooltip.
Sample
<renderer id="certificateDownload" type="java.lang.Object[]"
    className=
  "com.siemens.webMgr.taglib.view.renderers.DownloadRenderer"
    defURL=
        "/WEB-INF/snippets/binary/certificateDownload.htm">
  <renderer-property name="servletPath"
                     value="binaryReader"/>
  <renderer-property name="contentType"
                     value="application/pkix-cert"/>
  <renderer-property name="prefix"      value="certificate"/>
  <renderer-property name="extension"   value=".cer"/>
  <renderer-property name="downloadImage"
                     value="resources/images/cert.gif"/>
  <renderer-property name="downloadText"
                     value="certificate.displayDownload"/>
</renderer>

The resulting download URI is “binaryReader/cert_0.cer?…​”.

HTML/JavaScript Rendering

The HTML code snippet is defined in binary/certificateDownload.htm. It invokes a JavaScript function of the certs variable in documentFuncs.js.

Certificates

The renderer displays one or more certificates, one below the other, when the HTML page is loaded. Each certificate is displayed in a table listing a configurable subset of its fields like issuer name, subject name and validity period. A small icon allows for downloading the certificate from the server; when clicked, the browser opens its standard dialog to let the user view the certificate or save it as a file on the client.

The renderer is quite simple since it displays each certificate field on a single line and truncates values exceeding a configurable maximum length.

Form Field Configuration Sample

<form-property name="userCertificate" type="byte[]"
               y="+1" spanX="6"
               label="ldap.attribute.certificate"
               readonly="true"
               fieldRenderer="certificates"/>

Change the type to “java.lang.Object[]” if the property is defined as multi-valued in the DirX Identity object descriptions.

Renderer Configuration

The following sections provide information on how to configure the renderer for certificate download displaying the certificates.

Attributes

The following table lists the attributes for renderer configuration:

Name Value

id

certificates

type

java.lang.Object[]

className

com.siemens.webMgr.taglib.view.renderers.X509CertificateRenderer

defURL

/WEB-INF/snippets/binary/certificates.htm
Properties

In addition to the properties described in section “DownloadRenderer” of section “Java Renderer Classes” below the renderer supports the following properties:

Name Value

downloadImage

The icon to be displayed when the HTML page is loaded.

downloadText

The message key for the icon tooltip.

maxValueLen

The maximum length for values displayed in the table. Longer values are truncated, which is indicated by three dots appended to the truncated value.
Sample
<renderer id="certificates" type="java.lang.Object[]"
    className=
       "com.siemens.webMgr.taglib.view.renderers.
                                   X509CertificateRenderer"
    defURL="/WEB-INF/snippets/binary/certificates.htm">
  <renderer-property name="dateFormat"
                     value="certificate.dateFormat"/>
  <renderer-property name="dnFormat"      value="RFC1779"/>
  <renderer-property name="attributes"
                     value="subjectDN,valid"/>
  <renderer-property name="messagePrefix"
                     value="certificate"/>
  <renderer-property name="servletPath"
                     value="binaryReader"/>
  <renderer-property name="contentType"
                     value="application/pkix-cert"/>
  <renderer-property name="prefix"
                     value="certificate"/>
  <renderer-property name="extension"     value=".cer"/>
  <renderer-property name="max"           value="0"/>
  <renderer-property name="maxValueLen"   value="80"/>
  <renderer-property name="downloadImage"
                     value="resources/images/cert.gif"/>
  <renderer-property name="downloadText"
                     value="certificate.download"/>
</renderer>

The generated download URIs are “binaryReader/cert_0.cer?…​”, “binaryReader/cert_1.cer?…​” etc.

HTML/JavaScript Rendering

The HTML code snippet is defined in binary/certificates.htm.It invokes a JavaScript function of the certs variable in documentFuncs.js.

Java Renderer Classes

This section provides information about Java Renderer classes.

DownloadRenderer

The renderer generates a JavaScript representation of URIs to download a user’s photos or certificates (or any other binary attribute of any other entry).It sets the following property that can be evaluated by JavaScript code in a corresponding HTML renderer snippet:

  • value - A JavaScript array with the download URIs for the binary attribute values.

Each download URI includes:

  • The servlet path of the binary reader servlet.

  • Extra path information composed of a prefix, a dash, the value’s index and an extension. It serves as a proposal for the file name when the user saves the binary attribute to a file on the client.

  • Request parameters:

  • The entry DN.

  • The name of the binary attribute.

  • The index of the attribute value, starting with 0.

  • The value for the HTTP Content-Type header to be used when sending the binary data to the browser. It serves to tell the browser that the transferred binary data represent a photo, a certificate, or whatever.

The request parameters are encoded based on UTF-8.

A download URI can, for example, be assigned to the src attribute of an image tag, the href attribute of a link tag, or to the JavaScript property window.location.href.

Properties

The following table lists the download renderer properties:

Name Value

servletPath

The servlet path of the binary reader servlet as configured in web.xml.

contentType

The value for the HTTP Content-Type header used when downloading a binary property value to the client.

prefix

The extra path information prefix used when downloading a binary property value to the client.

extension

The extra path information extension used when downloading a binary property value to the client.

max

The maximum number of binary property values to process. Specify 0 for all values.

downloadEnabled

Whether to generate a value with download URIs (true), or to set the value to an empty array (false). The default is true. If the array is empty, the certificate renderer does not display download icons along with certificates.

Samples

If no binary attribute value is available, the renderer class sets the value property to an empty array:

[]

If one photo is available, the renderer class sets the value property to an array of length 1:

["binaryReader/photo_0.gif?dn=cn%3DAbele+Marc%2Cou%3DFinances%2Co%3DMy-Company%2Ccn%3DUsers%2Ccn%3DMy-Company&attr=photo&index=0&contentType=image%2Fgif"]

X509CertificateRenderer

The renderer generates a JavaScript representation of a user’s (or any other object’s) certificates. It sets three properties that can be evaluated by JavaScript code in a corresponding HTML renderer snippet:

  • labels - A JavaScript array with the labels of the fields returned per certificate

  • certificates - A JavaScript array whose items are again arrays. Each item array lists the component values for a single certificate.

  • value - A JavaScript array with the download URIs for the certificates (see section “DownloadRenderer”).

Properties

The class supports the following properties in addition to the properties of the DownloadRenderer:

Name Value

attributes

A comma-separated list of field names whose values are to be returned per certificate. The fields are returned in the same order as listed here. See the table below for available field names.

For details on the fields, see the Java documentation of class java.security.cert.X509Certificate.

dateFormat

The requested format for dates. To get localized dates, provide the message key of a date format. See the Java documentation of class java.text.SimpleDateFormat for details on date formats.

Default: MM/dd/yyyy z

dnFormat

The requested format for DNs. For details, see the Java documentation class javax.security.auth.x500.X500Principal.

Default: RFC1779

messagePrefix

The message prefix for the labels to be returned. The label’s message key is the concatenation of the prefix, a dot and the field name (for example, certificate.issuerDN).

Default: certificate

timeZone

The requested time zone for dates. Note that your users may work in different time zones.

Default: The local time zone of the Web server

Certificate Field Names

See the Java documentation of class java.security.cert,X509Certificate for details on the listed Java methods.

Name Java-script Type Java Method / Notes

basicConstraints

String

X509Certificate.getBasicConstraints()

certificate

String

X509Certificate.toString()

encoded

String

X509Certificate.getEncoded()

issuerDN

String

X509Certificate.getIssuerX500Principal().getName(format)

Formatted according to renderer class property dnFormat.

issuerUniqueID

String

X509Certificate.getIssuerUniqueID()

keyUsage

String

X509Certificate.getKeyUsage()

notAfter

String

X509Certificate.getNotAfter()

Formatted according to renderer class properties dateFormat and timeZone.

notAfterMs

Number

X509Certificate.getNotAfter().getTime()

Number of milliseconds since January 1, 1970, 00:00:00 GMT. Can be used to display the date according to the end user’s time zone.

notBefore

String

X509Certificate.getNotBefore()

Formatted according to renderer class properties dateFormat and timeZone.

notBeforeMs

Number

X509Certificate.getNotBefore().getTime()

Number of milliseconds since January 1, 1970, 00:00:00 GMT. Can be used to display the date according to the end user’s time zone.

publicKeyAlgorithm

String

X509Certificate.getPublicKey().getAlgorithm()

publicKeyEncoded

String

X509Certificate.getPublicKey().getEncoded()

publicKeyFormat

String

X509Certificate.getPublicKey().getFormat()

serialNumber

String

X509Certificate.getSerialNumber()

sigAlgName

String

X509Certificate.getSigAlgName()

sigAlgOID

String

X509Certificate.getSigAlgOID()

sigAlgParams

String

X509Certificate.getSigAlgParams()

signature

String

X509Certificate.getSignature()

subjectDN

String

X509Certificate.getSubjectX500Principal().getName(format)

Formatted according to renderer class property dnFormat.

subjectUniqueID

String

X509Certificate.getSubjectUniqueID()

TBSCertificate

String

X509Certificate.getTBSCertificate()

type

String

X509Certificate.getType()

valid

Boolean

X509Certificate.checkValidity()

true if the certificate is currently valid, false otherwise

version

String

X509Certificate.getVersion()

Configuration in web.xml

This section provides information about configuration in web.xml.

The Binary Reader Servlet

The binary reader servlet processes requests for binary data.It delegates the task to read the data from the LDAP directory to the JSP /WEB-INF/jsp/controller/binary/default.jsp.The path to the JSP must be configured here.There should be no need to customize the JSP.

Definition

<servlet>
	<servlet-name>BinaryReaderServlet</servlet-name>
	<servlet-class>
		siemens.dirxjsp.servlet.BinaryReaderServlet
	</servlet-class>
	<init-param>
		<param-name>JspPath</param-name>
		<param-value>
			/WEB-INF/jsp/controller/binary
		</param-value>
	</init-param>
</servlet>

Mappings

The mapping defines the servlet path for the binary reader servlet.

<servlet-mapping>
	<servlet-name>BinaryReaderServlet</servlet-name>
	<url-pattern>/binaryReader/*</url-pattern>
</servlet-mapping>

The Binary Request Filter

The binary request filter is a variant of the request filter used for all other Web Center requests. The only difference is that the filter itself takes care of correct request parameter decoding. The request encoding must be UTF-8 since the DownloadRenderer class encodes request parameters based on this encoding.

Definition

<filter>
	<filter-name>BinaryRequestFilter</filter-name>
	<display-name>Binary Request Filter</display-name>
	<description>Binary Request Filter</description>
	<filter-class>
    siemens.dirxjsp.core.application.RequestFilter
</filter-class>
	<init-param>
		<param-name>CleanUpEnabled</param-name>
		<param-value>false</param-value>
	</init-param>
	<init-param>
		<param-name>RequestSyncEnabled</param-name>
		<param-value>true</param-value>
	</init-param>
	<init-param>
		<param-name>RequestEncoding</param-name>
		<param-value>utf-8</param-value>
	</init-param>
	<init-param>
		<param-name>IgnoreLocale</param-name>
		<param-value>true</param-value>
	</init-param>
	<init-param>
		<param-name>DecodeRequestParameters</param-name>
		<param-value>true</param-value>
	</init-param>
</filter>

Mappings

The filter must be mapped to all requests served by the binary reader servlet.

<filter-mapping>
	<filter-name>BinaryRequestFilter</filter-name>
	<url-pattern>/binaryReader/*</url-pattern>
</filter-mapping>

The AddHeaderFilterForDownloads Filter

The filter is used to direct the browser to keep downloaded photos (and other binary attributes) in its cache for a period of time. This action prevents the browser from downloading a photo whenever the user clicks the download icon or hovers over the photo thumbnail.

The default caching period is 10 minutes (600 seconds).

Definition

<filter>
	<filter-name>AddHeaderFilterForDownloads</filter-name>
	<display-name>
    Add Header Filter for Downloads
</display-name>
	<description>
    Adds headers to HTTP response when downloading files
</description>
	<filter-class>
    siemens.dirxjsp.core.application.AddHeaderFilter
</filter-class>
	<init-param>
		<param-name>Expires-Header</param-name>
		<param-value>http/1.*:Expires:now+600</param-value>
	</init-param>
</filter>

Mappings

The filter must be mapped to all requests served by the binary reader servlet.

<filter-mapping>
	<filter-name>AddHeaderFilterForDownloads</filter-name>
	<url-pattern>/binaryReader/*</url-pattern>
</filter-mapping>

Approving Photos and Certificates

Web Center supports the approval of photos and certificates in request workflows and tickets.An approver can approve or reject an assignment, but he may not assign a different photo or certificate.

For example, if modification approval is activated for photos and a user assigns a photo to another one, a request workflow is started to let some approvers approve the assignment.Or if modification approval is activated for certificates and a user assigns one or more certificates to another one with a due date, a ticket is created and a workflow to approve the assignment is started.

You cannot assign a photo or certificate to an object in an enterAttributes activity of a request workflow.But if you manage somehow to assign a photo or certificate in an automatic activity you can let some approvers approve the assignment in a later approval activity of the same workflow.Just add the attribute name (like photo or userCertificate) to the attributes list on the parameters page of the activity.

Modification Approval

The renderers for binary attributes on modification approval pages are defined in file WEB-INF/config/workflows/modificationApproval/forms-config.xml:

<form-bean name="approveUserModificationActivityForm">
  …
  <form-property name="userCertificate"
        type="java.lang.Object[]"
        readonly="true"
        fieldRenderer="certificates"
        rendererProperties="downloadEnabled:false"
	  y="+1"/>
  <form-property name="jpegPhoto"
        type="byte[]"
        fieldRenderer="photo"
        readonly="true"
        y="+1"/>
  <form-property name="photo"
        type="java.lang.Object[]"
        fieldRenderer="photos"
        readonly="true"
        y="+1"
        spanX="4"
        hideOldIfEmpty="true"/>

  • The form property attribute readonly must be set to true.

  • The property type depends on whether the property is single- or multi-valued. Use type byte[] for single-valued properties, type java.lang.Object[] for multi-valued properties.

  • You can have the certificate renderer hide download icons by setting its property downloadEnabled to false.

  • New and old values of the last attribute photo are displayed below each other due to spanX="4". If the attribute does not have any old value, the label “Old value” is not displayed due to hideOldIfEmpty="true".

Creation Approval

The renderers for binary attributes on all other approval pages are defined in file WEB-INF/config/defaultRenderer.properties:

jpegphoto       = photo
#jpegphoto      = photos
photo           = photos
#photo          = documents
usercertificate = certificates

  • The list maps property names to renderer identifiers.

  • Use lower-case property names.

  • Usually, all approval pages use the same renderer for a property. The only choice is to assign renderers per object class, for example

    photo         = photos
photo@dxruser = documents