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:
- 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 usersName |
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
.
- Distribute the URL to mobile users:
- Format the URL as a link or use a third-party application
to generate a scannable QR code.
- 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.