# Convert Engine (Engine `cnv`)

This engine provides jobs for converting image files.

* [cnv.AddAnnotations](cnv.md#cnv.AddAnnotations)
* [cnv.ConvertDocument](cnv.md#cnv.ConvertDocument)
* [cnv.CreateSlide](cnv.md#cnv.CreateSlide)
* [cnv.GetExifData](cnv.md#cnv.GetExifData)
* [cnv.GetIcons](cnv.md#cnv.GetIcons)
* [cnv.GetPageCount](cnv.md#cnv.GetPageCount)
* [cnv.GetPictureInfos](cnv.md#cnv.GetPictureInfos)
* [cnv.GetRendition](cnv.md#cnv.GetRendition)

## Undocumented Endpoints

The following jobs are offered by the enaio® server but are not currently described in this documentation:

* `cnv.CheckMimeType`
* `cnv.CheckPDFA`
* `cnv.ConvertDocToPDF`
* `cnv.GetConversionCapabilities`
* `cnv.SplitDocument`

<a id="cnv.AddAnnotations"></a>

## cnv.AddAnnotations

This job burns annotations (slides) into one or more image files.

> **Note:** The job respects the access rights on the annotations.
For example, only the personal slide of the logged-in user is displayed.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | `0` = The input files are deleted; temporary copies are created for unchanged input files. +<br>`2` = Input files are not deleted; unchanged input files are written back to the output list. |
| `[AnnotationID]` | INT | No | Specific ID of an annotation to be burned into the input file(s). |
| `[dwObjectID]` | INT | No | ID of an object to be burned into the input file(s).<br>`AnnotationID` can be passed, `dwObjectID` must be passed for this. |

### Input Files

| Name | Description |
|---|---|
| `File List` | Paths and names of files to be annotated. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `nProcessed` | INT | — | Number of image files that were annotated. |
| `sAnnotationIDs` | STRING | — | Comma-separated list of annotation IDs that were burned in. |

### Output Files

| Name | Description |
|---|---|
| `File List` | Path and name of the image file that was annotated, if annotations were present for this input file.<br>Otherwise, the input file is returned unchanged (see `Flags`).<br>The output format corresponds to the respective input file format. |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

<a id="cnv.ConvertDocument"></a>

## cnv.ConvertDocument

This job converts one or more document files of the specified format into one or more PDF or TIFF files.
Accordingly, arbitrary input and output formats are also possible depending on the respective configurations.

The following classes of transformations are possible:

* Bitmap format (JPG, TIF) → PDF
* Singlepage TIFF → Multipage TIFF
* ASCII-COLD (`.asc`) → TIFF / PDF
* XSL:FO (`.fo`, `.xml`) → PDF
* Office documents (`.ps`, `.doc`, `.xls`, `.ppt`, `.txt`, `.rtf`, `.pdf`, `.ima`) → PDF

For bitmap formats and ASCII-COLD documents, `Flags` can be used to control whether a separate output file should be created for each input file or whether the individual pages should be consolidated into a single document.

> **Note:** Format specifications are expected in lowercase (e.g. `pdf` instead of `PDF`).

> **Note:** If `ObjectID` and `ObjectType` are passed, conversion is performed via OS RenditionPlus (`___ren.bat`).
The target format can then additionally be `SLIDE` for preview generation or `TXT` for text recognition.
The size of the generated preview can be specified with `Height` and `Width`.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | `0` = one output file is created for each input file +<br>`1` = all input files are written to one output file +<br>`2` = one output file is created for each input file; temporary files created by the server are not deleted +<br>`3` = all input files are written to one output file; temporary files created by the server are not deleted |
| `SourceFormat` | STRING | Yes | Format of the source file |
| `DestinationFormat` | STRING | Yes | Format to convert to |
| `[Timeout]` | INT | No | Maximum time in milliseconds that a conversion by external programs may take.<br>Considered for XSL:FO and office format conversions. |
| `AddAnnotations` | INT | Yes | `1` = public slides are burned in |
| `[ConvertEqualFormat]` | INT | No | Default `0`. If set to `1`, a conversion is attempted even if source and destination format are identical (e.g. PDF → PDF/A). |
| `[Watermark]` | INT | No | Default `0`. If set to `1`, a generated PDF document is provided with headers and footers.<br>Appearance and content are configured by the administrator.<br>See enaio® Administrator Guide → tab _Print Marking_. |
| `[dwObjectID]` | INT | No | Document object ID for use in watermarks.<br>Only relevant when `Watermark=1` and print watermarks are configured to output the document ID. |
| `[ProtectPDF]` | INT | No | Default `0`. If set, a generated PDF document is protected — printing and copying of text passages is then not possible. |
| `[ObjectID]` | INT | No | ID of the document (alternative to file list) |
| `[ObjectType]` | INT | No | Type of the object (alternative to file list) |
| `[Digest]` | STRING | No | Hash value of the document (only when passing `ObjectID`/`ObjectType`) |
| `[Height]` | INT | No | Height of the preview when destination format is `SLIDE` |
| `[Width]` | INT | No | Width of the preview when destination format is `SLIDE` |

### Input Files

| Name | Description |
|---|---|
| `[File List]` | Path and name of files to be converted (alternative to `ObjectID`/`ObjectType`) |

### Output Files

| Name | Description |
|---|---|
| `File List` | Path and name of converted file(s) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

See also: [cnv.CreateSlide](cnv.md#cnv.CreateSlide)

### Using XSL:FO

* For converting FO files (Formatting Objects), the Apache FOP processor must be installed.
This requires a Java runtime environment 1.6 or higher.
The path to the FOP batch file (Windows) or FOP shell script (Linux) must be stored in the registry via the Enterprise Manager.
Additionally, a timeout can be defined after which the conversion process is aborted.
* If an XML document is passed to FOP, an XSLT document must be passed as a second file in the input file list to transform the XML into an XSL:FO document.
* If images are to be included in the resulting PDF, they must be referenced in the XSL:FO file via a URL accessible to the application server.
* Only one FO or XML document can be processed per job.

.Example: [cnv.ConvertDocument](cnv.md#cnv.ConvertDocument) with XSL:FO (`SourceFormat: XML`, `DestinationFormat: PDF`, `Flags=0`)

1. Input file — XML file with arbitrary input information:
+
```xml
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<?xml-stylesheet type="text/xsl" href="example.fo"?>
<persons>
  <person age="42">Max Mustermann</person>
  <person age="37">Denise Musterfrau</person>
</persons>
```
2. Input file — XSL file for converting to an XSL:FO file:

```xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
  <xsl:template match="persons">
    <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
      <fo:layout-master-set>
        <fo:simple-page-master page-master-name="one" page-height="29cm" page-width="21cm"
                               margin-left="2cm" margin-right="2cm">
          <fo:region-body margin-top="50pt" margin-bottom="50pt"/>
        </fo:simple-page-master>
      </fo:layout-master-set>
      <fo:block text-align="center" font-size="24pt" font-weight="bold"
                lineheight="28pt" space-after="10mm">
        <xsl:apply-templates/>
      </fo:block>
    </fo:root>
  </xsl:template>
  <xsl:template match="person">
    ...
  </xsl:template>
</xsl:stylesheet>
```

<a id="cnv.CreateSlide"></a>

## cnv.CreateSlide

This job converts files and documents of JPG or TIF formats into a DIA file with the same format as the input file.
DIA files are highly compressed and serve as a preview of a document.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | `0` = a DIA output file is created +<br>`2` = a DIA output file is created; temporary files created by the server are not deleted |
| `[ObjectID]` | INT | No | ID of the document (alternative to file list) |
| `[ObjectType]` | INT | No | Type of the object (alternative to file list) |
| `[Page]` | STRING | No | Page number of the document (file list) for which the data should be retrieved.<br>Default: `1`; `All` for all pages. |

### Input Files

| Name | Description |
|---|---|
| [File list] | Path and name of the file in JPG or TIF format to be converted (alternative to `ObjectID`/`ObjectType`) |

### Output Files

| Name | Description |
|---|---|
| File list | Path and name of the converted DIA file(s) with format corresponding to the input file(s) |

### Return Value

(INT): 0 = Job successful, otherwise error code.

See also: [cnv.ConvertDocument](cnv.md#cnv.ConvertDocument)

<a id="cnv.GetExifData"></a>

## cnv.GetExifData

This job determines the EXIF data from the image files of a document.

> **Note:** Information (EXIF, DICOM, general data) is only determined for EXIF, JPEG, TIF, and DICOM files.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | `1` = do not delete the passed file list; `0` = delete (for client-side calls) |
| `[ObjectID]` | INT | No | ID of the document (alternative to file list) |
| `[ObjectType]` | INT | No | Type of the object (alternative to file list) |
| `[Page]` | STRING | No | Page number of the document (file list) for which the data should be retrieved.<br>Default: `1`; `All` for all pages. |

### Input Files

| Name | Description |
|---|---|
| [File list] | Paths and names of files whose data should be determined (alternative to `ObjectID`/`ObjectType`) |

### Output Parameters

The information is returned in the form `Leadtool-Name(Page number) value`.

Examples:

```text
CMNT_SZMAKE(1)   "Panasonic"
CMNT_SZMODEL(1)  "DMC-TZ10"
...
```

### Return Value

(INT): 0 = Job successful, otherwise error code.

<a id="cnv.GetIcons"></a>

## cnv.GetIcons

This job returns icons in GIF format.
This makes it possible to read custom icons, as used in the archive area and hit lists.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |
| `sIconIds` | STRING | Yes | Comma-separated list of icon IDs. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `sIconIds` | STRING | — | Comma-separated list of icon IDs in the same order as the output files. |

### Output Files

| Name | Description |
|---|---|
| File list | Path and name of icons in GIF format. |

### Return Value

(INT): 0 = Job successful, otherwise error code.

<a id="cnv.GetPageCount"></a>

## cnv.GetPageCount

This job determines the total page count from the image files of a document.

> **Note:** Determination is only performed for image and PDF documents.
If the total page count can be determined from all files in the list or the document, `FileCount` and `PageCount` are returned.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | `1` = do not delete the passed file list; `0` = delete (for client-side calls) |
| `[ObjectID]` | INT | No | ID of the document (alternative to file list) |
| `[ObjectType]` | INT | No | Type of the object (alternative to file list) |

### Input Files

| Name | Description |
|---|---|
| [File list] | Paths and names of files whose total page count should be determined (alternative to `ObjectID`/`ObjectType`) |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `FileCount` | INT | — | Number of files of the document (file list) |
| `PageCount` | INT | — | Total page count of all files of the document (file list) |

### Return Value

(INT): 0 = Job successful, otherwise error code.

<a id="cnv.GetPictureInfos"></a>

## cnv.GetPictureInfos

This job determines image information from the files of a document.

> **Note:** Determination is only performed for image and PDF documents.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | `1` = do not delete the passed file list; `0` = delete (for client-side calls) |
| `[ObjectID]` | INT | No | ID of the document (alternative to file list) |
| `[ObjectType]` | INT | No | Type of the object (alternative to file list) |
| `[Page]` | STRING | No | Page number of the document (file list) for which the data should be retrieved.<br>Default: `1`; `All` for all pages. |

### Input Files

| Name | Description |
|---|---|
| [File list] | Paths and names of files whose image information should be determined (alternative to `ObjectID`/`ObjectType`) |

### Output Parameters

The information is returned in the form `Infoname(Page number) value`.

For **image documents** the following values (INT) are returned:

| Parameter | Description |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| `InfoBits(N)` | Color depth | `InfoCompress(N)` | Compression type | `InfoFormat(N)` | Image format | `InfoIFD(N)` | IFD information | `InfoLayers(N)` | Number of layers | `InfoSizeDisk(N)` | File size on storage device | `InfoSizeMem(N)` | Memory size (uncompressed) | `InfoViewPerspective(N)` | Orientation | `InfoHeight(N)` | Image height in pixels | `InfoWidth(N)` | Image width in pixels | `InfoFileType(N)` | File type identifier | `InfoFileSuffix(N)` | File extension |
For **PDF files** the following values are returned:

| Parameter | Description |  |  |  |  |
|---|---|---|---|---|---|
| `InfoFormat(N)` | Document format | `InfoFileType(N)` | File type identifier | `InfoFileSuffix(N)` | File extension |
_(N = page number)_

### Return Value

(INT): 0 = Job successful, otherwise error code.

<a id="cnv.GetRendition"></a>

## cnv.GetRendition

This job performs a rendition for a document via a call using the file `___ren.bat`.

> **Note:** As destination format, `SLIDE` can be passed for preview generation.
With `Height` and `Width` the size of the preview to be generated can be specified.
Instead of `SLIDE`, `TXT` is also allowed as destination format for OCR.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ObjectID` | INT | Yes | ID of the document |
| `ObjectType` | INT | Yes | Type of the object |
| `Flags` | INT | Yes | `1` = do not delete the passed file list; `0` = delete (for client-side calls) |
| `DestinationFormat` | STRING | Yes | Format to which the file should be converted (see [cnv.ConvertDocument](cnv.md#cnv.ConvertDocument)) |
| `[Digest]` | STRING | No | Hash value of the document |
| `[Watermark]` | INT | No | Default `0`. If set to `1`, a generated PDF document will be provided with headers and footers.<br>Appearance and content is configured by the administrator.<br>See enaio® Administrator Guide, Chapter: _Print Identification_ tab. |
| `AddAnnotations` | INT | Yes | `1` = public slides are burned in |
| `[ProtectPDF]` | INT | No | Default `0`. If set, a generated PDF document will be protected — printing and copying of text passages will then not be possible. |
| `[SynchData]` | INT | No | Default `0` |
| `[Height]` | INT | No | Height of the preview for destination format `SLIDE` |
| `[Width]` | INT | No | Width of the preview for destination format `SLIDE` |

### Output Files

| Name | Description |
|---|---|
| File list | Path and name of the converted file(s) |

### Return Value

(INT): 0 = Job successful, otherwise error code.