# Julian Date Converter

An OutSystems Client Action JavaScript implementation for converting multiple Julian date formats into a UTC ISO 8601 date string.

## Features

- Supports astronomical Julian Dates (`JD`)

- Supports Julian Day Numbers (`JDN`)

- Supports ordinal date format (`YYYYDDD`)

- Supports two-digit ordinal date format (`YYDDD`)

- Performs strict input validation

- Handles leap years correctly

- Returns validation status and a descriptive error message

- Produces a UTC ISO 8601 result compatible with OutSystems text handling

- Does not use dynamic code execution such as `eval`

## Supported Formats

| Format | Description | Example | Result |

|---|---|---:|---|

| `JD` | Astronomical Julian Date, including fractional days | `2451545.0` | `2000-01-01T12:00:00Z` |

| `JDN` | Integer Julian Day Number | `2451545` | `2000-01-01T12:00:00Z` |

| `YYYYDDD` | Four-digit year followed by day of year | `2024123` | `2024-05-02T00:00:00Z` |

| `YYDDD` | Two-digit year followed by day of year | `24123` | Depends on `YearBase` |

`DDD` is the day of the year. It ranges from `001` to `365`, or `366` during a leap year.

## OutSystems Action Parameters

### Input Parameters

| Name | Data Type | Required | Description |

|---|---|---:|---|

| `JulianNumber` | Text | Yes | The Julian value to convert. Leading and trailing spaces are ignored. |

| `Format` | Text | Yes | The input format: `JD`, `JDN`, `YYYYDDD`, or `YYDDD`. Spaces, hyphens, and underscores are ignored when matching the format. |

| `YearBase` | Integer | Only for `YYDDD` | The century used to expand the two-digit year. Examples: `1900`, `2000`, or `2100`. |

### Output Parameters

| Name | Data Type | Description |

|---|---|---|

| `Result` | Text | A UTC ISO 8601 date string, for example `2024-05-02T00:00:00Z`. Empty when conversion fails. |

| `IsValid` | Boolean | `True` when conversion succeeds; otherwise `False`. |

| `ErrorMessage` | Text | Describes the validation or conversion failure. Empty when conversion succeeds. |

## Configuration

Create a Client Action containing a JavaScript node. Add the input and output parameters listed above, then paste the JavaScript implementation into the node.

The recommended type for `Result` is `Text` because the JavaScript node returns an ISO 8601 string. Convert it to an OutSystems `DateTime` using the appropriate OutSystems conversion action when required by the consuming logic.

## Usage Examples

### Astronomical Julian Date

```text

JulianNumber = 2451545.0

Format       = JD

YearBase     = 0

Result       = 2000-01-01T12:00:00Z

IsValid      = True

```

### Julian Day Number

```text

JulianNumber = 2451545

Format       = JDN

YearBase     = 0

Result       = 2000-01-01T12:00:00Z

IsValid      = True

```

### Four-Digit Ordinal Date

```text

JulianNumber = 2024123

Format       = YYYYDDD

YearBase     = 0

Result       = 2024-05-02T00:00:00Z

IsValid      = True

```

### Two-Digit Ordinal Date

```text

JulianNumber = 24123

Format       = YYDDD

YearBase     = 2000

Result       = 2024-05-02T00:00:00Z

IsValid      = True

```

## Validation Rules

- `JD` accepts a valid decimal number and may contain a fractional component.

- `JDN` accepts digits only and does not accept decimal values.

- `YYYYDDD` must contain exactly seven digits.

- `YYDDD` must contain exactly five digits.

- Ordinal dates must contain a valid day of year for the selected year.

- Leap years allow day `366`; non-leap years do not.

- `YearBase` must be a valid century, such as `1900` or `2000`.

- Invalid values return `IsValid = False`, an empty `Result`, and a populated `ErrorMessage`.

## Important Notes

### JDN Time Convention

An integer Julian Day Number represents noon UTC, not midnight. Therefore, `2451545` converts to `2000-01-01T12:00:00Z`.

### YYDDD Ambiguity

`YYDDD` does not contain enough information to determine the century. For example, `24123` could refer to 1924, 2024, or another century. Always supply `YearBase` explicitly.

### UTC Output

The result is always returned in UTC and ends with `Z`. This avoids differences caused by the user’s local time zone or the server time zone.

## Security Considerations

This implementation uses strict format validation and does not execute input as code. However, Client Action JavaScript runs in the browser and can be inspected or modified by the end user.

Do not rely on this client-side validation for:

- Authorization decisions

- Payment or financial calculations

- Security rules

- Database integrity

- Other business-critical operations

Repeat all important validation in a Server Action before saving or processing the result.

## Error Handling Example

After calling the action:

```text

If IsValid = True:

    Use Result

Else:

    Display ErrorMessage

```

## Compatibility

The implementation uses standard browser JavaScript APIs available in modern browsers supported by OutSystems. The output is plain ISO 8601 text and can be logged, displayed, stored as text, or converted to an OutSystems `DateTime`.