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)
The Translation service creates a translation report.
Implementing the Translation Service
To implement the Translation service, complete the following tasks:
- Activate your license for the Translation service.
- 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.
- Create a Translation service configuration.
- Configure the Translation service. See Configuring the Translation Service.
- 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.
- 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:
- 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>