getTextReport — Retrieving a list of system messages

The getTextReport method retrieves a list of all system messages used within the SiteLock product. These include messages that are generated by the scanners and the strings needed for the user interface. The response contains the system messages in all requested languages.

The API endpoint is:

https://api.sitelock.com/v1/partner

Request format

SiteLockOnlineRequest: This element is used to delineate the full API request.
- authentication: The partner’s username, password, and branding
  - username: The partner’s API username
  - password: The partner’s API password
  - partner: (Optional) The brand name to use in messaging
- getTextReport: The method name
  - languages: It’s expected to contain one or more lang elements. When there are no child lang elements, the languages element is optional. When the languages element isn’t specified, all currently supported languages are returned.
    
    lang: (Optional) When present, each lang element is expected to contain an identifier for one language. All valid identifiers are returned by the method that lists the languages supported by SiteLock. A language identifier may take one of the following forms:
    
    The common English name for the language, for example, english
    
    The two-character abbreviation of the five-character code, for example, en
    
    The five-character code, for example, en-US
    
    The internal SiteLock ID, for example, 1

Example request

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>Password</password>
    </authentication>
    <getTextReport>
        <languages>
            <lang>english</lang>
            <lang>2</lang>
            <lang>fr</lang>
        </languages>
    </getTextReport>
</SiteLockOnlineRequest>

Response format

SiteLockOnlineResponse: This element is used to delineate the full API response.
- getTextReport: The method name
  - languages: A list of languages
    
    language: (Repeatable) A language
    
    abbr: [attribute] - The two-character abbreviation of the five-character code, for example, en
    
    code: [attribute] - The five-character code, for example, en-US
    
    id: [attribute] - The internal SiteLock language identifier, for example, 1
    
    local_name: [attribute] - The name of the language as used in its native country, for example, English
    
    strings: A list of system messages
    
    string: (Repeatable) A system message
    
    key: [attribute] - A unique SiteLock identifier for the string. This can safely be ignored.
    
    state: [attribute] - The validity of the translated strings. It can have the following values:
    
    new: The English text provided is new, and if any of the other languages have been provided, it’s an accurate translation. One or more languages may not have been provided.
    
    out_of_sync: When a system message is out of sync, it means that any child language present cannot be trusted (old translations may be temporarily retained for reference purposes), and the message must be retranslated to all languages.
    
    in_sync: All translations for this string are up to date.
    
    scan: [attribute] - Indicates to which scan, if any, a particular message is related. See also How the attributes are related. The value can be one of the following:
    
    verify_domain_email: Domain email verification
    
    ssl_scan: SSL Monitor
    
    malware_scan: Webpage Scan
    
    xss_scan: Cross-site scripting scan
    
    sqli_scan: SQL injection scan
    
    advisories: Security advisories
    
    risk_score: Risk Score
    
    smart_scan: SMART File Scan
    
    db_scan: SMART Database Scan
    
    patchman_scan: SMART Patch Scan
    
    spam_scan: Spam monitoring
    
    n/a: The message isn’t related to any scan. For example, the message relates to constant strings displayed in the UI.
    
    verify_phone: (Deprecated) Phone verification. Empty attribute is returned to preserve backwards compatibility.
    
    verify_address: (Deprecated) Address verification. Empty attribute is returned to preserve backwards compatibility.
    
    channel: [attribute] - Defines how the string will be communicated to the user. See also How the attributes are related. The value can be one of the following:
    
    email_system_message: This message will appear in an email sent by SiteLock.
    
    ui_system_message: This message will appear in the UI and is output generated by the backend application. For example, SMART scan found 2 issues.
    
    ui_scan_output: This message will appear in the UI and is output generated specifically by a scan in the back end application. This differs from ui_system_message in that it’s always a message from a scan.
    
    ui_constant: This message will appear in the user interface as a prompt, or as text on the web page. The channel attribute will never have the value n/a.
    
    id: [attribute] - This attribute identifies the string and is referenced in scanDetail.
    
    level: [attribute] - The priority, or criticality, of the given message. See also How the attributes are related. The possible values are:
    
    information: Information message
    
    notice: Notice message
    
    critical: Critical message
    
    n/a: The message isn’t related to any scan. For example, the message relates to constant strings displayed in the UI.
    
    see_scan: The level of message will be derived at the time a scan is performed.
    
    language: The translation of a particular system message into the specified language.
    
    id: [attribute] - The internal SiteLock identifier for a language. The id for the first language is always 1 and is the system message in English. Other id values correspond to other languages.

How the attributes are related

When the value of channel is ui_scan_output, the scan attribute will contain the name of the scan, and the value of level will be see_scan. In this case, the level of the message will be derived at the time a scan is performed. For example, when app scan finds a service installed on your server, it will assign a different level of severity should it find an SSH service, rather than it would were it to find a Trojan service. In both cases, the message will be the same in that a service was found. However, in the former case, the level is information, and in the latter, it’s critical. To determine the actual/resolved level, see scanDetail.

When channel is ui_scan_output, level will be see_scan, and scan will never be n/a
When channel is ui_constant, level will be n/a
When channel is ui_system_message, level will vary
When channel is email_system_message, level will be n/a

Example response

<SiteLockOnlineResponse>
    <getTextReport>
        <languages>
            <language name="english" abbr="en" code="en-US" id="1"
            local_name="English" />
            <language name="german" abbr="de" code="de-DE" id="2"
            local_name="Deutsch" />
            <language name="french" abbr="fr" code="fr-FR" id="4"
            local_name="Français" />
        </languages>
        <strings>
            <string key="intl_messages:scan_obf_js_found" channel="ui_scan output" id="n/a" level="see_scan" scan="advisories" state="in_sync">
            <language id="1">Found on sample pages ( %s ).
            The javascript starts with:</language>
                <language id="2">Javascript gefunden, unter anderem hier: ( %s ). Das Script beginnt mit: </language>
                <language id="4">Trouvé dans les échantillons de pages ( %s ). Le javascript commence par:</language>
            </string>
            <string key="system_emails:30:subject" channel="email_system message" id="30:subject" level="n/a" scan="n/a" state="in_sync">
                <language id="1">Congratulations on displaying your SiteLock badge!</language>
                <language id="2">Herzliche Gratulation zur Anzeige Ihres
                SiteLock-Siegels!</language>
                <language id="4">Félicitations pour afficher votre badge SiteLock!</language>
            </string>
        </strings>
    </getTextReport>
</SiteLockOnlineResponse>

Brands and other tokens in messages

SiteLock partners who integrate deeply may have a need to remove the SiteLock brand from all emails, system messages and scan output meant for the end user. This is determined by the agreement that SiteLock has with the partner. Once a partner has this agreement in place with SiteLock, the strings retrieved via getTextReport and scanDetail will be tokenized to remove references to SiteLock. The partner can then replace the token with suitable phrases.

The following table lays out the tokens that can be expected in the output from SiteLock.

Keyword or Token	Meaning	Original in SiteLock communications
\{\{--link-verify--}}	URL to the site verification page, including identifier(s)	https://www.sitelock.com/verify.php?site=www.somethingsomething.com
\{\{--link-shield-image--}}	URL to the shield image, including identifier(s)	//shield.sitelock.com/shield/www.somethingsomething.com
\{\{--url-shield-server--}}	URL to the shield server root, used in FAQ/troubleshooting style messages	//shield.sitelock.com
\{\{--link-unsub--}}	URL to navigate to in order to unsubscribe, including identifier(s)	https://www.sitelock.com/subscribe.php?email=\{\{--to--}}
\{\{--link-login--}}	URL to dashboard login	https://secure.sitelock.com/login
\{\{--link-password-reset--}}	URL to reset password form	https://secure.sitelock.com/reset-password.php
\{\{--support-email--}}	E-mail address of support department	[email protected]
\{\{--brand-site-http-www--}}	URL of brand main site, including HTTP/S and www prefix	https://www.sitelock.com/[https://www.sitelock.com]
\{\{--brand-site-http-no-www--}}	URL of brand main site, including HTTP/S but without www prefix	https://sitelock.com/
\{\{--brand-site-www--}}	URL of brand main site, including www prefix but without HTTP/S	www.sitelock.com/
\{\{--brand-site-no-www--}}	URL of brand main site, without HTTP/S or www prefix	sitelock.com
\{\{--brand-name--}}	The name of the brand of the product. Sometimes precedes other terms (for example, SiteLock App Scan ⇒ \{\{--brand-name--}} App Scan)	SiteLock

Keyword or Token

Meaning

Original in SiteLock communications

\{\{--link-verify--}}

URL to the site verification page, including identifier(s)

https://www.sitelock.com/verify.php?site=www.somethingsomething.com

\{\{--link-shield-image--}}

URL to the shield image, including identifier(s)

//shield.sitelock.com/shield/www.somethingsomething.com

\{\{--url-shield-server--}}

URL to the shield server root, used in FAQ/troubleshooting style messages

//shield.sitelock.com

\{\{--link-unsub--}}

URL to navigate to in order to unsubscribe, including identifier(s)

https://www.sitelock.com/subscribe.php?email=\{\{--to--}}

\{\{--link-login--}}

URL to dashboard login

https://secure.sitelock.com/login

\{\{--link-password-reset--}}

URL to reset password form

https://secure.sitelock.com/reset-password.php

\{\{--support-email--}}

E-mail address of support department

[email protected]

\{\{--brand-site-http-www--}}

URL of brand main site, including HTTP/S and www prefix

https://www.sitelock.com/[https://www.sitelock.com]

\{\{--brand-site-http-no-www--}}

URL of brand main site, including HTTP/S but without www prefix

https://sitelock.com/

\{\{--brand-site-www--}}

URL of brand main site, including www prefix but without HTTP/S

www.sitelock.com/

\{\{--brand-site-no-www--}}

URL of brand main site, without HTTP/S or www prefix

sitelock.com

\{\{--brand-name--}}

The name of the brand of the product. Sometimes precedes other terms (for example, SiteLock App Scan ⇒ \{\{--brand-name--}} App Scan)

SiteLock

Other tokens may be encountered within the messages, but these tokens are intended to be used in emails or messages with variable substitutions, as described in Retrieving pending email messages.