Control-D Delivery Server Transformers and Transformations

Control-D Delivery Server uses two key modules to transform reports; transformers and transformations, which are critical for converting reports, such as AFP to PDF, and enables users to view, analyze, print, or distribute reports.

Transformer attributes control the entire transformation process and determine the input and output file paths of the report, the file type, and what transformation definitions to include when you transform a report.

However, transformations attributes are more precise and alter the document structure, layout, or appearance to meet specific business needs, and adhere to specific standards, such as add metadata, merge, or split documents, apply security measures, or reformat content to fit different layouts or devices. Transformations ensure that reports are user-friendly and tailored to exact requirements.

A Financial Services provider uses Control-D/WebAccess Server to view and transform their quarterly reports. The Control-D Delivery Server transformation process uses a transformer, which determines whether to convert a report from AFP format to PDF. The selected transformer includes transformation attributes, such as adds a background image, uses a TrueType font, widens the columns, and protects the reports with a password linked to the user's account number before you send them to clients. The Control-D Delivery Server automatically distributes reports on with the Distribution Monitor to the end user.

Transformation modules automatically appear when you install Control-D Delivery Server and includes the following inputs:

Configuring Control-D Delivery Server Transformers

Transformers determine the input and output file paths of the report, resource file paths, and what transformation definitions to include when you transform a report. Transformer default attributes are hard-coded in Control-D Delivery Server. You can override these hard-coded values and supply alternative values in the Transformer Configuration file.

This procedure describes how to configure the global Transformer in the Control-D Delivery Server, which enables you save transformers in a different location on your computer.

Begin

  1. From the Root directory, navigate to the following location:

    Definitions > Common > Transformer > Transformer Configuration

  2. Double-click Transformer Configuration.

    The Transformer Configuration window appears.

  3. For each field, define the required parameters, as described in Transformer Configuration Parameters.

Running Control-D Delivery Server Shell Transformations

Control-D Delivery Server enables you to use third-party external transformation components and uses one of the following application extensions, which triggers transformations from the third-party application.

  • Windows: bmc-ctd-si-shell-transformer.dll

  • UNIX: libbmc-ctd-si-shell-transformer.so

The Shell transformer, within these extensions reads data from the repository, duplicates it into temporary input and logical view files, manages parameters, executes macro substitutions, and configures settings. The shell transformer triggers an external program to transform the report when an error or a timeout, it issues an error message and deletes temporary files for system maintenance.

The PostScript to PDF transformer definition, Ps_D_2_Pdf_D_Ext, is an example of a third-party transformer.

Begin

  1. From the Root directory, navigate to the following location:

    Configurations > Distribution Server> Distribution_CTD_Delivery > Distribution Process > Shell Transformers

  2. From the Shell Transformers folder, right-click, and then click Add.

    The New Item window appears.

  3. In the Basic tab, do the following:

    1. In the Display Name field, define the new transformer name.

    2. In the From Extension field, determine the input file type.

    3. In the To Extension field, determine the output file type.

    4. In the Program field, type one of the following programs:

      • Windows: bmc-ctd-si-shell-transformer.dll

      • UNIX: libbmc-ctd-si-shell-transformer.so

  4. In the Advanced tab, in the Param field, type the following command, as described in Syntax:

    Command "%%IN%%" ["%%OUT%%"] ["%%LV%%"] [{%%RA_ATTRIBUTE_NAME%%}] [{%%AD_PARAM%%}] [si_pagebreak=page_break_symbol] [si_dateformat=date_and_time_format] [si_timeout=number_of_seconds] {si_cleanup=yes|no}] [parameters required by external transformer executable]

    You must enclose any command, macro, shell transformer, settings, or parameters contains one or more spaces in quotation marks.

    BMC recommends that you enclose the %%IN%%, %%OUT%%, and %%LV%% macro variables with quotation marks.

  5. Click Apply.

  6. Click OK.

  7. The configuration is complete.

Syntax

The following syntax structure defines an external transformer and its parameters in the Param field:

Command macros settings parameters

where

  • Command: Defines the full path to the executable file of the external transformer, which you must define the first. The rest of the macros, settings, and parameters appear in the required order to pass the data to the external transformer, as discussed in Command.

  • Macros: Defines the shell transformer macro variables. The actual values replace the macro variables and passes the variables to external transformer in the command line parameters, as discussed in Macros.

  • Settings: Defines the shell transformer settings, which the shell transformer uses, as discussed in Settings.

  • Parameters: Defines other parameters required by the external transformer.

Command

In the Command section the full path to the executable file of the external transformer appears. You must first type the file path in the Param field.

d:\Program Files\BMC\bin\Xreport property.exe

Type one of the following commands when you run a batch transformation:

  • cmd /c call batch_file_full_path parameters

    cmd /c call "d:\Program Files\BMC\test.bat" "%%IN%%" "%%OUT%%"

  • cmd /c "batch_file_full_path parameters"

    cmd /c " "d:\Program Files\BMC\test.bat" "%%IN%%" "%%OUT%%" "

Macros

The shell transformer determines macro variables and encloses them in paired %% (percent) symbols. The macro variables replace with the actual values, which passes to the external transformer in the command line parameters.

Shell transformer macro variables include the following:

  • %%IN%%: Full file path to the temporary input file.

    ctd_installation_dir/transformer/input/file_gen2ext_{unique name}.original_ext

  • (Optional) %%OUT%%: Full file path to the temporary output file.

    ctd_installation_dir/transformer/output/file_gen2ext_{unique name}.target_ext

  • (Optional) %%LV%%: Full file path to the temporary logical view text file.

    ctd_installation_dir/transformer/input/file_gen2ext_{unique name}_log_view

  • (Optional) One of the following RA_ATTRIBUTE_NAME macros replace each %%RA_ATTRIBUTE_NAME%:

    • RA_CATEGORY

    • RA_CHARS

    • RA_CLASS

    • RA_COPIES

    • RA_DECOLLATIONDATE

    • RA_DEST

    • RA_ENCODING

    • RA_FILEEXTENSION

    • RA_FORM

    • RA_FROMUSER

    • RA_JOBENDDATE

    • RA_JOBNAME

    • RA_JOBID

    • RA_JOBSTARTDATE

    • RA_LANGUAGE

    • RA_LINES

    • RA_LOCATION

    • RA_ORDERDATE

    • RA_ORIGINALENCODING

    • RA_PAGELISTMODE

    • RA_PAGES

    • RA_RECFM

    • RA_RECIPIENT

    • RA_REMARK

    • RA_REPORTNAME

    • RA_RESOURCESETID

    • RA_STATUS

    • RA_USERDEST

Settings

The following table describes the shell transformer settings, which you must determine in the Settings area. Each setting begins with: si_.

Parameter

Description

si_dateformat=%d/%m/%Y %H:%M

Determines date and time formats to replace all RA_…DATE macros.

You must enclose the entire si_dateformat setting in quotation marks when the setting contains a space, such as, "si_dateformat=%d/%m/%Y %H:%M".

Default: Use %d/%m/%Y %H:%M when the si_dateformat= setting does not appear.

si_pagebreak

Determines the symbol to place in the %%OUT%%, which shows a page break file for page break.

You must use a hexadecimal format to determine the symbol.

Default: 0x0c

si_timeout

Determines the number of seconds before the transformation process finishes.

Default: 240

The following example lists sample outputs in different formats assuming a date of August 20, 2003, at 3:59:10 a.m.

  • si_dateformat=%d,%m,%Y: 20,08,2003.

  • si_dateformat=%d/%m/%Y %H:%M: 20/08/2003 03:59.

  • si_dateformat=%m-%d-%y %H:%M:%S: 08-20-03 03:59:10.

  • si_dateformat=%d/%m/%Y %k:%M: 20/08/2003 3:59.

si_cleanup

Determines whether the transformer deletes the temporary input or output files.

Default: Yes

You must set the Output Mode field to Doc.

The following table lists acceptable date and time format specifiers.

Format

Description

%d

Determines the number of digits to show a two-digit day of month.

Valid values: 01−31

%H

Determines the number of digits to show a two-digit hour.

Valid values: 00−23

%k

Determines the number of digits to show a two-digit hour.

Valid values: 0−23

A blank space precedes single digits.

%m

Determines the number of digits to show a two-digit month.

Valid values: 0−12

%M

Determines the number of digits to show a two-digit minute.

Valid values: 00−59

%S

two-digit second

Valid values: 00−59

%y

Determines the number of digits to show a two-digit year.

Valid values: 00−99

%Y

Determines the number of digits to show a four-digit year.

XML to HTML

The XML to HTML transformer definition, Xml_D_2_HTML_D, uses a third-party product XALAN to transform XML reports into HTML. XALAN uses an XSLT style sheet, located in the transformer/res directory, for the transformation. The param field defines the XSLT style-sheet name, which allows you to have different style sheets for different report types.

You must type the following text in the Param field.

installation_directory/bin/Xalan.exe -o "%%OUT%%" "%%IN%%" w:\transformer\res\%%RA_REMARK%%.xsl

TIFF to PDF

The TIFF to PDF transformer definition, Tif_D_2_Pdf_D, uses a third-party product, PDFLib to transform TIFF reports to PDF.

You must type the following text in the Param field.

installation_directory/bin/bmc-ctd-dal-transformer-img2pdf.exe -o "%%OUT%%" "%%IN%%" -s [noprint][,nocopy][,nomodify] -r output_resolution

where

  • -s determines the following security settings of the resulting PDF.

    • noprint: You cannot print the PDF.

    • nocopy: You cannot copy the PDF.

    • nomodify: You cannot modify the PDF.

    Default: Allows all operations.

  • -r Determines the resolution of the output, which overrides the image settings.

    Default: Original resolution.