11.0 FirstClass Synchronization Services Admin Guide
About FirstClass Synchronization Services
FirstClass Synchronization Services (FCSS) provides SyncML and ActiveSync interfaces for FirstClass systems. SyncML and ActiveSync are industry standard protocols supported by a wide variety of handheld devices and desktop applications as a way to synchronize important user data such as calendar events, contacts, and tasks between a server and those devices/applications.
This release of FCSS runs as a standalone application. It requires a FirstClass 10.0 or 11.0 version of Internet Services and FirstClass core server.
Installing FirstClass Synchronization Services
Before installing FCSS
Before you can install FCSS, you must have a Windows-based Internet Services cluster installed and configured on your system for FCSS to run on. Though FCSS is a standalone application, it uses the infrastructure of an Internet Services cluster.
In many cases, you can run FCSS on an active Internet Services cluster you have already created for other purposes.
 CautionThe exception is if you need to support certain Windows ActiveSync devices. A number of devices that use ActiveSync are not configurable to use any port other than 80. Because Internet Services must use port 80, those devices will not be supported if you install FCSS on an active Internet Services cluster. To support those devices, you need to install FCSS on a separate Internet Services cluster, with a separate IP address, and configure it to use the default Internet Services port 80.
If you need help to understand clusters or to create and configure a cluster, see Clustering Internet Services in Online Help.
Installing FCSS
 NoteYou can use the following procedure whether you're installing FCSS for the first time or have installed a previous version of FCSS in the past.
1 Unzip the contents of the Synchronization Services file.
2 Place the contents in the directory where your Internet Services cluster is installed.
If you've installed FCSS in the past, overwrite those files with the new FCSS files.
After you've installed FCSS, you need to register and configure it before starting it.
Registering FirstClass Synchronization Services
You can register FCSS either as a standalone application server or as a Windows service. Like your server and Internet Services, if you register FCSS as a Windows service it will launch automatically on Windows startup. This means that after an event such as a power failure, it will reboot automatically when Windows reboots.
To register FCSS
1 Choose Start > All Programs > Accessories > Command Prompt on the Windows desktop of the machine where you installed FCSS.
2 Navigate to the FCServer folder on the hard drive where FCSS is installed.
3 Do one of the following:
• To register FCSS as a standalone application server, type fcsync /RegServer and press Enter.
• To register FCSS as a Windows service, type fcsync /Service and press Enter.
A confirmation of registration appears.
If you change your mind any time after you've registered FCSS
1 Type fcsync /UnregServer and press Enter to undo your registration.
2 Register FCSS again.
Your registration will take effect at startup. After you've registered FCSS, you can configure it.
Configuring FirstClass Synchronization Services
Configuring the FCSS port
We recommend you configure FCSS to use port 7962 (spells "sync" on a telephone keypad) unless you need to support Windows ActiveSync devices that can't be configured to use any port other than 80.
Notes
If you need to support Windows ActiveSync devices that can only use port 80, you don't need to configure the port. It defaults to 80.
If you've already configured a previous version of FCSS to use port 8080 or another available port, that will continue to work with this release.
To configure the port
1 Open the inetsvcs.cf file in the FCServer folder on the hard drive where FCSS is installed.
Don't confuse the inetsvcs.cf (configuration) file with the INETSVCS.fc (settings) file used for logging in.
You can right-click the inetsvcs.cf file and open it with Notepad or WordPad.
 TipIt's easier to read and work with the formatting in WordPad.
2 Copy the following text in below any text already in the file:
[SyncServices]
PROTOCOL_PORT = 7962
Configuring other FCSS parameters
You may not need to configure any other FCSS parameters. In many cases the default parameter settings built into FCSS will be all you need. The following is a list of parameters that you can, however, configure in the inetsvcs.cf file to optimize FCSS performance for your circumstances if you wish.
Caution
If your FCSS installation installed an fcsync.cf file, that file is only an example file that lists configuration options. It cannot be used to actually configure FCSS. You must use the [SyncServices] section of the inetsvcs.cf file (in the FCServer folder on the hard drive where FCSS is installed) to configure FCSS.
Configuration parameter |
Function |
SYNCML_MAX_PACKET_SIZE
|
Limits the maximum allowed network packet size in bytes. The default is 0 which makes the maximum network packet size unlimited or controlled by the device. Note This parameter was formerly SYNC_PACKET_SIZE. If you have already configured it with that name it will continue to work with this release. |
SYNCML_ENFORCE_MD5_AUTH
|
0 - Default. Authentication type is determined by the client. 1 - Enforces MD5 authentication Note This parameter was formerly ENFORCE_MD5_AUTH. If you have already configured it with that name it will continue to work with this release. |
ACTIVESYNC_MAX_WINDOW_SIZE |
Sets the maximum number of items that can be sent to the device in one message. Because the device also supplies a maximum window size, the server will use the smaller of the two values. The default is 25. |
ACTIVESYNC_MAX_PING_INTERVAL |
Overrides the device "push" request interval which is usually 8 to 10 minutes. This is the time, in minutes, after which the server will check for and send any updates to the device when ActiveSync "push" is activated. Because the device also supplies a value, the server will use the smaller of the two values. The default is 8. Caution Setting this to 1 or 2 minutes may cause fast battery drainage on some devices.
When set to zero, "push" is effectively disabled. Since it is not actually possible to disable "push" on the device, FCSS sends a status "Wait interval error" back to the device and sets the new minimum wait interval period, in which the device is allowed to initiate a new "push" command, using the MIN_PING_INTERVAL parameter below.
|
ACTIVESYNC_MIN_PING_INTERVAL |
This interval is 30 minutes by default but can be custom set. Effectively, "push" is postponed. This allows the server to logout the client instead of keeping a session logged in as in a normal (every few minutes) push request. Caution We recommended you not turn off "ping" if you are supporting BlackBerry AstraSync clients. AstraSync does not respect protocol restrictions and immediately re-issues a "ping/wait" request. This is even worse for both the device, which is constantly on-air, and for the sync server, which is constantly bombarded by "ping" requests building up TCP connections which can cause a crash. |
ACTIVESYNC_SESSION_TIMEOUT_INTERVAL |
Sets the timeout interval, in seconds, for sessions left alive by a device after a sync is done (some devices do not terminate connections correctly after a sync, leaving a live session to wait for more data). The default is 8. |
ACTIVESYNC_HIGH_VERSION = 140 |
Sets the highest supported ActiveSync protocol version to 14. |
SSL_CERTIFICATE_NAME = <your ssl certificate name>
|
Specifies a valid SSL certificate for use with FCSS. Note You must have placed the valid SSL certificate named here in your Internet Services/SSL Certificates folder for this to work. SSL is not enabled by default. If you need help to understand SSL certificates or how to create and use them, see Internet Services/About security certificates in the Online Help. |
PROTOCOL_SSL_PORT = <ssl port> |
Specifies the port to use for SSL. The default is 443. |
LOG_LEVEL |
Sets the log level at startup, controlling the amount of information displayed on the FCSS console and written to the FCSS log file created and stored daily where FCSS is installed. The log level values are Basic, Verbose, and Debug, Basic providing the least information and Debug the most. The default value is Basic. You can also set log levels on the FCSS console. |
TRACEXX, where xx are index numbers 01, 02...99. |
Sets trace component logging at startup. Trace component logging options allow you to trace specific events and are used only for troubleshooting. The values are TRACE01, TRACE02, TRACE03, etc., as per Trace components menu options: DISPATCHER, TRANSPORT, HTTP, FC_API, FC_API-ENUMERATION, SYNCML_SESSION, SYNCML_DECODE, SYNCML_ENCODE, SYNCML_DECODE_DETAILS, SYNCML_ENCODE_DETAILS, ACTIVESYNC _SESSION, ACTIVESYNC _DECODE, ACTIVESYNC _ENCODE, ACTIVESYNC _DECODE_DETAILS, ACTIVESYNC _ENCODE_DETAILS. You can also set trace component logging on the FCSS console. Note You must set the log level to Debug, as well as selecting trace component logging options, for trace component logging to work. |
SHOW_MY_PEOPLE |
Enables OTSW FirstClass servers to synchronize contacts from My People (people a user follows in OTSW). 0 - Default. My People contents are NOT synchronized to contacts 1 - My People contents are synchronized to contacts Note The My People contacts will be synchronized into a separate "My People" folder. Users with devices that do not support folders or subcontainers will receive contacts from My People as part of their normal contacts list. All contacts from the My People folder will have a
category set to "My People". Caution Any changes to contacts flagged as My People done on the device will not be applied on the FirstClass server. |
DEVICEXY where xy are index numbers 01, 02...etc. |
Populates the device capabilities table. Caution The values for any new device will be supplied by FirstClass. Do not populate the device capabilities table with arbitrary values. This mechanism just enables FCSS to dynamically update the table, with new entries via the inetsvcs.cf file, when new devices with new capabilities are introduced to the market. The values are: type - the device name with which it is registered, for example iPhone, BlackBerry width - the contact picture width in pixels, on the device height - the contact picture height in pixels, on the device subcontainers - the device supports subcontainers, 0=NO, 1=YES addOnSLowSync - the device requires command ADD on Slow Sync refresh, 0=NO, 1=YES Example: DEVICE01 = iPad,64,64,1,1 |
To configure these parameters
Add any parameters that you want to configure anywhere in the [SyncServices] section of the inetsvcs.cf file.
Example:
[SyncServices]
PROTOCOL_PORT = 7962
SYNCML_MAX_PACKET_SIZE = 5000
SYNCML_ENFORCE_MD5_AUTH = 1
ACTIVESYNC_MAX_WINDOW_SIZE = 20
ACTIVESYNC_MAX_PING_INTERVAL = 5
ACTIVESYNC_SESSION_TIMEOUT_INTERVAL = 5
ACTIVESYNC_HIGH_VERSION = 120
SSL_CERTIFICATE_NAME = <your ssl certificate name>
PROTOCOL_SSL_PORT = 443
SHOW_MY_PEOPLE = 1
Example configuration for a normal debug startup with basic component tracing:
LOG_LEVEL = DEBUG
TRACE01 = SYNCML_SESSION
TRACE02 = SYNCML_DECODE
TRACE03 = SYNCML_ENCODE
TRACE04 = ACTIVESYNC_SESSION
TRACE05 = ACTIVESYNC_DECODE
TRACE06 = ACTIVESYNC_ENCODE
TRACE07 = FC_API
Your configuration changes will take effect at startup. After you've installed, registered, and configured FCSS, you can start it.
Licensing FirstClass Synchronization Services
You can run FCSS without a license. In this mode it will support the first 50 users who log in. This is useful for small systems with limited users accessing FCSS and for larger sites that want to evaluate FCSS prior to widespread deployment. Once you install a license, all of the users on your FirstClass system can use FCSS.
To install an FCSS license
1 Choose Admin > System Profile on the administrator's Desktop.
2 Click Apply License File(s) on the Licensing tab.
3 Browse to the location of your FCSS license file and select the text (nnnnnnn.LIC).
The uploaded file appears in "License application results" and "Licensing summary".
Administering FirstClass Synchronization Services
Checking FCSS status with a web browser
Command |
Function |
ping |
Checks to see if FCSS is running. Recommended method. Does not log in to the server and does not return detailed FCSS info. |
info |
Provides detailed FCSS status. Caution Not recommended unless necessary. Logs in to the server and provides detailed information. Is an "expensive" operation that can degrade server performance. |
To use the ping or info command, type the IP address and relevant command in the address window of your web browser and press Enter.
Example: 127.0.0.1/fcss+ping
If using other than port 80, add the port number.
Example: 127.0.0.1:7962/fcss+ping
Checking FCSS status with the Synchronization Services console
1 Choose Start > All Programs > Accessories > Command Prompt on the Windows desktop of the machine where you installed FCSS.
2 Navigate to the FCServer folder on the hard drive where FCSS is installed.
3 Type fcsync
The console opens, detailing the current FCSS version, configuration settings, and status.
Administering FCSS with the Synchronization Services console
You administer FCSS from the Control menu on the FCSS console.
Command |
Function |
Enable Sync |
Enables synchronization (if previously disabled) |
Disable Sync |
Disables synchronization |
Reset System |
Terminates all sessions and connections, and restarts synchronization server |
List Connections |
Lists the currently active connections on the Synchronization Services console |
List Sessions |
Lists the currently active sessions on the Synchronization Services console |
FirstClass Synchronization Services logging
FCSS automatically logs activity as text files in the FCServer folder where FCSS is installed.
The FCSS logs are named FCSYNC_yyyy_mm_dd_hh_mm_ss.txt, where:
• yyyy, mm, dd, is the date (year, month, day) that the logging was started
• hh, mm, ss is the time (hours, minutes, seconds) that logging was shutdown.
If FCSS is still running at midnight each day, the old log is closed and a new log is created.
The type and amount of information displayed on the FCSS console and written to the log depends on the logging level you set.
To set the logging level
1 Open the FCSS console.
2 Choose Log Level.
3 Select the logging level you desire.
The log levels are: Quiet, Basic, Verbose, and Debug. Quiet provides the least amount of logging information, Debug provides the most. The default is Basic.
Trace component logging options allow you to trace specific events and are used only for troubleshooting.
Note
You must set the log level to Debug, as well as selecting trace component logging options, for trace component logging to work.
FirstClass Synchronization Services notifications to users on errors
FCSS automatically provides notifications to users' FirstClass mailboxes whenever a condition exists that needs user attention and/or intervention, as follows:
- a "push" is detected (the message warns the user that it may have detrimental effects on the device battery life)
- an attempt to register a fifth device is detected
- a picture is not synced because of a corrupt contact picture
- a new device is registered (this is just an informational message).
| 
