Create and link a translation set

Last updated: Nov 13, 2024

DEVELOPER

IMPLEMENTATION

A translation set is a list of individual translations, which map two values to each other. Learn about translation sets.

Platform API endpoints

This article contains instructions for managing translations and translation sets in the Redox dashboard. If you'd like to create and manage via API instead, use these Platform API endpoints:

Only for engineer or support roles

Any user may view existing data operations (e.g., filters, translation sets, config modifiers) for subscriptions in a given environment. However, you must be assigned to an engineer or a support role to create and manage data operations. Learn about roles.

Create a translation set

Navigate to the Operations page in the Redox dashboard.
By default, the Value sets tab displays. Click the Translation sets tab.
Any defined translation sets appear on the page. Click the Create translation set button.
The translation set wizard opens. Enter the translation set name, then click the Next button.
Name requirements
A translation set name can't exceed 500 characters. Also, the name must be unique for each environment. In other words, staging and production environments can't have the same names for translation sets.
The name appears as the column title for the translation set table.
Next, the Setup details tab opens. You can either:

Build translations from existing value sets in the dashboard

This is a convenient option if you've already created value sets and simply want to map values in the dashboard.

Or, if you haven't created value sets but would like to create and map directly in the dashboard, learn how to create a value set first.

Click the Build translations from existing value sets option.
In the From drop-down on the left, select the value set you want to translate from.
In the To drop-down on the right, select the value set you want to translate to.
Click the Next button.
The Set up translations tab opens. At the top, the translation set's directionality displays. Below that, two drop-down fields appear with the value sets you selected in the previous step.
A note about directionality
Technically, a translation set is bi-directional by default, so the value sets could be either FROM or TO values. The directionality only changes to uni-directional when you add at least two mappings with the same TO value from the drop-down on the right.
You can link bi-directional translation sets either FROM-TO or TO-FROM. However, you can only link uni-directional sets FROM-TO. Learn more about directionality.
On the left side, select the value you want to map.
On the right side, select the value you want to map the previous value to.
Click the Add button.
The new translation appears in the table below. Repeat steps #6 through #8 for each translation you want to create.
"In use" values and directionality
If a FROM value has already been selected, it will have a label that says "in use." You may not map the same value more than once (i.e., selecting a FROM value more than once).
You may map multiple values to the same value (i.e., by selecting a TO value more than once), but doing so will change the directionality to uni-directional. Otherwise, mappings will be bi-directional by default.
Translation limit
You may not have more than 1,000 mapped translations per translation set.
Translation sets are case sensitive by default. To change it, toggle the Case sensitive option to off. If you turn off case sensitivity, any value that matches a FROM value, regardless of casing, will be translated to the indicated TO value.
Disabled case sensitive option
In some instances, the case sensitive toggle is disabled. This can happen when:
You want to turn case sensitivity off, but there are at least two FROM values that would be the same without case sensitivity. For example, if you have two FROM values of WISCONSIN and wisconsin. You must remove any conflicting FROM values before the case sensitive toggle will be enabled.
You want to turn case sensitivity off, but the selected translation set has one or more TO-FROM links. If there are at least two TO values that would be the same without case sensitivity, it means that the set can't be bi-directional. You must remove any TO-FROM links before the case sensitive toggle will be enabled.
Review the table with your translations. To edit a translation, click the pencil icon on the right. To delete a translation, click the minus icon on the left. This only deletes one translation in the table, not the entire translation set.
When you've finished, click the Create set button.

Import new value sets with translations in a CSV file

This is a helpful option if you have lots of values and would prefer to handle mapping translations in a CSV file.

If you choose this option, the value sets you import are only temporarily created in the dashboard until you finish creating the translation set.

Click the Import new value sets with translations in a CSV file option.
Instructions display for the import. Click the Upload a CSV file button.
CSV file requirements
A CSV file will import successfully if it has:
exactly two columns (i.e., one column per value set);
a header row with value set names;
at least one defined mapping (i.e., value in column 1 mapped to value in column 2) but no more than 1,000; and
no duplicate values in column 1.
A dialog box opens. Select the CSV file you want to import.
CSV file errors
If your file doesn't meet these criteria, you may get any of these errors:
CSV file or format is invalid.
Duplicate value "<defined-value>" found on column 1 of lines: <row number>
CSV file must not have more than 1,000 rows.
Make sure that your CSV file is properly formatted to avoid these errors. If you do get one of these errors, fix the issue, then re-select it to validate again.
The file passes validation. Click the Next button.
The Set up translations tab opens. At the top, the translation set's directionality displays. Below that, two drop-down fields appear with the value sets you imported in the previous step. A table shows all the translations defined in the CSV file.
A note about directionality
Technically, a translation set is bi-directional by default, so the value sets could be either FROM or TO values. The directionality only changes to uni-directional when you add at least two mappings with the same TO value from the drop-down on the right.
You can link bi-directional translation sets either FROM-TO or TO-FROM. However, you can only link uni-directional sets FROM-TO. Learn more about directionality.

"In use" values and directionality
If a FROM value has already been selected, it will have a label that says "in use." You may not map the same value more than once (i.e., selecting a FROM value more than once).
You may map multiple values to the same value (i.e., by selecting a TO value more than once), but doing so will change the directionality to uni-directional. Otherwise, mappings will be bi-directional by default.
Translation sets are case sensitive by default. To change it, toggle the Case sensitive option to off. If you turn off case sensitivity, any value that matches a FROM value, regardless of casing, will be translated to the indicated TO value.
Disabled case sensitive option
In some instances, the case sensitive toggle is disabled. This can happen when:
You want to turn case sensitivity off, but there are at least two FROM values that would be the same without case sensitivity. For example, if you have two FROM values of WISCONSIN and wisconsin. You must remove any conflicting FROM values before the case sensitive toggle will be enabled.
You want to turn case sensitivity off, but the selected translation set has one or more TO-FROM links. If there are at least two TO values that would be the same without case sensitivity, it means that the set can't be bi-directional. You must remove any TO-FROM links before the case sensitive toggle will be enabled.
Review the table with your translations. To add a translation, select a value you want to map from the left drop-down field, then a value to map to from the right drop-down field. To edit a translation, click the pencil icon on the right. To delete a translation, click the minus icon on the left. This only deletes one translation in the table, not the entire translation set.
When you've finished reviewing and editing, click the Create set button. This creates the new translation set, including the translations and value sets from import, and saves it with any edits you've made in the dashboard.

Edit or delete a translation set

Navigate to the Operations page in the dashboard.
By default, the Value sets tab displays. Click the Translation sets tab.
Any defined translation sets appear on the page. Find the translation set you want to delete. Click the three-dots icon.
From the drop-down menu, click the Delete option or click the Edit option.
Deleting a translation set
You may not delete a translation set that's in use. Remove any links first to successfully delete a translation set.
If you clicked the Edit option, the Details page opens. Modify the details on this page, or you can also delete the translation from this page, too.
Changing directionality
A translation set is bi-directional by default. However, a bi-directional set changes to uni-directional if you add at least two mappings with the same TO value. You must remove any TO-FROM links first, though, since you can't have TO-FROM links with duplicate TO values.
To change a uni-directional set back to bi-directional, you must remove all mappings with duplicate TO values.

Link a translation set

After creating a translation set, you must link it to the relevant stage of log processing (i.e., REQUEST and RESPOND or SEND and RECEIVE).

Links and processing stages

You can link a translation set to up to four stages, depending on whether your organization owns both sides of the subscription (i.e., both the source and destination).

If your organization owns both sides of the subscription, you may link a translation set to any of the four processing stages.

If your organization owns only one side of the subscription, you may link a translation set to the two processing stages you own. For example, if you own the source side of the subscription, you may link a translation set to the REQUEST and RECEIVE processing stages.

Navigate to the Operations page in the dashboard.
By default, the Value sets tab displays. Click the Translation sets tab.
Any defined translation sets appear on the page. Find the translation set you want to link. Click the three-dots icon.
On the drop-down menu, click the View translation set option.
The translation set's activity, details, and links display. Under the Links section, click the Link set button.
Uni-directional sets
You can't link a uni-directional translation set in the TO-FROM direction.
The translation set wizard opens. From the Set name drop-down, select the translation set you want to link.
Click the Next button.
The Select subscription tab opens. If the translation set is bi-directional, two options display for directionality. Select the direction for this specific translation link. Remember, you can link a bi-directional translation to go in different directions with different links.
A note about directionality
Technically, a translation set is bi-directional by default, so the value sets could be either FROM or TO values. The directionality only changes to uni-directional when you add at least two mappings with the same TO value from the drop-down on the right.
You can link bi-directional translation sets either FROM-TO or TO-FROM. However, you can only link uni-directional sets FROM-TO. Learn more about directionality.
Click the Select subscription link.
A dialog box opens with the subscriptions in your environment. Use the Search field or the Connection drop-down to narrow down the available options. If needed, use the page options at the bottom of the dialog to navigate through the pages. Then select the radio button of the subscription you want to link a translation set to.
Click the Select Subscription button.
After selecting a subscription, the available stages in the log processing display. If your organization doesn't own a processing stage, the location is grayed out. From the When drop-down, select the processing stage (i.e., REQUEST, RECEIVE, RESPOND) to link the translation set to.
Click the Next button.
The Field paths section appears. Click the Select Field Path drop-down to view a list of fields.
Select the field you want to link the translation set to.
A dialog opens for testing the field path and value. You can change your selection by clicking the Field Path drop-down again to view a list of fields.
Once you have the correct path, use the validation tools to test your choice. Or, if you don't want to test, you can skip and proceed to the next step.
1. Find a log payload for the subscription you want to translate. Learn more about searching for logs.
2. Copy and paste the log payload into the Test Message section.
3. On the right side of the dialog, under Field Values, the value that displays is the one found at the field path you selected.
Keep in mind that Redox doesn't validate the translation set link. But it does give you an idea of whether you selected the right field path by using an existing log payload.
Click the Select Path button on the bottom right of the dialog.
To add another field path, click the plus button next to right of the drop-down field. Repeat steps 14 through 19 for as many field paths you want to include in the translation set link.
Review the information for the link, then when you're ready. To edit any of the details, click the Previous button. If everything look good, click the Create Link button.
The new link appears in the table, and it automatically takes effect on the related subscription.
Operation details in logs
If a log has undergone filtering or translation, you can view the related operation details when you click the related processing stage.
Learn about data operations and:
log details for filters
log details for translation sets
log details for config modifiers (beta feature)
You can link the same translation set multiple times. To create another link, click the Link set button to repeat the process.

Edit or delete a translation set link

Navigate to the Operations page in the dashboard.
By default, the Value sets tab displays. Click the Translation sets tab.
Any defined translation sets appear on the page. Find the translation set you want to edit. Click the three-dots icon.
From the drop-down menu, click the View translation set option.
The translation set's activity, details, and links display. Under the Links section, click the three-dots icon.
From the drop-down menu, click the Delete option or click the Edit option.
Deleting a translation set link
If you click the Delete button, a dialog opens to confirm. You may delete a translation set link that's in use. Logs will still process, but without the translation set link, no translation will happen.
The translation set wizard opens. Edit any of the details, then click the Update Link button.

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.