# XINA Struct Export

The XINA Struct Export command line utility processes archive files for a specified time range to produce data products for XINA's Export Tasks. There are 2 suppported archive file formats: `xbin` and `xpf`. If the archive file is in the `xpf` format, processing is delegated to a mission specific tool. See the [Struct Extract Interface](https://wiki.xina.io/books/structured-data-standards/page/struct-extract-interface) that describes the interface the tool must implement. Available data products include:
  - Full resolution mnemonic data with a configurable format
  - Mnemonic data statistics
  - Configurable plots of data
  - Limit Report
  - Events
  - Log file

### Arguments

| Name | Req | Description | Default |
|-|-|-|-|
| cache |  | Cache directory path. Used for any persistent caching across tasks for optimization purposes. | |
| cancellation | | Path to the cancellation file for detecting cancel requests. | |
| conf | ✓ | File path to the JSON config containing the export parameters. | |
| env | ✓ | File path to the JSON environment file which defines environment parameters such as project specific paths. | |
| extract | | Overrides the path provided in the environment file to the [struct_extract](https://wiki.xina.io/books/structured-data-standards/page/struct-extract-interface) app. Only used if the archive format is `xpf`. | |
| help | | Print available options. | |
| host | | XINA Tunnel host. | `"localhost"` | 
| port | | XINA Tunnel port. | `41746` |
| import | ✓ | Import directory path. Files that need to be imported will be placed here. `struct_export` is responsbile for generating the corresponding import action file but `xina-run` will perform the actual importing. | |
| log | ✓ | File path that log events will be written to. | |
| out | ✓ | Ouptut directory path. Files placed here will be uploaded and accessible directly from the Task interface (e.g. notifications panel). | |
| pkt_models | | Models to use packet time by default. **[TBD Remove]** | |
| plot | ✓ | Overrides the path provided in the environment file to the app that generates plot PDFs. | |
| post | ✓ | Post directory path (for post-import outputs) e.g. uploading log files to the Task record. | |
| python | ✓ | Overrides the path to the Python executable used by the plot app provided in the environment file. | |
| task | ✓ | File path to the JSON file containing info about the Task. | |
| temp | ✓ | Temp directory path for storing temporary files during execution. For example, zipped archives are unzipped to this directory for processing. | |



### conf

The below table describes the available fields in the `conf` JSON file and is used to control how data should be exported.

| Name | Type | Req | Description | Default |
|-|-|-|-|-|
| model | `utf8text `   | ✓ | Path of model to export data from e.g. `moma.fm` | |
| start | `instant(us)` | ✓ | Start time of data to export. May be provided as a Unix timestamp in microseconds (e.g. `1738781947000000`) or an ISO 8601 formatted string (e.g. `2024-06-12T00:00:00Z`). | 
| end   | `instant(us)` | ✓ | End time of data to export. May be provided as a Unix timestamp in microseconds (e.g. `1738781947000000`) or an ISO 8601 formatted string (e.g. `2024-06-12T00:00:00Z`). | 
| ueid  | `UUID` | 	 | Event UUID of interval if the export was requested for an interval. The event's start and end time will be used instead of `start` and `end`.| 
| disable_filter| `boolean` || If `true`, does not apply the filters defined in `data_conf`. This is useful if you want to export an existing profile that has filters, but don't want to apply the filters. | false |
| copy  | `boolean`   || If true, the zip file will be uploaded and available from the Task UI. | false
| label | `utf8text`   || The text that will be used to name the files and final zip file. The format will be like `2024_06_12_00_00_00_2024_06_12_00_20_00_profile_label` | 
| profile | `utf8text ` || The name of the Profile if the export was generated from one. If provided, then the Profile's `plot_conf` and `data_conf` will be used. | 
| auto_conf | `struct_auto_conf`  | | The `struct_auto_conf` that triggered the export. Only provided if the export was auto generated. | 
| plot_conf | `struct_plot_conf`  || The plot configuration used to generate the plot PDF. See [plot format](https://wiki.xina.io/books/oci-user-guide/page/export-plot-configuration-json-format). An empty object i.e. `{}` can be provided to generate the default plot configuration. If not provided, then plots will not be generated. |  One mnemonic per plot, one plot per page, sorted by `mn_id` in ascending order.
| data_conf | `struct_data_conf`  | | See [struct_data_conf](https://wiki.xina.io/link/170#bkmrk-struct_data_conf-jso) | 
| multi |  `boolean`  || **[TBD REMOVE - Not currently supported]** Has extract process all archives at once. This was added for performance reasons since loading the mnem def is slow. | 

**Example conf:**

_Note: The plot_conf was truncated for brevity._

This example performs an export with fields provided directly in the `conf` object.

```json
{
  "model": "oci.fm",
  "label": "test",
  "start": 1718150400000000,
  "end": "2024-06-12T00:20:00Z",
  "ueid": null,
  "copy": true,
  "plot_conf": {
    "trend_series": [
      "avg"
    ],
    "pages": [
      {
        "plots": [
          {
            "title": "OCI Pri Power (15A)",
            "mnemonics": [
              "PSE.OM1.OCI_PRI_CURR"
            ]
          },
          {
            "series": [
              {
                "mnemonic": "oci.dau.ddc.FPGA.CcdOpMode",
                "plot_options": {
                  "color": "k"
                }
              }
            ]
          }
        ]
      }
    ]
  },
  "data_conf": {
    "limit": false,
    "ids": "@#[42316,42318-42322,43255,44243,45140,45187-45210,45233-45236,45238,45240,45241,45245,45247,45248,45259,45260,45265-45268,45270,45272,45273,45277,45279,45280,45291,45292,45442,45444,45446,45448,45450,45452,45454,45460,45462,45472,45538,45540,45542,45544,45546,45548,45550,45556,45558,45568,51908,51910,64097,64109,64111,64113,64115,66333,66341,66349,66357,66365,66373,66381,67536,67537,69019,69024-69026,69031,69032,69729,77534,77570,77696]sci",
    "dis": false,
    "fill": false,
    "columns": {
      "ts_utc_iso": true
    },
    "join": true,
    "pkt": true
  }
}
```

This example performs an export for an existing [Profile Definition](https://wiki.xina.io/link/170#bkmrk-profile-definitions). The `data_conf` and `plot_conf` objects will be retrieved from the `OPS_FLT_OCI_SDS` profile.

```json
{
  "model": "oci.fm",
  "profile": "OPS_FLT_OCI_SDS",
  "label": "test",
  "start": 1718150400000000,
  "end": "2024-06-12T00:20:00Z",
  "ueid": null,
  "copy": true,
}
```