Installing Language I/O Incidents in OSC Desktop (.NET)

The purpose of this article is to guide Oracle Service Cloud administrators through the installation and configuration of the Language I/O extension for Chat translation.

In this article:

1. Creating a Language I/O Status Custom Field
2. (Optional) Creating a Custom Language Field
3. Importing and Deploying the Language I/O Custom Object Definition
4. Installing the Language I/O Response Add-in
5. Adding the Add-in to Incident Workspaces
6. Adding Rules to Workspaces
7. Granting Profiles API and LNThread Custom Object Permissions
8. Server Configuration Properties
9. Downloads

Creating a Language I/O Status Custom Field

This is a required field. This field stores the status of the most recent translation attempt. 

1. Open your OSC application. Depending on your version:
   • If you have OSC version 19D or earlier: Go to Configuration > Database > Custom Fields and select Incident.
   • If you have OSC version 21A or later: Go to Configuration > Site Configuration > Custom Fields and select Incident.
2. Create a new custom field. Configure it as shown below:
   
   
   Note: In "Column Name", enter ln_status (spelled with lowercase 'L').
3. Click Save. This operation can take a few minutes. The add-in cannot function until this step is complete. 

(Optional) Creating a Custom Language Field

1. Open your OSC application. Depending on your version:
   • If you have OSC version 19D or earlier: Go to Configuration > Database > Custom Fields. 
   • If you have OSC version 21A or later: Go to Configuration > Site Configuration > Custom Fields.
2. Create a New Incident field and set it up as shown. Add all desired languages:
   
3. Hover with your mouse over each language and write down their IDs.
   1. Language I/O will request the list of all languages & their numeric IDs.
   2. You need the Language IDs to set the server configuration properties (see Chapter 8 below).
      
4. Make sure to write down the name of your custom locale field and the ID value for your agent language. You need it to set the server configuration properties (see Chapter 8 below).

Importing and Deploying the Language I/O Custom Object Definition

1. Download the "LNThread.zip" file attached at the bottom of this article.
2. Go to Configuration > Database > Object Designer.
3. In the Ribbon, click Import. Import the ZIP file.
4. Click Save, then Deploy. The operation may take a few minutes.

Installing the Language I/O Response Add-in

To upload the Language I/O Response add-in into your Oracle Service Cloud instance:

1. Go to Configuration > Site Configuration > Add-In Manager.
2. Click New and add the "LanguageIO_Response.zip" attached at the bottom of this article.
3. Enable your own profile in the Profile Access tab.
4. Click Save & Close. You can add users and set Server Configuration Properties later in the process.
5. Restart the Agent Desktop application to apply the changes.

Adding the Add-in to Incident Workspaces

You must now add the Language I/O Response add-in to the Workspaces for agents who need to translate Incident threads. Then, you must add the Language I/O Status field to the Workspace.

Repeat the following steps for all profiles for which you granted permission when you installed the Add-in:

1. Go to Configuration > Application Appearance > Workspaces/Workflows and open the relevant Incident Workspace.
2. Create a new tab in the Workspace. Label it with a user-friendly name, for example "Language I/O".
3. Go to Insert Control > Agent Desktop Add-Ins and drag the "Language I/O Incident" Add-In into the tab.
4. Go to the tab or area in your Incident Workspace where you want to show the Language I/O translation status field to users. Select "Insert Field in" and drag the "Language I/O Status" field.
5. Repeat Step 4 for the "Language" field.
   
   Note: This field may be named differently if you are using Custom Locales.
6. Ensure that the add-in will fill the tab:
   1. Select the add-in placeholder and navigate to the Design tab.
   2. Select Table >  Increase Column Span.
   3. Select Position > Stretch > Fill Cell.
   4. Set the size to autosize.
      These steps may vary based on your version of OSC.
7. Click Save.

Adding Rules to Workspaces

This section covers how to add a rule to allow Language I/O to automatically switch over to the Messages tab within the Incident Workspace once a translated response from an agent is ready to send. This must be done for for each workspace that uses Language I/O.

First, add a button (and associated rule) to loads the add-in into the workspace:

1. Go to Insert Control > Controls and drag a button into the top-left of tab containing the add-in.
2. Give the button a relevant name, for example "Load Language I/O". You may have to adjust the table position of the add-in after adding the button.
3. In the Home Ribbon, open the Rules popup.
4. Click Add Rule and set up the following:
   1. Triggers:
      1. Add "A button is clicked". Click the "button" link and select the "Language I/O" button.
   2. Actions:
      1. Add "Execute an add-in action". Click the "add-in action" link. Select the add-in and set the value to load.
      2. Add "Hide an Object". Click the "object" link. Select the "Load Language I/O" button.
   3. Name the rule with a relevant name in the Properties tab, for example "Language I/O Load Add-In".
   4. Click Finish.

Then, add the rule to switch to the Messages tab:

1. Click Add Rule again and set up the following:
   1. Triggers:
      1. Add "A named event fires". Click the "named event" link. Set the value to switch_to_messages_tab.
   2. Actions:
      1. Add "Focus a tab". Click the "tab" link. Select the messages tab.
   3. Name the rule with a relevant name in the Properties tab, for example "Language I/O Switch to Messages Tab".
   4. Click Finish.
2. Click OK to save your changes, then Save and Close to close the workspace editor.

Granting Profiles API and LNThread Custom Object Permissions

Make sure that all agent profiles that need to use Language I/O have the correct permissions:

1. Go to Configuration > Staff Management > Profiles report and follow the steps below for each profile that requires access to the Language I/O Response add-in.
2. The Add-In requires the following permissions to function:
   • Public SOAP API > Account Authentication: Session Authentication
   • Custom Objects > LNThread > Read: Add/Edit
   • Incidents > Read: Add/Edit, Send Response

You can grant the permissions for each user profile that need them, or for a single Add-In account or profile. For the latter, use the credentials for this account when you set the Server Configuration Properties (in Site_OscSoapLogin).

Depending on the Oracle Service Cloud version, you may have to adjust the Autosize options to make the add-in fill the available space.

Server Configuration Properties

Go to Configuration > Site Configuration > Add-In Manager > LanguageIO_Response.zip > Profile Access and select the relevant profile and interface:

• Color_: 
  • AgentMessage, AutomaticMessage, CustomerMessage, OtherMessage: These affect the status bar color for the various message types. You can use any color name from this list.
• Config_:
  • MaxContentLength: Copy-pasting content from other programs can introduce large amounts of hidden content (text formatting like bolding, font sizes, etc.) that may cause the translation engine to truncate the translation.  If set, determines the max number of characters that are allowed in an agent message. Default is no limit.
  • SendEmail: This determines whether Language I/O automatically sends translated agent messages:
    • If yes, clicking "send" on a translation emails it to the customer.
    • If no, clicking "send" moves the agent to the messages tab so that they can review, modify, and add standard text and articles to the message before sending.
    • The availability of this option depends on the configuration of the workspace.
  • Config_WordCountWarningThreshold: defaults to 0. If this is set to a number greater than 0, an alert triggers to verify if the agent wants to continue when an incoming message translation has a wordcount greater than the provided value.
• Site_:
  All Site properties are unique to your OSC instance and must be identical for every profile. If you use different values for these properties, Language I/O Response may stop working.
  • LinguistNowLogin: This value is typically set by your Language I/O Customer Success Manager. If not, they will let you know what value to use.
  • IncidentLocaleField: Leave this as "default" if you use built-in locales. Otherwise, use the name of the custom locale field that you created (see Chapter 2).
  • LinguistNowUrl: Leave this value as https://golinguist.com/linguistnow/resources/ unless otherwise instructed.
  • OscSoapLogin: If this field contains credentials, the add-in used these credentials to make all SOAP calls. This removes the need to give agent profiles SOAP permissions (see Chapter 7). Credentials should be in the format "username:password".
  • Site_IncidentLocaleField_UseLabels: Indicates the string label values for custom locale menu options are used instead of the numeric ID values, useful for using the same Language I/O consumer across multiple OSC sites where the custom locale menu options have different IDs.
• Translation:
  • AgentCanChangeTranslationType: This determines whether the agent can select anther translation type for outgoing messages.
  • AgentCanRequestRetranslation: This determines whether the agent can request a human re-translation for a customer message.
  • PreferredType:  This determines what type of translation Language I/O selects first:
    • machine - machine translation always preferred.
    • hybrid - machine for incoming translations (to agent), human for outgoing translations (to customer).
    • human - human translation always preferred.
  • Translation_QualityRatingType: If set to 0, no quality rating flags appear for translated messages. If set to 1, then a quality rating flag appears next to translated end-user messages.
  • RetranslationType: This determines the type used for retranslations, when the option is available.
    • machine2 - use an alternative machine translation engine.
    • human - use rapid human translation.
  • SupportLocale: This represents the language that the agent speaks.
    • If you are using Oracle's locales, and your agent speaks English, this value is 1.
    • If your agent speaks another language and you do not know its ID, contact your Language I/O Customer Success Manager.
    • If you use custom locales, use the ID that shows when you hover your mouse over the relevant language in the "data details" section of the custom field (see Chapter 2).
  • TranslationTypeLocales: Used in conjunction with AgentCanChangeTranslationType, this limits the number of languages that an agent can select to change translation types. If it is left blank, or if the list is not valid, the agent can select the type or not based on the AgentCanChangeTranslationType setting. To use this setting, enter a list of IDs in the form of a comma separated list to specify the target languages for which agents can select translation type, for example "1, 2, 5".

Downloads