RapidIdentity Product Guide: Legacy UI

Localization

Localization provides users with the RapidIdentity System Admin role the ability to configure text within RapidIdentity.  

Legacy_Localization.png

The primary difference between Localization in the legacy UI relative to the new UI is that the new UI groups Localization modules in to component categories to help facilitate navigation and understanding of where a localization string is found within the product.

There are three major localization functionalities.

  1. Create custom labels or other text.

  2. Create new translations for non-English speaking audiences.

  3. Create a custom i18n bundle for Federation self-service links.

Of these three functionalities, creating custom labels or other text is the most common use case.

Localization Nomenclature

Localization precedes RapidIdentity 3.2, which means that many values in the Localization modules correspond to names no longer used within current Identity Automation and RapidIdentity branding (e.g. Marketing and Component or Module names).

For example, one localization container is called net.idauto.arms.aam. In this container, "arms" is the acronym for "Access Request Management System" which is now called RapidIdentity Portal. Similarly, "aam" is the acronym of "Application Access Module" which is now called Applications. To understand container labels and other deprecated acronyms and names, consult the localization nomenclature table.

Table 228. Branding Names

Deprecated Branding Name

Current Branding Name

Deprecated Branding Name

Current Branding Name

arms

RapidIdentity Portal

aam

Applications (module)

ApplicationAccessModule

Applications (module)

actm

Profiles (module)

AccountManagmentModule

Profiles (module)

dash

Dashboard (module)

fam

Files (module)

FileAccessModule

Files

gmm

Roles (module)

GroupManagementModule

Roles

rptm

Reporting (module)

spm

Sponsorship

dss

RapidIdentity Connect

wfm

Workflow (module)



Creating Custom Labels and Text

The most common localization use case is to make a particular message more friendly or informative by adjusting a single word or the overall phrasing.

The most efficient method to solve this use case is to locate the proper container to modify the string in question by using the dynamic search filter.

Sample Use Case: Claim My Account

Consider the following error message in response to a failed attempt to Claim My Account attempt.  

Localization_2.png

In this example, the red error message states that the Claim My Account operation failed however, it does not provide the user any additional information to clarify what step(s) should be taken to execute the Claim My Account operation properly.

While there are many different reasons that could uniquely or collectively trigger this error message, from the localization perspective what needs to be done is to modify the error message to inform the user what they should do before panicking and contacting their Support team.

The overall problem-solving approach includes the following steps.

  1. Access RapidIdentity Appliance Localization.

  2. Modify the string to inform the user.

  3. Save and apply changes.

  4. Validate the modified message works

Access Localization in the manner described above.

Using the dynamic search filter, type "The Claim My Account Operation failed". 

Localization_3.png

The dynamic search returns exactly one result. Click the red lettering to display the default value. 

Localization_4.png

Next, enter a custom description in the Custom Value text box.

Click Save and then Refresh Caches. After clicking Save, the Localization Tree will refresh and Refresh Caches will be in an orange box.

Once the caches are refreshed the orange box disappears.

Finally, validate the overall process by attempting to fail the Claim My Account operation.  

Localization_5.png

If the refreshed custom value is not desired or needs to be replaced, either edit the custom value as desired or click the Revert to Default button. Then click the Refresh Caches button to apply the changes.

Creating a New Locale

Creating a new locale involves cloning an existing locale. Thus, all new locales require manual translation to the desired language in the new locale.

To create a new localization, do the following.

Access RapidIdentity Appliance Localization and then click Manage Locales

Localization_6.png

Select Clone a locale, name the new locale, and then click Clone

Localization_7.png

The new locale can now accept updates or translations to new languages.

Localization_8.png

Delete an Existing Locale

To delete a locale, click Manage Locales, select the desired locale, and then click Delete.  

Localization_9.png

Click Refresh Caches to make the deleted locale effective immediately.

Create a Custom i18n Bundle

A Custom i18n Bundle currently supports the three RapidIdentity Federation self-service buttons from the IdP login page.

  1. Claim My Account

  2. Forgot My Password

  3. Forgot My Username

To initialize the custom i18n bundle, it is necessary to make two different API calls to RapidIdentity to authenticate for a new session and to create the custom key:value string.

API Call for New Session

Follow these steps to authenticate to RapidIdentity using Postman, cURL, or other equivalent approach.

  1. Using Postman or equivalent approach to perform an API call, make the following API call. 

    Authenticate for a new session

    POST /api/rest/sessions

  2. In the Headers field, enter Content Type as the key and application/json as the value.  

    Localization010.png
  3. In the Body field, select Raw and JSON (application/json). In the body, enter and administrator username and password.  

    Localization011.png
  4. Send the API call. A 200 status code returns with the JSON response for the session. 

    Localization012.png
  5. Alternatively, the cURL command can be entered to make the API call.

    Authenticate for a new session

    curl -X POST \https://server.domain/api/rest/sessions \-H 'cache-control: no-cache' \-H 'content-type: application/json' \-d '{"username": "adminUsername", "password": "adminPassword"}'

API Call to Create Custom Key:Value

Once the new session is established the custom i18n key:value pairs can be created.

Follow these seven steps to create the custom i18n key:value pair.

  1. Using Postman or equivalent approach to perform an API call, make the following API call:

  2. Create custom key/value pair

  3. POST api/rest/admin/resourceBundles/persistent/custom_i18n/{key}

  4. Currently Supported Keys

  5. There are three supported keys that can be passed into this API call currently:

    1. federation.label_claim_my_account

    2. federation.label_forgot_my_password

    3. federation.label_forgot_my_username

  6. In the Headers field, enter two key/value pairs.

    1. Enter Authorization as the key and Bearer {value} as the value.

    2. Enter Content Type as the key and text/plain as the value. 

      Localization013.png
    3. Obtain Bearer value

    4. To obtain the Bearer value, open Portal in the same cluster and then open the browser developer tools. Navigate to Network | All and refresh the page.

    5. Select bootstrapInfo. Scroll to the Request Headers section to locate  Authorization: Bearer {value}.

  7. In the Body field, select Raw and text/plain. In the body, enter Claim My Account.  

    Localization014.png
  8. Send the API call. A 204 status code returns to indicate that the API call was processed correctly. 

    Localization015.png
  9. Alternatively, the cURL command can be entered to make the API call.

    Create custom key:value

    curl -X POST \ https://server.domain/api/rest/admin/resourceBundles/persistent/custom_i18n/federation.label_claim_my_account \-H 'authorization: Bearer Fa4tmCTxzScJwVmY045joevX0YWoR3pn' \-H 'cache-control: no-cache' \-H 'content-type: text/plain' \-d 'Claim My Account'

  10. Navigate to RapidIdentity Appliance | Localization. The custom i18n bundle should be present at the top of the page. 

    Localization016.png
  11. Repeat this second API call sequence for the remaining Federation self-service keys.