RapidIdentity Product Guide: Legacy UI

Localization Functionalities
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.

Legacy_Create_Custom_Labels.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. Find the appropriate string container.

  3. Modify the string to inform the user.

  4. Save and apply changes.

  5. Validate the modified message works

Access Localization in the manner described above.

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

Legacy_Custom_Text.png

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

Legacy_New_Text.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. 

Legacy_Customized_Message.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 and Deleting Locales

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.

Legacy_Manage_Locales.png

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

Legacy_Clone_Locale.png

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

Legacy_New_Locale.png

To Delete an Existing Locale, click Manage Locales, select the desired locale, and then click Delete

Legacy_Delete_Locale.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 another equivalent approach:

  1. Using Postman, cURL, or another HTTP client, submit a POST call to the following path to authenticate a new session.

    POST /api/rest/sessions

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

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

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

    Legacy_API_Call_Send_Json.png
  5. You can use the following cURL call to authenticate 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, cURL, or another HTTP client, submit a POST call to the following path to create a new custom key/value pair.

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

    Currently, there are three supported keys that can be passed into this API call.

    1.  federation.label_claim_my_account

    2.  federation.label_forgot_my_password

    3.  federation.label_forgot_my_username

  2. 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. 

    Legacy_API_Call_Custom_Key_1.png

    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.

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

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

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

    Legacy_API_Call_Successful.png
  5. You can use the following cURL example to create a custom key/value pair:

    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'       
  6. Navigate to RapidIdentity Appliance | Localization. The custom i18n bundle should be present at the top of the page. 

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