---
id: codecs--asn1-encoder-plugin
title: "ASN.1 encoder"
summary: "Encodes typed records into an ASN.1 BER file (for example telecom CDR files). Flow types are generated from an ASN.1 module definition, the same way the ASN.1 decoder does it; every record received on `Input` is encoded and appended to the current file, which is emitted on `Output`."
audience: user
keywords: "input, output, asndefinition, roottypename, encoding, mode, maxdepth, framing, maxfileopentime, fileextension, releaseidentifier, releaseidentifierextension, versionidentifier, tsnumber, nodeipaddress, filesequencestart, batchscope"
---
# ASN.1 encoder

Encodes typed records into an ASN.1 BER file (for example telecom CDR files). Flow types are generated from an ASN.1 module definition, the same way the ASN.1 decoder does it; every record received on `Input` is encoded and appended to the current file, which is emitted on `Output`.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Input | input | generated root type (`<flow namespace>.<RootType>`) | One record per call. |
| Output | output | `Viaducta.Plugins.Files.Types.ViaFileStream` | The encoded file, emitted when its batch ends, per record without a batch, or when the file reaches `MaxFileOpenTime` (records without a batch). `Name` is `CDR-<yyyyMMdd-HHmmss>-<file sequence, 10 digits><ext>` (TS 32.297) or `ASN-<yyyyMMdd-HHmmss>-<file number since start, 6 digits><ext>` (raw), UTC. |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `AsnDefinition` | ASN.1 module (editor) | | The module text. Triggers reconfigure. |
| `RootTypeName` | type (type selector) | | Full name of the record type. Set automatically by reconfigure; triggers reconfigure. |
| `Encoding` | dropdown: `BER` | `BER` | BER with definite lengths. |
| `Mode` | dropdown: `1` STRICT, `2` RELAXED | `2` | `1` stops on the first record that can't be encoded; `2` logs it and skips the record. |
| `MaxDepth` | integer (1-9999) | `99` | Maximum nesting depth of a record, protects against cyclic object graphs. |
| `Framing` | dropdown: `NONE`, `TS32297` | `NONE` | `NONE` writes concatenated TLV records; `TS32297` writes a 3GPP TS 32.297 CDR file. |
| `MaxFileOpenTime` | integer, ms (0-86400000) | `0` | Records without a batch only: `0` = a file per record; otherwise the records go into one file emitted once it has been open (since its first record) this long. |
| `FileExtension` | text | `.ber` | Extension set on the produced `ViaFileStream`. |
| `ReleaseIdentifier` | integer (0-7) | `7` | TS 32.297 release identifier for the file and CDR headers. `7` writes `ReleaseIdentifierExtension`. |
| `ReleaseIdentifierExtension` | integer (0-255) | `0` | TS 32.297 release identifier extension. |
| `VersionIdentifier` | integer (0-31) | `0` | TS 32.297 version identifier. |
| `TsNumber` | integer (0-31) | `0` | TS 32.297 TS number in the CDR header (for example 6 = TS 32.250, 7 = TS 32.251). |
| `NodeIpAddress` | text | | TS 32.297 IP address of the generating node (IPv4 or IPv6). |
| `FileSequenceStart` | integer | `0` | TS 32.297 file sequence number of the first file after start, incremented per file. |
| `BatchScope` | batch scope selector | empty | Which batch goes into one file. Empty = the closest batch producer upstream (e.g. the records of one decoded file). A component id of a batch producer upstream = the batches of that producer. `None` = ignore batches (see `MaxFileOpenTime`). |

## Values

The encoder accepts the values the ASN.1 decoder produces, so decoded records can be re-encoded unchanged:

| ASN.1 | Value |
|---|---|
| `INTEGER`, `INTEGER64`, `BIGINT` | any integer type, `BigInteger`, integral string |
| `ENUMERATED` | generated enum, integer, or the item name |
| `BOOLEAN` | `bool` |
| `NULL` | `bool?`: `true` = present, `null`/`false` = absent |
| `OCTET STRING` | hex string (decoder format) or `byte[]` |
| `TBCD-STRING` | digit string (`0-9 * # a b c`, odd length padded with `F`) or `byte[]` |
| `BIT STRING` | `BitArray`, `bool[]`, `byte[]` or a `0`/`1` string |
| character strings | `string`, character set is validated |
| `GeneralizedTime`, `UTCTime` | `DateTime` (`Unspecified` = UTC, as decoded) or `DateTimeOffset` |
| `REAL` | `double` |
| `CHOICE` | `ActiveChoice` names the alternative; when empty exactly one alternative must be set |
| `SEQUENCE OF`, `SET OF` | list, `SIZE` constraints are checked |

## Behaviour

- Reconfigure (changing `AsnDefinition`) generates the flow classes and picks the first `SEQUENCE`/`SET`/`CHOICE` no other type refers to as the root, written to `RootTypeName` and set on `Input`.
- Members are written in definition order (`SET` members too, BER doesn't sort). Missing mandatory members, an unset `CHOICE` and `SIZE` violations fail the record with the member path in the message.
- Tagged members are IMPLICIT unless declared `EXPLICIT` or of a `CHOICE` type, which matches how the decoder reads them.
- Records in a batch (see `BatchScope`) are encoded into the file of their batch. When the whole batch has been processed the file is emitted with the metadata of the last record; it stays in the batch, so batch consumers behind it (Write file, ...) include it before they commit. When the batch failed the file is discarded (with TS 32.297 its file sequence number is used up). In `STRICT` mode a record that can't be encoded fails the batch. `MaxFileOpenTime` doesn't split batches.
- Records without a batch (or `BatchScope` `None`): with `MaxFileOpenTime` `0` every record is emitted as a file of its own; otherwise they go into one shared file emitted by `MaxFileOpenTime`.
- TS 32.297: CDR count, file length and timestamps (local time) are filled in when the file is closed; closure reason is `0` normal or `2` open time limit. Routing filter and private extension are empty.

## Notes

- Only `BER` (definite length). DER/CER/PER/OER are rejected at start.
- A TS 32.297 CDR is limited to 65535 bytes (16 bit length field).
- The file sequence number is not persisted, it restarts at `FileSequenceStart` on every flow start.
- On flow stop, files of open batches are discarded (the batch is aborted) and records of the shared file are dropped with a warning.

## Example

```json
{ "Encoding": "BER", "Mode": "2", "Framing": "TS32297", "MaxFileOpenTime": 60000, "ReleaseIdentifier": 7, "ReleaseIdentifierExtension": 8, "TsNumber": 6, "NodeIpAddress": "10.1.2.3", "RootTypeName": "MyFlow.CallDataRecord" }
```

Data mapper → **ASN.1 encoder** → File writer