Translation Service

The following table provides an overview of the Translation service:

System name
Translation Type
Graphical Process Modeler (GPM) categories
All Services, Translation
Description
Performs translation of the primary document using a specified map, and replaces the primary document with the result of the translation.
Business usage
Performs translation of the primary document within business processes.
Usage example
You want to take positional data from your order system and translate it to variable-length-delimited data so that it can be read by your billing system.

Use the Sterling B2B Integrator Map Editor to create a map that will translate the incoming data from positional data to variable-length-delimited data. Write a business process that will put the data into the primary document, then start the Translation service. Using the map you created, the service translates the data from positional data to variable-length-delimited, and replaces the old data with newly translated data in the primary document.

Preconfigured?
There is a configuration of the service delivered with the IBM® Sterling B2B Integrator, but you must configure parameters for it in the GPM.
Requires third party files?
No
Platform availability
All supported application platforms
Related services
No
Application requirements
The map specified in the map_name parameter must be registered with the IBM Sterling B2B Integrator and activated. If either of these conditions is not met then the translation will not be performed.
Initiates business processes?
No
Invocation
Runs as part of a business process.
Business process context considerations
The Translation service looks for the following parameters in the business process context. If the service finds them, it uses them during translations where either the input or output is EDI:
  • edi_output_tag_delimeter
  • edi_output_segment_delimeter
  • edi_output_element_delimeter
  • edi_output_sub_element_delimeter
  • edi_output_repeating_element_delimeter
  • edi_output_release_character
  • edi_output_decimal_separator
  • edi_input_tag_delimeter
  • edi_input_segment_delimeter
  • edi_input_element_delimeter
  • edi_input_sub_element_delimeter
  • edi_input_repeating_element_delimeter
  • edi_input_release_character
  • edi_input_decimal_separator
Returned status values
  • Success – Translation was successful.
  • Error – Errors were encountered during translation or translation could not be performed. See the Translator report contained in the Business Process Context Status report for further detail.
Restrictions
No
Persistence level
None
Testing considerations
The best way to test is within a simple business process where the Translation service is the only operation. After the business process runs, verify the output in the IBM Sterling B2B Integrator, and review the translator report for detail on what occurred during the translation.

How the Translation Service Works

The Translation service translates data in the following file formats:

  • Electronic data interchange (EDI)
  • Positional
  • Variable-length-delimited
  • Extensible Markup Language (XML)
  • Structured Query Language (SQL)
  • Japanese Center for Informatization of Industry (CII)
Note: If the input document character encoding is specified in the IBM Sterling B2B Integrator, it overrides the encoding specified in the map. The output document content type and character encoding are set based on the information contained in the map.

The Translation service creates a translation report.

Implementing the Translation Service

To implement the Translation service, complete the following tasks:

  1. Activate your license for the Translation service.
  2. If you are using a map that has a database on the output side, you must set up a connection to the database that contains the tables you want to access.
  3. Create a Translation service configuration.
  4. Configure the Translation service. See Configuring the Translation Service.
  5. Use the Translation service in a business process.

Configuring the Translation Service

To configure the Translation service, you must specify settings for the following fields in the GPM:

Field
Description
Config
Name of the service configuration.
edi_input_decimal_separator
Character used to indicate the decimal point on the input side.
edi_input_element_delimiter
Character used to delimit elements (fields) on the input side.
edi_input_release_character
Character used to quote elements (fields) that contain the delimiter on the input side.
edi_input_repeating_element_delimiter
Character used to delimit repeating elements on the input side.
edi_input_segment_delimiter
Character used to delimit segments on the input side.
edi_input_sub_element_delimiter
Character used to delimit sub-elements on the input side.
edi_input_tag_delimiter
Character used to delimit tags on the input side.
edi_output_decimal_separator
Character used to indicate the decimal point on the output side.
edi_output_element_delimiter
Character used to delimit elements (fields) on the output side.
edi_output_release_character
Character used to quote elements (fields) that contain the delimiter on the output side.
edi_output_repeating_element_delimiter
Character used to delimit repeating elements on the output side.
edi_output_segment_delimiter
Character used to delimit segments on the output side.
edi_output_sub_element_delimiter
Character used to delimit sub-elements on the output side.
edi_output_tag_delimiter
Character used to delimit tags on the output side.
exhaust_input
Whether to execute the map until the Translation service has translated all of the input. Valid values are Yes and No.
Note: If your map design is faulty (that is, if the data structure does not match the layout of the map), the data in the input file cannot be properly processed. If a segment is present in the input file it must be defined and active in the map and in the proper sequence. When the translator reads a segment, it tries to match it to the records in the map based on their tag values.

If exhaust_input is set to “Yes” the translator attempts to match each segment in the input file to a segment in the map, until it reaches the end of the input file. Conversely, if exhaust_input is set to “No,” the translator does not re-invoke the map to continue processing the remaining data in the input file.
map_name
Name of the map used for translation. The map must already be checked in to the IBM Sterling B2B Integrator and enabled.
output_report_to_process_data
Whether to output the report to process data. Valid values are:
  • Yes: Output the report to process data.
  • No: Do no output the report to process data.
output_to_process_data
Whether the output of the translation should be placed in the process data tree. The output must be XML. Valid values are Yes and No.
useStreams
Whether to support large files (streaming mode). Valid values are Yes (default), No, and blank (which uses default).

The default was changed with release 4.1.1, patch 1973. In versions previous to that, the service did not use document streaming by default.

validate_input
Validates the input to the input side of the map. Valid values are Yes and No.
validate_input_against_dtd
Validates the input to the DTD specified in the input document. Valid values are No validation, Validate using a DTD, and Validate using an XML schema.
validate_output
Validates the output to the output side of the map. Valid values are Yes and No.
ErrorIfAllDataNotConsumed
Whether to throw an error if all of the input data is not consumed during the translation (please note that this is valid only if exhaust_input is not set to true). The default is false (do not throw an error if all of the input data is not consumed).
ErrorIfNoOutput
Whether to throw an error if the output document generated by the translation is empty. The default is false (do not throw an error).

Parameters Passed Through BPML Only

The following parameters can be passed through BPML using an Assign statement. Note that these parameters are not available through the GPM.

Parameter
Description
FromSchema
Used to enable manipulation of a database schema prefix within the SQL Table/View or SQL Statement of a map. This parameter is required when overriding schema names within one or more SQL Statement fields.

If the FromSchema and ToSchema parameters are not supplied, then no schema name substitution is performed.

Note: The schema search/replace is case-sensitive.
ToSchema
Used to enable manipulation of a database schema prefix within the SQL Table/View or SQL Statement of a map.
Note: The schema search/replace is case-sensitive.

If the FromSchema and ToSchema parameters are not supplied, then no schema name substitution is performed.

If the ToSchema parameter is supplied and contains a non-empty value, then any matching schema names are changed at translation time to use the supplied ToSchema schema value as follows:

  • For a SQL Statement, only schema names that match the FromSchema value will be substituted. The FromSchema parameter is required—otherwise, no schema values are substituted. To match and substitute more than one value pair, the FromSchema and ToSchema parameter strings can be delimited with an @ sign. For example:
    
    FromSchema=”from1@from2”
    ToSchema=”to1@to2”
    

    In this example, any schema names matching “from1” are changed to “to1,” and any schema names matching “from2” are changed to “to2.”

For convenience, you can supply fewer ToSchema fragments than FromSchema fragments, and when there is no corresponding ToSchema fragment, the last fragment in the ToSchema string is used. For example:


FromSchema=”from1@from2@from3”
ToSchema=”to”

In this example, any schema names matching “from1,” “from2,” or “from3” will be changed to “to.”

  • For a SQL Table/View, the FromSchema parameter is optional. If it is not supplied, all schema names are changed to the supplied ToSchema value. If it is supplied, the substitution occurs in the same way as it does for a SQL Statement. If the translator property sql.driver.useIdentifierQuoteString is set to True within customer_overrides.properties, then matching and substitution occurs with quoted schema names.
  • If the ToSchema parameter is supplied but is empty (equal to ““ (two double quotation marks) or ‘' (two single quotation marks)), then any matching schema names contained in the map are removed at translation time.
sql_statement_use_batching
Whether to enable batching. Valid values are Yes and No (default).
sql_statement_maximum_
batchsize
The maximum size of the SQL statement batch. Only valid if sql_statement_use_batching is set to Yes.

Turning on SQL Statement Batching

In your map, any record for which the On failure, automatically switch selected operation and retry Inserts as Updates or Updates as Inserts setting is turned on (enabled) is not be batched, because batching is not supported for records that have retry enabled. For these records, the SQL is executed with no batching, and records that do not have retry enabled are batched.

Additionally, in the map, the data source must have Use Transaction enabled. If Use Transaction is turned off, then batching is not performed

Finally, the database must support batching. If the database does not support batching, the batch service parameters will be ignored and the SQL statements will not be batched.

This example BPML demonstrates how you might enable SQL statement batching:


<operation name="Translation">
      <participant name="Translation"/>
      <output message="TranslationTypeInputMessage">
        <assign to="map_name">insert</assign>
        <assign to="sql_statement_use_batching" from="'yes'"/>
        <assign to="sql_statement_maximum_batchsize" from="'500'"/>
        <assign to="." from="*"></assign>
      </output>
      <input message="in">
        <assign to="." from="*"></assign>
      </input>
    </operation>