Many of Cireson’s new applications are being released on the Cireson Platform rather than relying on the existing technology of IIS to host the site the applications run on. This has many advantages that I won’t go in to within this blog post.
Instead, I’m going to cover one of the most frequent questions I get asked and that is “How do I change some of the custom text within the application?”
There may be many reasons for wanting to do this including adding a new language, changing some of the text to comply with corporate or security standards.
The Cireson Platform is designed to be a Multilanguage platform that allows users to switch between different languages as required. As such, all of the text that is assigned to each field, button or title is stored against a specific language.
To manipulate the Cireson Platform in any custom way we must do this via PowerShell using a custom module that can be downloaded from the Cireson development site.
To do this, run the following PowerShell command:
| Register-PackageSource “https://https://cireson.myget.org/F/public/api/v2” -Name CiresonPublicFeed -Trusted -ProviderName PowerShellGet |
This will download the required files inside the PowerShell session that you are running and therefore allow you to install the Cireson Platform Extension module called CPEX.
To do this run the following command:
| Install-Module -Name CPEXLets |
Once the module is installed you have access to a range of CMDLets to help you retrieve and set values within the Cireson Platform. The CMDLets that we will be using to change the text in the platform are Get-CPEXLocalizations and Set-CPEXLocalizations.
The first thing to understand when working with localizations within the Cireson platform is that each of the languages stored in the platform are stored against a Culture value. The culture value is a standard 4 letter initialism that is used to identify each language.
Such as:
| Culture | Language |
| en-US | English US (Default) |
| en-AU | English Australian |
| es-ES | Spanish |
| Pl-PL | Polish |
So when we extract the text fields that we want, we have to ensure we are retrieving the correct language or Culture associated with the test and language that we want to change. For example, if we want to change the welcome message for any en-US users, we need to get all the text values associated with the en-US culture.
Second, the values returned from the CPEX CMDLets are in JSON format that does not lend itself to easy reading within PowerShell.
For example if you type:
| Get-CPEXLocalizations -Culture en-US |
You will receive a
| @odata.context value
——————— ——- http://localhost/api/$metadata#Edm.String {“passwordsettings_requirelowercaseletters”:”Lowercase”,”error_passwordconstraintviolation”:”Password did not conform… |
Now this really doesn’t help us. What we need to do is transform this data from JSON format into something we can read.
To do this, PowerShell has a built in function that can do the conversion for us. It is called ConvertFrom-Json.
So if we run:
| ConvertFrom-Json ((Get-CPEXLocalizations -culture en-US).value) |
We see each of the Key and Value pairs for any of the text fields for the English (US) language and the looks something like this:
| KEY | VALUE |
| passwordsettings_requirelowercaseletters | Lowercase |
| error_passwordconstraintviolation | Password did not conform to all requirements. Please try a different password or check with your administrator. |
| licenseerror_version | This license is not valid for this version of Password Reset |
| error_usernotfoundexception | We’re sorry, but we didn’t find your account in the system. Please check with your administrator. |
| questionsettings_removeselectedquestions | Remove Selected Questions |
| integrationsettings_smtp_port_description | The port of your SMTP Server. |
| resetpassword | Reset Password |
| dialog_mustnotifyuserspart2 | before they can utilize this Password Reset functionality. |
| integrationsettings_rest_templateonmaxtokens_description | A template defining properties/values to set when creating a workitem for max token failures. |
| passwordsettings_requireuppercaseletters | Uppercase |
| …. | …. |
Each of the keys represent a different text area within the Cireson Platform. For example: The welcomemessage key, represents the welcome message that is shown on the front page of the Cireson True Password reset app.
Often it is easier to copy the output to a text file editor to search for the text that you would like to manipulate as it can be easier to find the text you are after.
To set the text to a different string it is as simple as using the Set-CPEXLocalizations CMDLet to set the value of a specific key.
For example, if we wished to set the custom Welcome Message on the True Password Reset App for the English (Australian) language we could run the following command:
| Set-CPEXLocalizations -culture en-AU -Key WelcomeMesage -value “Gday! Change your password mate.” |
This sets the key of WelcomeMessage to a value of the given text for the culture of en-AU.
Once run, the Cireson Platform service will require a restart for the changes to take effect. In the case of Cireson True Password Reset, the CiresonPasswordReset service will require a restart.
After which, the text field in question should be changed.
| BEFORE | AFTER |
 |
 |
EASY!
One of the most common fields people wish to edit is the custom SMS Text Message template. This is because most mobile phones provide the end user with a preview of the text message even when on the lock screen. This exposes a security risk for the second factor authentication of using the mobile phone token in the first place. However, if the message is long enough, the secret token will be truncated from the preview display.
The key to change for the SMS Text Message Template is tokenresettextmessagetemplate.
There are specific key words that are enclosed in % or { that are generated by the system that can be included in the test, such as %TOKEN% for the password reset token that is generated at the time of a password reset request.
So to set a new custom text message template for the English Australian language the command would be:
| Set-CPEXLocalizations -culture en-AU -Key tokenresettextmessagetemplate -value “You have requested for your corporate password to be reset. This is an automated message. Please do not reply. Please enter the following token in to the password reset utility %TOKEN%” |
Of course you can change the text to read whatever you would like, but the important piece to remember is the %TOKEN% filed needs to be included.
Hopefully this makes sense and you can now custom edit any of the required fields within your environment, and check out a video on this trick here.
