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.

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

• Report data: Reports retrieved from the Control-D Mainframe repository, as described in Connecting Control-D Delivery Server to the Control-D Mainframe.

• Transformer configuration: Determines the folder paths where to save resources and report cliques, as described in Configuring Control-D Delivery Server Transformers.

• Transformation definition: Determines the output criteria, such as output resolution, orientation, and color, as described in Configuring Control-D Delivery Server Report Cliques.

  You can also transform reports with a third-party application, as described in Running Control-D Delivery Server Shell Transformations.

• Resources: Required resources to transform a report, such as fonts and images, saved in the in the \transformer\res folder, as described in Control-D Delivery Server Resource Management and Mapping Fonts.

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.

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.

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

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.