# Timestamp

## Availability

[\[SINCE Orbeon Forms 2025.1.1\]](https://github.com/orbeon/orbeon-forms-doc/blob/master/release-notes/orbeon-forms-2025.1.1.md)

## What it does

The timestamp component is a readonly form control able to show an instant in time, with date, time, and timezone. It does not support user input: instead, it is meant to show a value, for example the last modified date of a form.

<figure><img src="/files/HhIPcOECmJOKmyYgU8TF" alt="" width="242"><figcaption><p>Timestamp component</p></figcaption></figure>

## Usage

From Form Builder, insert the Timezone control from the toolbox.

## Datatype

`fr:timestamp` must be bound to the `xs:dateTime` type.

In addition, it expects a value with a timezone offset or the suffix `Z` for UTC. For example these are valid values:

* `2024-06-30T12:34:56Z`
* `2024-06-30T12:34:56+02:00`

The following is not a valid value, because it doesn't have a timezone offset and represents a *local time*:

* `2024-06-30T12:34:56`

In particular the following functions return a value with a timezone offset:

* `current-dateTime()`
* [fr:modified-dateTime()](/xforms/xpath/extension-functions/extension-form-runner.md#frmodified-datetime)
* [fr:created-dateTime()](/xforms/xpath/extension-functions/extension-form-runner.md#frcreated-datetime)

In particular, these can be used with:

* [Formulas](/form-builder/formulas.md): see the "Initial" or "Calculated Value" formulas
* [Action syntax](/form-builder/advanced/services-and-actions/actions-syntax.md): see the `<fr:control-setvalue>` action
* [simple process](/form-runner/advanced/buttons-and-processes/actions-form-runner/actions-form-runner-control-setvalue.md): see the `control-setvalue()` action

*NOTE: While the timezone offset in the value can have meaning, its main function is to refer to an absolute point in time (or instant). That timezone offset is not used for formatting the value to the user, see below.*

## Timezone

### Client-side

When displaying a timestamp, the value is converted to the current user's local timezone as provided by the web browser.

### Server-side

When rendering on the server, for example when producing a PDF file, the value is converted to a timezone provided on the server, as follows:

* `user.timezone` property, if set, for example to `Europe/Paris`
* `oxf.fr.default-timezone` property, if set
* UTC timezone, if none of the above is set

## Configuration

### Date format

The format by default is done with the following property:

```xml
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.timestamp.output-format" 
    value="[M]/[D]/[Y] [h]:[m]:[s] [P,*-2] [ZN]"/>
```

The above includes:

* a date format (see the [Date](/form-runner/component/date.md) control)
* a separator string (here a space)
* a time format (see the [Time](/form-runner/component/time.md) control)
* a timezone format

The timezone formats are the following:

| Symbol | Meaning                                 |
| ------ | --------------------------------------- |
| `[Z]`  | Short offset, for example `+02:00`      |
| `[z]`  | Long offset, for example `GMT+02:00`    |
| `[ZN]` | Timezone short name, for example `CEST` |

The format described above allows placing the date or time first, and choosing the middle separator.

As of Orbeon Forms 2025.1.1, there is no UI to specify the date format, but the `output-format` attribute on the `<fr:timestamp>` component allows overriding the default format on a per-component basis.

## XForms usage

You use the timestamp component:

```xml
<fr:timestamp ref="signature-dateTime">
  <xf:label>Signature date and time</xf:label>
</fr:timestamp>
```

## See also

* [Date](/form-runner/component/date.md)
* [Time](/form-runner/component/time.md)
* [Dropdown Date](/form-runner/component/dropdown-date.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.orbeon.com/form-runner/component/timestamp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.