Provisioning a URL that creates a connection for mobile users

Provision a URL that automatically creates an IBM® Sametime® community definition on mobile devices running Google Android or Apple iOS, so users can easily connect to Sametime.

About this task

A mobile user cannot connect to the Sametime Proxy Server without a special "mobile community" definition that provides details needed for the connection. Creating the mobile community is often frustrating for users because they do not have ready access to required information such as the Sametime Proxy Server's host name and port. Provisioning a URL for the mobile community makes it easy for users to connect to Sametime from their mobile devices after installing the client.

To connect to Sametime, the user simply taps the link or scans the QR code, and then:
  • If the user is logged in to Sametime, an alert explains that the user must log out of Sametime to use the link, and then resumes the previous session so the user can log out and try again.
  • If the user already belongs to a community with the same name, an alert prompts the user to confirm that the existing community definition should be updated. When the user confirms the update, the new settings are applied.
  • If the user does not already belong to a community by that name, Sametime displays the “Add Community” panel with fields filled in with information from the URL. The user verifies and saves the information, and is connected to Sametime.
You can format the URL as a link or as a QR code, and distribute it in email or post it on a web site. The provisioned URL is supported on the following mobile operating systems:
  • Google Android 2.0.1 or later
  • Apple iOS 4.2 or later

Procedure

Provision the URL by completing the following steps:

  1. Build the URL by defining its components:
    The URL is formatted as shown:
    sametime://st_user@stproxy_host:port/?action=AddCommunity&communityName=community_name
    where:
    • sametime:// is a required prefix to ensure that the URL is recognized and processed correctly.
    • st_user the user name of a particular Sametime user; for example, tjwatson@ibm.com.

      If you are sending or posting a URL for use by multiple people, you will probably not want to code a specific user’s ID into the URL because other users may find that confusing. Instead, you can supply a variable or a partial user name and instruct users to modify the URL with the completed user name on their own devices, or you can omit the user name entirely so that each user is prompted for credentials when logging in to Sametime. If you want users to be able to simply click a link or QR code to use the URL, you should omit the user name and allow the user to provide credentials at login.

      Note: In addition, you can optionally instruct users to include the associated password in the URL with the following syntax: st_user:st_password; however this is not a good practice because the password could potentially be consumed by an untrusted app.
    • stproxy_host is the fully qualified host name of the Sametime Proxy Server; for example: stproxy.example.com.
    • port is the port that the Sametime Proxy Server is listening on.
    • ?action=AddCommunity is a required parameter that ensures the information within the URL is added to the mobile client as a community definition.
    • &communityName=community_name is an optional URL-encoded string that provides a name for the new community. If you do not specify a name with this parameter, a default name will be created based on the Sametime Proxy Server's host name.

    Table 1 provides the complete list of parameters that you can include in the URL and indicates whether each parameter is required.

    Table 1. Parameters used in the provisioning URL for mobile users
    Name Value Description
    action AddCommunity Required. This string identifies the URL as an auto-provisioning operation.
    communityName URL-encoded string Optional. A user-friendly nickname for the newly created community. If you do not specify a name with this parameter, a default name will be created based on the Sametime Proxy Server's host name.
    ssl true or false Optional. Indicates whether SSL is enabled for this connection. Default value is true.
    savePassword true or false Optional. Indicates whether passwords are remembered for this connection. Applies to both Sametime and authenticating proxy passwords. Default value is true.
    photoPort 0 - 65535 Optional. Specifies the port to use for sending business card photos to mobile clients. If you have configured Sametime Proxy Server to send a URL for business card photos and the target of that URL is an internal server, you can configure access for external users (such as mobile clients) through a reverse-proxy server and specify the corresponding port here. The default photoPort value is 0, which indicates that the URL specified by the Proxy Server should be used with no substitution.
    authProxyEnabled true or false Optional. Indicates whether the connection requires authentication with a reverse-proxy server. Default value is false. If this parameter is omitted but authenticating proxy credentials are supplied, Sametime behaves if this parameter is set to true.
    authProxyReuseCredentials true Optional but if you include this parameter, you must set it to true. Indicates whether reverse-proxy authentication will use the Sametime user ID and password provided earlier in the URL. If this parameter is omitted but authenticating proxy credentials are supplied, Sametime behaves if this parameter is set to true.
    Examples:
    • Encrypted (SSL) connection to lmc.example.com on port 443 reusing authenticating proxy credentials and supplying a variable for the user name, which each user must replace with their own ID:
      sametime://Your_Sametime_ID@lmc.example.com:443/?action=AddCommunity&ssl=true&authProxyReuseCredentials=true
    • Encrypted (SSL) connection to lmc.example.com on port 8881 reusing credentials, with no credentials specified so that each user will be prompted for credentials when logging into Sametime:
       sametime://lmc.example.com:8881/?action=AddCommunity&ssl=true&authProxyReuseCredentials=true
    • Unencrypted direct connection to stproxy.example.com on port 9080 using a partial user name that provides the domain name but requires each user to insert a user name before clicking the link:
      sametime://@stproxy.example.com:9080/?action=AddCommunity&ssl=false
    • Unencrypted direct connection to server stproxyserver.example.com on port 9080 with no user specified:
      sametime://stproxyserver.example.com:9080/?action=AddCommunity&ssl=false 
    • Unencrypted direct connection to server stproxyserver.example.com on port 9080 with no user specified but the community name is specified as “Sametime Server” :
      sametime://stproxyserver.example.com:9080/?action=AddCommunity&ssl=false&communityName=Sametime%20Server

      To preserve correct URL syntax, the space in "Sametime Server" is represented with %20.

    • Unencrypted direct connection to server stproxyserver.example.com on port 9080 for user dmisawa:
      sametime://dmisawa@stproxyserver.example.com:9080/?action=AddCommunity&ssl=false

      If the user name itself contains the @ symbol you will need to format it as the URL-encoded character %40 to preserve correct syntax, as in dmisawa%40auto_sales

    .
  2. Distribute the URL to mobile users:
    1. Format the URL as a link or use a third-party application to generate a scannable QR code.
    2. Post the link or QR code to a web site, or distribute to users it with email.

      If users need to modify a URL link to provide a user name, make sure you instruct them to do so when you distribute the URL.