Häufig gestellte ragen

Antworten auf die am häufigsten gestellten Fragen zum OnTime® Gruppenkalender

Haben Sie Fragen zum OnTime Gruppenkalender? Vielleicht finden Sie ja die Antwort bereits unten. Falls Sie nicht fündig werden, wenden Sie sich bitte mit Ihren Fragen an uns, wir freuen uns, Ihnen weiterzuhelfen.

Administration

User debug - How do I enable it?

Please note: The approach described in this document was added in v. 4.2.

User debugging consists of two elements:

  1. API logging to see what traffic is being sent between the OnTime Group Calendar clients (or API) and the OnTime Group Calendar server.
  2. Extended synchronization logging that  enabled to the user in question to help diagnose specific sychronization issues for a particular user. This is similar to enabling extended log in an OnTime Server Document for only for specific users and is hence much more lightweight.

Prior to v. 4.2 user synchronization logging and API logging was enabled separately and in different ways. This is now much easier to enable.

Enabling user debug for one or more users are done as follows:

  1. Open the OnTime Group Calendar Configuration database.
  2. Go to the "Users" view in the left hand navigator.
  3. Select the user(s) to enable/disable user logging for.
  4. From the action bar select "Selected/Debug/Enabled" to enable debugging and "Selected/Debug/Disable" to disable debugging.
  5. A magnifying glass is shown to the right of the names where user debugging is enabled.
  6. Now reproduce the issue and send the OnTime Group Calendar log database to OnTime support as arranged with us.

Remember to disable user debugging once the issue has been reproduced.

API logging - How do I enable it? (before v. 4.0.0)

Enabling API logging enables OnTime support to see what traffic is being sent between the OnTime Group Calendar clients (or API) and the OnTime Group Calendar server. Enabling API logging is done by following the steps below:

Please note: The approach described in this document was changed in v. 4.0

  1. Locate the OnTime Group Calendar Configuration database on your workspace and make sure you have the [Developer] role assigned to you in the ACL of the database. Please note that you may have to create the role if it hasn't yet been created.
  2. Open the OnTime Group Calendar Configuration database.
  3. Go to the "Server Settings" by clicking "Server Settings" at the top of the left hand navigator.
  4. Open the server settings document for the server you will be accessing to reproduce the issue (or just open the one server settings document if you only have one OnTime Group Calendar server).
  5. Bring the document into edit mode and check the "Log API Comm." check box on the lower right side of the form.
  6. Save and close the document.
  7. Now reproduce the issue and send the OnTime Group Calendar log database to OnTime support as arranged with us.

Remember to turn off API logging once the issue has been reproduced as having API logging enabled may affect the performance of your server.

API logging - How do I enable it from the clients?

Please note: The approach described in this document was added in v. 4.0

Enabling API logging enables OnTime support to see what traffic is being sent between the OnTime Group Calendar clients (or API) and the OnTime Group Calendar server. API logging may be enabled from the OnTime Group Calendar client to from the server. This document describes how API logging is enabled from the client. 

Web client

Opening the Web client is done through the Client database e.g. using a URL like the following:
http://demo.ontimesuite.com/ontime/ontimegcweb.nsf/web?open

To Enable API logging from the client append debug=1 to the url as follows:
http://demo.ontimesuite.com/ontime/ontimegcweb.nsf/web?open&debug=1

Notes

To enable API logging from the OnTime Group Calendar Notes client open the client and open the "OnTime" from the top menu, select the "Help" submenu and then "Enable API Log". API logging is enabled until explicitly disabled or the IBM Notes client is restarted.

Mobile

It's currently not possible to enable API logging from the client. From v. 4.2 an option to enable API logging from the server was added.

Team-At-A-Glance

It's currently not possible to enable API logging from the client. From v. 4.2 an option to enable API logging from the server was added.

Social

It's currently not possible to enable API logging from the client. From v. 4.2 an option to enable API logging from the server was added.

Can I use same license key for both GC 9.x and the new GC 4.x/3.x product?

No, the OnTime Group Calendar 9 series and the OnTime Group Calendar version 3 are two totally different products and therefore also have seperate license keys.

Please contact your prefered OnTime partner or IntraVision in order to retreive a new license key.

Which OnTime Group Calendar databases may be clustered?

OnTime Group Calendar is fault tolerant and support clustering on IBM Domino but please note that not all databases in the OnTime Group Calendar installation should be clustered. The API database and the Web database are only used to serve up the Web and Mobile interfaces and to temporarily store documents related to the OnTime Group Calendar API. These two databases are not designed for clustering and hence should not be clustered as it may cause the clients to fail. Whether you choose to cluster the log database is up to the customer.

How are groups resolved when the multi-domain option is enabled?

You may run OnTime Group Calendar even though you are running multiple domains in your IBM Domino environment but it does pose some additional challenges when names and groups need to be resolved. In general the only requirement that OnTime Group Calendar imposes when running in multi-domain configuration is that all the Domino Directories from the other Domino domains must be replicated to the Domino server running the admin-task. OnTime Group Calendar does not however require Directory Assistance or similar to be configured.

Configuring the multi-domain option is very simple and generally only consists of adding references to the various Domino Directory databases and mapping each to a Domino domain. This is very clearly described in the OnTime Group Calendar Installation manual.

Resolving groups

When using the multi-domain option special care needs to be taken when group names are specified. All group names may have the domain name appended to explicitly tell OnTime Group Calendar which Domino Directory to use when resolving the group. If nested groups are used they are resolved against the same Domino Directory as the parent group. If no domain is specified for a group OnTime Group Calendar will look to the group in allconfigured Domino Directory databases and resolve the group as being the combination of users from across directories.

Configuration example

Consider an IBM Domino environment with three domains called US, EU and JP and an organizational certifier called /ACME. The OnTime Group Calendar admin-task is designated to run on the OnTimeServer/ACME server in the EU domain. To enable the multi-domain option the administrator would perform the following steps:

  1. Replicate the Domino Directory for the US and JP domains to the OnTimeServer/ACME server in the EU domain.
  2. In the OnTime Group Calendar configuration database enable the multi-domain option mapping each Domino Directory to the corresponding domain.
  3. Make sure all groups used in the OnTime Group Calendar configuration is qualified with a domain name. E.g. the group SalesEurope from the EU Domino Directory should be SalesEurope@EU to explicitly tell OnTime how to resolve the group.

Group resolving example

Imagine the following groups from the Domino Directories mentioned above.

EU domain

  • SalesEurope (members: Jane Ellen/ACME@EU, Marc Rogers/ACME@EU)
  • Administrators (members: Pete Sams/ACME@EU)

US domain

  • SalesUS (members: Sales@US)
  • Sales (members: John Ops/ACME@US, Eileen Hums/ACME@US)
  • Administrators (members: Marc Willis/ACME@US)

JP domain

  • SalesJP (members: Sales@JP)
  • Sales (members: Jiro Tokyo/ACME@JP, Masuru Heiku/ACME@JP)
  • Administrators (members: Jiro Tokyo/ACME@JP)

Below are examples from resolving the specified group names using the Domino Directories above.

  • SalesEurope (result: Jane Ellen/ACME@EU, Marc Rogers/ACME@EU)
  • SalesEurope@EU (result: Jane Ellen/ACME@EU, Marc Rogers/ACME@EU)
  • Administrators@JP (result: Jiro Tokyo/ACME@JP)
  • Administrators@US (result: Marc Willis/ACME@US)
  • Administrators (result: Pete Sams/ACME@EU, Marc Willis/ACME@US, Jiro Tokyo/ACME@JP)
    Please note: Resolved against all directories as no domain name is specified for the group and the group exists in all directories)
  • Sales@US (result: John Ops/ACME@US, Eileen Hums/ACME@US)
  • Sales (result: John Ops/ACME@US, Eileen Hums/ACME@US, Jiro Tokyo/ACME@JP, Masuru Heiku/ACME@JP)
    Please note: Resolved against US and JP directories as no domain name is specified for the group name was found in both the US and JP directories.
How do I clean up the OnTime logs on request?

The logs are cleaned up as part of the clean-up process that runs automatically at 2am. If you want to run the log clean up on request issue the below command from the Domino Server console.

tell ontimegc cleanup

How do I roll-out the widgets in our environment?
Just follow normal IBM guidelines on deploying widgets in the Domino/Notes environment.

RELATED LINKS

Missing legend colors - all appointments appear with default legend color

If you experience only having the default legend color on all appointments in OnTime Group Calendar user interfaces but have legends in the OnTime Group Calendar Configuration database a database setting may be the cause. To resolve it please beform the following steps:

  1. Open the database properties on the OnTime Group Calendar Configuration database.
  2. Go to the last tab ("the beanie").
  3. Verify that the 'Don't support specialized response hierachy' property is NOT set. If it is this is the cause.
  4. Untick the property.
  5. Close the database
  6. Terminate the OnTimeGC task on the Domino Server console (tell ontimegc quit).
  7. Delete all Legends from the OnTime Group Calendar Configuration database.
  8. Fetch the Default Legends by pushing the 'Deefault Legends' button (top right corner of the Legends view).
  9. Verify that nobody has the OnTime Configuration database open and run a copy-style compaction on the database (load compact -c <path  to database>'). Please note: Since the database may be in use you may have to flush dbcache or similar to make the compact work (dbcache flush).
  10. Load the OnTime task (load ontimegc)
  11. Run FullSync on all users

If the above steps doesn't resolve the issue please contact OnTime support.

Photo db: Stacktrace displayed on IBM Domino Console, when the 'Get Photo from Connection' agent runs

If you are using a self-signed SSL certificate or a certificate that Domino doesn't trust you will see an error on your Domino console whenever the Photo Db agent run. To make the agent run successfully you have to import the certificate of the IBM Connections endpoint (IBM HTTP Server) into the Java keystore utilized by Domino.

How to install a SSL certificat in the Domino keystore.

1. Open a Command prompt

2. Navigate to the security-folder on the Domino Servers jvm-directory (e.g. D:\Domino\jvm\lib\security).

3. Optional: If you want to see the current certificates
..\..\bin\keytool.exe -keystore cacerts -list

Please note: The default password for the keystore is: "changeit"

4. Export the certificate of the IBM Connections endpoint using a web browser 
(e.g. using Firefox) in DER-format 

5. Copy the DER-file you exported to the security-folder of the Domino server
(e.g. D:\Domino\jvm\lib\security).

6. Import the certificate as a trusted certificate into the keystore

..\..\bin\keytool.exe -keystore cacerts -import -v -trustcacerts -alias <some alias> -file <certificate DER file>

If the certificate file is called cert.der and the alias should be ibm_connections use the following command:

..\..\bin\keytool.exe -keystore cacerts -import -v -trustcacerts -alias ibm_connections -file cert.der

7. Verify cert is imported and trusted (alias set to ibm_connections)

..\..\bin\keytool.exe -keystore cacerts -list -alias ibm_connections

8. Restart the agent manager in Domino

Is there any Domino Server settings that needs to be set?

Please note: If you are using the servlet to improve performance for HTTP based calls the below information is not applicable.

There are a few Domino Server settings that needs to be set to make sure OnTime Group Calendar runs as smoothly as possible. These are listed below.

Concurrently web agents

On the server document in the Domino Directory on the "Internet Protocols/Domino Web Engine" there is a setting called "Run web agents and web services concurrently?" that needs to be enabled. This setting is disabled by default and restricts Domino from running the same agent concurrently.

Authentication

The OnTime Group Calendar web interface only supports form based authentication also known as "Multiple Servers (SSO)". Whether you use LtpaToken or LtpaToken2 is up to you.

Proxy support for OnTime Group Calendar for IBM hybrid

Available from v. 4.6

If you require outgoing requests from the IBM Domino server to an on-premises Microsoft Exchange server or to Microsoft Office 365 to be proxied this is configured using servlets.properties. The following parameters are available to support HTTP proxying: 

  • ProxyHost
  • ProxyPort

Below is an example of adding a proxy host (proxy.example.com) on port 8080 to the configuration:

servlet.ontimegcex.code=com.ontimesuite.gcex.OnTimeGCEx
servlet.ontimegcex.initArgs=ProxyHost=proxy.example.com,ProxyPort=8080

More information on the OnTime Group Calendar Administration task

By default the OnTime Group Calendar Administration task ("admin") runs every night at 2am on the OnTime Group Calendar Administration Server. The admin-task can also be initiated on demand from the OnTime Group Calendar Config database or from the IBM Domino Server console using "tell ontimegc admin". 

One of the purposes of the admin-task is to process information read by the synchronization process from mail files into the Configuration database such as mail file Access Control List (ACL), calendar settings profile document (work hours etc.) In OnTime Group Calendar each user has 3 documents:

  • User document (maintained by the admin-task)
  • Calendar document (maintained by the synchronization task, created on first synchronization of a user)
  • Settings document

It's important to know that all user based calls to OnTime Group Calendar is processed from the "user document" and hence the admin-task is required to run to "bring in" information read from the mail file. For instance if a user changes his/her work hours in the mail file OnTime Group Calendar will first need to synchronize the user (reads information from the mail file into into the "calendar document") and then run the admin-task to transfer the information from the "calendar document" to the "user document". OnTime Group Calendar maintains a very strict separation between which tasks may write to which documents to avoid data corruption and save/replica conflicts.

Sometimes the admin-task will take a while to run - sometimes even a long time if you have many thousands of users in OnTime Group Calendar. This is of course because the admin-task does a lot of things from maintaning users from associated directories to maintaining groups and groups membership. That doesn't mean that moving the admin-task to a separate server cannot be a good idea as it certainly will optimize I/O but it describes why the task may take a while to run.

Please note:  For most organisations there should be no need to run admin during the day or even multiple times a day. It runs daily at 2am.

If you need to run the admin-task during the day consider using one of the sub-commands to tell the admin-task exactly what you would like it to do. If you only want to process static groups i.e. update group membership you could run "tell ontimegc admin gs" from the IBM Domino Server console. 

All of the "sub commands" from the admin-task is available to be run separately as shown in the below table. The sub-commands are listed in the actual sequence they are run.

Description

Console Command

Load*

Day**

Hour***

Update users
Reads in users, rooms and resources from the Domino Directories setup in OnTime Group Calendar. This operation also transfers certain pieces of information from the "calendar document" to the "user document" i.e. work hours etc. read from the mail files during synchronization of users.

tell ontimegc admin u

X

X

 

Fixup / cleanup
Does maintenance work associated with the internal data structures when required during upgrade between versions.

tell ontimegc admin f

X

X

 

Static groups
Processes static groups as configured in OnTime Group Calendar considering users currently in OnTime Group Calendar e.g. that must have been brought into OnTime Group Calendar by the "users sub-command" first. The process also makes sure that private groups does not contain invalid users.

tell ontimegc admin gs

X

X

 

Dynamic groups
Processes dynamic group definitions as configured in OnTime Group Calendar considering users currently in OnTime Group Calendar e.g. that must have been brought into OnTime Group Calendar by the "users sub-command" first.

tell ontimegc admin gd

X

X

 

External groups
Processes external groups as configured in OnTime Group Calendar considering users currently in OnTime Group Calendar e.g. that must have been brought into OnTime Group Calendar by the "users sub-command" first.

tell ontimegc admin ge

X

X

 

Directory (NAB) groups
Processes Domino Directory groups ("NAB") as configured in OnTime Group Calendar considering users currently in OnTime Group Calendar e.g. that must have been brought into OnTime Group Calendar by the "users sub-command" first.

tell ontimegc admin gn

X

X

 

Process ACLs
Reads the mail file ACL read during the synchronization of a user and writes the exploded result to the "users document" for the particular user.

tell ontimegc admin a

X

X

 

Process roles
Processes the role definitions according to the rules and assigns roles to users. Required to run for a change in a role to take effect.

tell ontimegc admin r

X

X

 

Rooms and resources
Reads information for rooms and resources as read from the coresponding room and resource database during synchronization. This process updates information such as capacity, restriction on rooms etc. meaning data maintained in the room and resource database(s).

tell ontimegc admin o

X

X

 

Process settings
Assigns Default Settings to users based on the configuration in the OnTime Group Calendar Configuration database. Changing Default Setting documents requires this command to be run to take effect.

tell ontimegc admin s

X

X

 

Cutom fields
Computes restrictions for custom fields and copies info to the user document.

tell ontimegc admin c

   

X

Process replica documents
Cleans up mail file replica information generated by the OnTime Group Calendar cluster sub-system.

tell ontimegc admin e X X  

* When task loads on OnTime GC admin server
** Daily job that runs at 2am
*** Job that runs every hour

Please note: Starting from version 4.2.2 you can now control which admin sub-commands run on which days and on load in Global Settings. You also have the option of terminating a running admin-task by issuing the follow command on the IBM Domino Server console.

Set Config OnTimeGCAdmin=Quit

How does OnTime Group Calendar handle recertification and users getting new person documents in Domino Directory?

Internally in OnTime Group Calendar users are identified by a socalled OnTime ID which is a short, unique, ID. The OnTime ID first created for a user when he/she is brought into OnTime Group Calendar and is thereafter maintained by the administration task.

For each user OnTime records the fully distinguished name (DN, e.g. CN=John Doe/OU=Sales/O=Acme) as well as the UnID of the person document. Whenever a user is processed as part of the administration task the user in OnTime can be found using either the DN or the UnID. This means that a user in OnTime will keep their OnTime ID even though that are recertified (get new name, new organisational hierarchy) or a new person document is created for the same user (same DN). Since the OnTime ID stays the same the user also keeps their private groups.

It follows from the above, that a user cannot change both DN and Domino Directory UnID at the same time while keeping their OnTime ID.

Why am I seeing java.lang.ThreadDeath messages from OnTime Group Calendar on the server console?

Please note: This applies to using the agent based API for OnTime Group Calendar.

Agents in IBM Domino has a maximum execution time at which point the thread execuring the agent is terminated. By default the maximum agent execution time in IBM Domino Directory is set to 0 meaning there is no maximum execution time. If for some reason the maximum execution time has been changed the following stacktrace may be seen on the Domino server console.

HTTP JVM: java.lang.ThreadDeath
HTTP JVM: at java.lang.Thread.stop(Thread.java:941)
HTTP JVM: at java.lang.ThreadGroup.stopHelper(ThreadGroup.java:722)
HTTP JVM: at java.lang.ThreadGroup.stopHelper(ThreadGroup.java:727)
HTTP JVM: at java.lang.ThreadGroup.stop(ThreadGroup.java:704)
HTTP JVM: at lotus.domino.AgentLoader.runAgent(Unknown Source)

This message indicates that an agent thread ran for too long time and was terminated. If you are repeatedly seeing this message we suggest you review your maximum agent execution time and make sure it is appropriate.

A solution could be to start using the servlet which also provides better performance.

How do I monitor which clients and in what version users connect with?

Starting with OnTime Group Calendar v. 4.2, for each user connecting to OnTime Group Calendar, we log the client name (Application ID, ApplID) and the client version (Application Version, ApplVer). The information is logged automatically and saved to the user setting document for each user. To see the actual user settings documents do the following:

  1. Assign the [Developer] role to your self in OnTime Group Calendar Configuration database.
  2. Open the OnTime Group Calendar Configuration database.
  3. In the "Developer" section on the left open the "Users Settings" view.

This view contains all the user setting documents. These documents has a number of backend fields - two fields per client (more specifically Application ID) as follows:

SettingsRead_<Application ID>_Ver
SettingsRead_<Application ID>_Time

For instance a user accessing OnTime Group Calendar using the OnTime GC Notes client (Application ID: Notes2011), Team-At-A-Glance sidebar component (Application ID: TAAG2011) and OnTime Group Calendar Mobile (Application ID: Mobile2011) will have the following 6 fields:

SettingsRead_Notes2011_Ver = "4.3.0.201507231633"
SettingsRead_Notes2011_Time = "03/08/2015 10:19:43 CEDT"
SettingsRead_TAAG2011_Ver = "4.3.0.201507231633"
SettingsRead_TAAG2011_Time = "31/07/2015 17:19:43 CEDT"
SettingsRead_Mobile2011_Ver = "4.2.2a"
SettingsRead_Mobile2011_Time = "12/07/2015 00:38:54 CEDT"

At the time of this writing this information is not surfaced in the user interface but is accessible using agents or manual access using the Document Property Explorer in IBM Notes.

What information is required in Domino Directory for a user to be considered for OnTime?

The below information must be set on the person document in Domino Directory for a person to be considered for import into OnTime Group Calendar. Please note that the user must also be included by the filter in Global Settings.

  • User must have a mail server (field "MailServer" in Domino Directory)
  • User must have a mail file (field "MailFile" in Domino Directory)
  • User must have a fullname (field "FullName" in Domino Directory)
  • User must have Mail System set to one of the following values:
    • "Notes mail" (field "MailSystem" set to "1" in Domino Directory)
    • "POP or IMAP mail" (field "MailSystem" set to "6" in Domino Directory)

If you use OnTime Group Calendar for IBM in a hybrid scenario where OnTime Group Calendar for IBM contains both IBM Domino and Microsoft Exchange users the Microsoft Exchange users must be defined in Domino Directory. The person documents must also have the following fields set:

  • User must have Mail System set to  something else than one of the following values:
    • "Notes mail" (field "MailSystem" set to "1" in Domino Directory)
    • "POP or IMAP mail" (field "MailSystem" set to "6" in Domino Directory)
  • User must have an email address set (field "InternetAddress" in Domino Directory)

Please note: The email address is used to map from the users in OnTime Group Calendars to users in Microsoft Exchange.

Why am I repeatedly seeing OnTimeGC WANING messages on the server console about access to non-OnTime and non-mail databases?

The OnTime Group Calendar server task listens to events on the Domino servers being monitored in order for OnTime Group Calendar to synchronize calendar entries from mail files. Part of this process is discovering the replica ID of the databases to support OnTime clustering among other things. To discover the replica ID the OnTime Group Calendar server require access to the databases even though they may not be a mail database or an OnTime Group Calendar system database.

See a message similar to the following means that the OnTime Group Calendar server does not have access to the listed database:
OnTime-server01: WARNING: CN=Server01/O=OnTime!!IBM_ID_VAULT\MyIDVault.nsf: You are not authorized perform that operation

To not see the message the OnTime Group Calendar should have at least "No access w/ read public documents" access to the database. With this low access OnTime Group Calendar can discover the replica ID without having access to contained data.

Web Interface

Problems launching the client - Need help?

Do you have problems launching OnTime GC Web after installing and setting up, then you can try to open the test page.

The test page can be found if you add "/test" after the normal path to the web database. http://<path>/<ontimegcweb database (.nsf)>/test

Here you can, amongst others, validate if the path to the config database is correct. 

Why Anonymous and Default need Author access?

The reason for Anonymous to have Author access with create rights on the web database:

To solve the problem with people having to log in every time they open the OnTime GC Web database, be it in a browser on the computer or a phone or inside the notes platform, we created an alternative form of handling the authenticating of users.

When the user tries to open the web database for the first time, we check the local computer for a cookie. This cookie contains the Token which we are using to Authenticate the user. Since its the first time, the cookie wont be there, so the user will be presented with a normal login screen. When the user has provided his login credentials, a token will be generated and saved in a cookie for future use. A token document is also created in the Web database. This is why the user needs the Create Document rights. The next time the user opens the web database, the cookie provides the token for authentication, and the user will not be presented with the authentication screen again.

If the user logs out using the logout function in OnTime GC Web, the cookie is deleted and the user has to log in again, the next time the user opens the web database.

If the user hasn't used the web database for a month, the cookie will be too old, and again the user has to log in the next time the user opens the web database.

In the OnTime GC Database, the administrator can alter the token lifespan for each user. If its set to 2 days, then the user has to log in every 2 days. 

Why do I have to login every time?

There can be 2 reasons to why you have to login every time:

  1. Your administrator has not set the correct Acces Control on the web database regarding Anonymous access. Described in the Installation manual
  2. You Domino environment use SSL and TCP Authentication for Anonymous is set to "No". Contact your Domino administrator
Login screen do not disappear after attempt login

Cookies can be blocked by the browser, therefore check the security settings to set allow cookies for the website.

Error when loading about user not found in Group Calendar Database

To use the web database, the user you use for authentication must be in the ontimegc.nsf database, since its otherwise impossible to find the user credentials for accessing peoples calendars.

Error 501 - Not implemented

Basic Authentication enabled and OTGC web 2011 is not supported for that.

Create Site document for website and Enable SSO (LTPAToken).

 

Application Settings for the Web Interface

This FAQ outlines the different application settings available to change the default behaviour of the OnTime Group Calendar Web Interface.

Application settings are configured from the OnTime Config DB using the "Default Settings" as shown below.

 

Default Settings

 

Below you will find a section per setting and a description of the setting.

 

AvatarBorderRadius

This application setting allows you to control whether photos should be displayed as squares or circles in the interface. This setting takes values between 0 and 50 where 0 equals square and 50 round.

CalItemBodyHeightExtra

This application setting allows control over additional height of the body field on calendar entries in pixels.

CalItemReread

To avoid conflicts when saving edited entries, the client will refetch data from the back end, before the user is presented with the calendar entry dialogue box. This setting takes the value true or false. This resembles doing a refresh (F9) before opening the entry for editing.

FreeTimeSearchDays

Changes the number of days into the future the clients will perform a freetime search. The default value is 93 days (3 months). Use this setting to override the value. If <= 0 we use the default value.

MaxUsersInGroups

This setting controls how many users can be added to a private or a shared group. The default value is 200 but can be increased. It is however important that the total size of the combined names never exceed 32Kb.

NoWeeksInWeeksView

Allows you to show more than the default 2 weeks in the weeks view.

NoWeeksInVacationView

Allows you to show more than the default 8 weeks in the weeks view.

PageSize

This setting controls how many users are loaded at a time in the main view. This setting can be increaed in newer browsers but older browsers can run out of memory if you increase this setting.

UserListRowHeight

This setting controls whether 1,2 or 3 lines of information from the name format should be displayed in the name selection dialogue boxes.

Mobiles Interface

Missing Icons in the OnTime Mobile client?

If you are experiencing that the OnTime Mobile client is missing the top icons or they are shown as small squares with numbers, there is a possible solution to the problem.

On the Domino server, there is a file in the data directory called httpd.cnf. This holds the mapping to which file types the domino can understand. This file is not touched, when
the Domino server is upgraded, so if you have been continually upgrading from older versions, this file might not contain all the recent values.

An excerpt from this file may look like the following:

#
# Text formats
#
AddType .html text/html 8bit # HTML
AddType .htm text/html 8bit # HTML variant
AddType .htmls text/html 8bit # HTML w/ Server-side includes
AddType .shtml text/html 8bit # HTML w/ Server-side includes
AddType .css text/css 8bit # Cascading Style Sheet
AddType .xml text/xml 8bit # XML
...continuing.
.
.

If the type .css is missing here, the domino server returns a mime header as a binary file instead of a text/css type file and the browsers wont understand the format.
To solve the missing Icons problem, simply add the .css line to your httpd.cnf file and restart the http task on the domino server (restart task http).

IBM Connections User Interface

Widget XML snippets (OnTime Group Calendar - Social version 3.7.0 to 4.2.x

Please note that this snippet file is applicable for OnTime Group Calendar - Social version 3.7.0 to 4.2.x.

Please note: These snippets are no longer used for version 4.3.0 and newer.

Profiles - widgets-config.xml

<!-- OnTime Group Calendar - Social - Profiles for IBM Connections -->
<widgetDef defId="ontimeProfilesCalendar" bundleRefId="ontimeProfilesCalendar_res" url="/ontime/profiles/Profiles.xml" modes="view">
<itemSet>
<item name="resourceId" value="{resourceId}"/>
</itemSet>
</widgetDef>

<widgetInstance uiLocation="col3" defIdRef="ontimeProfilesCalendar" />

Profiles - lotusconnections-config.xml

<resources>
<widgetBundle name="com.ontimesuite.gc.social.profiles" prefix="ontimeProfilesCalendar_res"/>
</resources>

Communities - widgets-config.xml

<!-- OnTime Group Calendar – Socal – Communities for IBM Connections -->
<widgetDef defId="ontimeCommunitiesAvailability" bundleRefId="ontimeCommunitiesAvailability_res" modes="view" showInPalette="false" uniqueInstance="true" url="/ontime/communities/Availability.xml">
<itemSet>
<item name="resourceId" value="{resourceId}"/>
</itemSet>
</widgetDef>

<widgetDef defId="ontimeCommunitiesCalendar" bundleRefId="ontimeCommunitiesCalendar_res" modes="view fullpage" showInPalette="true" uniqueInstance="true" url="/ontime/communities/Calendar.xml">
<itemSet>
<item name="resourceId" value="{resourceId}"/>
</itemSet>
</widgetDef>

<widgetInstance uiLocation="col3" defIdRef="ontimeCommunitiesAvailability" />

Communities - lotusconnections-config.xml

<resources>
<widgetBundle name="com.ontimesuite.gc.social.communities.availability" prefix="ontimeCommunitiesAvailability_res" />
<widgetBundle name="com.ontimesuite.gc.social.communities.calendar" prefix="ontimeCommunitiesCalendar_res" />
</resources>

Enable trace logging - version 4.2.x and older

Please note: The below applies only to version 4.2.x and older.

If instructed to enable trace logging for the OnTime Group Calendar - Social server side components follow the below steps:

  1. Log into the WebSphere ISC on the Deployment Manager
  2. From the lefthand menu select "Troubleshooting/Logs and trace"
  3. Click on the server running the "OnTime Group Calendar - Common" application (if multiple servers are in running the application the following steps need to be performed for each server running the application)
  4. Select "Change Log Detail Levels"
  5. Click the "Runtime" tab
  6. In the text box append ": com.ontimesuite.gc.social=all: dk.intravision.http=all: com.ontimesuite.gc2011.api.http=all" (please note the leading colon). 
    Please note: For most installations this means that the field value will now be "*=info: com.ontimesuite.gc.social=all: dk.intravision.http=all: com.ontimesuite.gc2011.api.http=all"
  7. Click Apply (a status message will appear at the top saying "Note: your specified trace string was optimized")

Reproduce the issue and send us the trace.log file which will be saved to the log directory of the server(s) in question.

Please note: You do not need to restart the WebSphere Application Server(s) to apply trace logging using the above approach.

Please note: Enabling trace logging will output LtpaTokens, usernames and passwords as clear text to the trace.log so please handle it appropriately.

Enable trace logging - version 4.3.x and newer

Please note: The below applies only to version 4.3.0 and newer.

If instructed to enable trace logging for the OnTime Group Calendar - Social server side components follow the below steps:

  1. Log into the WebSphere ISC on the Deployment Manager
  2. From the lefthand menu select "Troubleshooting/Logs and trace"
  3. Click on the server running the "OnTime Group Calendar - Common" application (if multiple servers are in running the application the following steps need to be performed for each server running the application)
  4. Select "Change Log Detail Levels"
  5. Click the "Runtime" tab
  6. In the text box append ": com.ontimesuite.gc.social.*=all: dk.intravision.http=all: com.ontimesuite.gc.api=all: com.ontimesuite.gc.api.http=all" (please note the leading colon). 
    Please note: For most installations this means that the field value will now be "*=info: com.ontimesuite.gc.social.*=all: dk.intravision.http=all: com.ontimesuite.gc.api=all: com.ontimesuite.gc.api.http=all"
  7. Click Apply (a status message will appear at the top saying "Note: your specified trace string was optimized")

Reproduce the issue and send us the trace.log file which will be saved to the log directory of the server(s) in question.

Please note: You do not need to restart the WebSphere Application Server(s) to apply trace logging using the above approach.

Please note: Enabling trace logging will output LtpaTokens, usernames and passwords as clear text to the trace.log so please handle it appropriately.

How do I trust a SSL certificate in the WebSphere Application Server ISC?

Please refer to the Youtube video below describing how to trust SSL certificates in the WebSphere Application Server Integrated Solutions Console (ISC).

Related Links:

How can I troubleshoot OnTime Group Calendar Socials ability to resolve network, following, communities etc.?

Starting with OnTime Group Calendar Social v. 4.4.0 the following debug capabilities are available to debug various aspects of the application.

/ontime/common/api/wim/currentuser
Resolves the currently logged in user in WebSphere Identity Manager (WIM) showing the name, uid and e-mail address is available. 

/ontime/common/api/cnx/following
Shows the e-mail addresses of the people the currently logged in user is following.

/ontime/common/api/cnx/network
Shows the e-mail addresses of the people the currently logged in user is in network with.

/ontime/common/api/cnx/community/<community uuid>
When supplied with a community UUID will resolve the members of the community and show the e-mail addresses of the members. The currently logged in user must have access to the community in IBM Connection.

Example:
/ontime/common/api/cnx/community/6840ee81-0e19-4418-8b7b-3b1a02c69041

/ontime/common/admin/test
Opens the Test Page as described in the manual. Require the admin-role.

/ontime/common/admin/wim/currentuser
Same as /ontime/common/api/currentuser but requires the admin-role.

/ontime/common/admin/wim/searchuser/email/<email address>
Searches for the supplied e-mail address in WebSphere Identity Manager and shows the name, uid and e-mail address of the found user. Requires the admin-role.

Example:
/ontime/common/admin/wim/searchuser/email/Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!

/ontime/common/admin/wim/searchuser/uid/<uid>
Searches for the supplied uid in WebSphere Identity Manager and shows the name, uid and e-mail address of the found user. Requires the admin-role.

Example:
/ontime/common/admin/wim/searchuser/uid/ch

/ontime/common/admin/wim/resolvegroup/<DN of group>
Searches for the supplied group in WebSphere Identity Manager and shows the name, uid and e-mail address of the members. Requires the admin-role.

Examples:
/ontime/common/admin/wim/resolvegroup/CN=All+Users,CN=Groups,dc=ontimesuite,dc=com
/ontime/common/admin/wim/resolvegroup/CN=All+Users

/ontime/common/admin/debug/config
Shows the configuration for the modules. Requires the admin-role.

/ontime/common/admin/debug/ontimeinfo
Shows the OnTime Group Calendar specific configuration. Requires the admin-role.

/ontime/common/admin/debug/url/<target>/<auth>/<url>
Attempts to load the specified URL using the specified authentication mechanism. Requires the admin-role.

Does OnTime Group Calendar - Social work with IBM Connections v. 5.5?

The short answer is "Yes!". The longer answer is that starting with IBM Connections v. 5.5 there is a new attribute which is required when configuring custom widgets such as OnTime Group Calendar - Social. The attribute needs to be added to the widgets-config.xml file and the declarations for the OnTime Group Calendar - Social widgets listed there. The attribute is called "themes" and describes the various locations that are valid for the widget meaning left column, middle column, right column and banner (new with v. 5.5). 

This is mainly an issue when upgrading a previous installation as the OnTime documentation has been updated to address this.

To fix an existing installation do as follows:

  1. Using wsadmin checkout the widget-config.xml file
  2. Locate each of the OnTime Group Calendar - Social widget declarations and add the "themes" attribute as applicable for each widget:
    1. Profiles: themes="wpthemeThin wpthemeNarrow wpthemeBanner wpthemeWide"
    2. Who Is Available: themes="wpthemeThin wpthemeNarrow wpthemeBanner wpThemeWide"
    3. Group Calendar: themes="wpthemeBanner wpthemeWide"
  3. Save and close the file and check the configuration back in
  4. Restart your WebSphere Application Server(s)

The various "themes" actually map to locations the widget may be dropped by the user as shown below (click the image for a large version):

ontime45_connections55_themes_small Häufig gestellte Fragen

 

For more information about the "themes" attribute see the IBM technote at http://www-01.ibm.com/support/docview.wss?uid=swg21974593

How do I see the version of the OnTime Group Calendar Social components I've installed?

There are two ways to locate the build / version number. The build version can be seen in the WebSphere ISC as follows:

  1. Open WebSphere Application Server Integrated Solutions Console (ISC)
  2. From the lefthand menu expand "Applications/Application Types" and select ”WebSphere Enterprise Applications"
  3. In the list click on the OnTime Group Calendar application to look into (e.g. "OnTime Group Calendar - Social - Profiles")
  4. Click "Display module build Ids" in the uppe right corner on the available options and note the "Build id" in the right hand column

Another way - which some find easier - is using a browser to inspect the version.json in each application e.g. <hostname>/ontime/<application>/version.json. E.g. the following links show the application versions deployed to our demo environment:

The above links shows the version output in JSON format.

IBM Connections Cloud (IBM Smartcloud)

OnTime® Group Calendar for IBM Connections Cloud (formerly IBM SmartCloud)

As described in the IBM Redbook titled "Preparing your enterprise for IBM Connections Cloud" OnTime Group Calendar works with IBM Connections Cloud meaning that it is able to synchronize mail databases located in IBM Connections Cloud. Although you can use the normal OnTime Group Calendar distribution there are a number of differences in the setup to deal with the IBM Connections Cloud mail setup.

IBM Notes Hybrid

Since you cannot run applications in IBM Connections Cloud you must have an IBM Domino Server running as part of your environment. This is called IBM SmartCloud Notes Hybrid and means that you have an on-premises IBM Domino installation sharing Domino Directory with the IBM Connections Cloud mail servers. Since this is also required for Rooms and Resources (RnR) most customers will deploy IBM Connections Cloud this way.

Mail template

To optimize the synchronization process the OnTime Group Calendar server task creates a specialized view in the mail databases it synchronizes. Since no user or server may have Designer level access to a mail database in IBM Connections Cloud the server task cannot create and maintain this view. To work around this you have two options:

  1. Deploy a custom mail template to IBM Connections Cloud. This is described in the IBM documentation.
  2. Switch OnTime Group Calendar to work based on a search rather than the view. This option, although slightly slower, will work out of the box against IBM Connections Cloud.

Database signing

The OnTime Group Calendar databases must be signed by the server hosting the databases. Only servers may access mail databases in IBM Connections Cloud. Additionally the server(s) must be part of the same organization as the certifier uploaded to IBM Connections Cloud i.e. if the certifier uploaded to IBM Connections Cloud is called /SCN/Acme the server running OnTime Group Calendar must be certified by /Acme or a descendent certifier (i.e. /Servers/Acme or similar).

ACL

Please note: As of 17 August 2015 it is now possible for customers to control and maintain the access control lists (ACL's) for mail files IBM SmartCloud Notes them selves using the administration panel. Please refer to IBM's InfoCenter for more information (http://www.ibm.com/support/knowledgecenter/SSPS94/service/topics/adm_acl_change.dita)

The IBM Domino Server running the OnTime Group Calendar synchronization must have access to the mail databases in IBM Connections Cloud. By default this access isn’t granted. This access may be granted as follows:

  1. Using a custom mail template as mentioned above.
  2. Opening a PMR with IBM asking them to add a group with the OnTime Group Calendar server(s) in it.

Manually adding the server to the mail database ACL's using the Calendar Delegation Profile as you would any other user. This is a suitable solution for test purposed but isn’t recommended for production use.

OnTime Group Calendar server cannot access mail databases in the cloud

When the OnTime Group Calendar server(s) cannot access the IBM Domino servers in the IBM Connections Cloud (IBM SmartCloud) and hence users cannot be synchronized it is usually due to one of the following:

  1. The ACL of the mail databases in IBM Connections Cloud is not configured correctly ie. the on-premises IBM Domino server may not open the mail databases in the cloud. 
  2. The access to IBM SmartCloud is attempted from a server which is not the designated passthru-server. When running IBM SmartCloud Notes Hybrid you designate a single IBM Domino server on-premises to be the passthru server to IBM Connections Cloud and all traffic has to flow through this server. If the server running OnTime Group Calendar is not the passthru-server or if you have multiple OnTime Group Calendar servers you need to make sure that traffic still flow through the passthru-server. This is configured using Passthru Connection Documents in your on-premises Domino Directory.

Sicherheit

How do I revoke an OnTime Access Token?

At some point you may need to revoke an OnTime Access Token ("token") if a mobile device has been stolen or you fear that a token which is still valid has been compromised. Revoking the token takes effect immediately and renders the token unusable. To obtain a new token the user will need to reauthenticate to OnTime Group Calendar.

To revoke a token follow the below steps:

  1. Open the OnTime Group Calendar Configuration database
  2. Open the Users view and locate the user for whom you need to revoke the token
  3. From the toolbar select "Selected/Force new Web Logon"
How security works in OnTime Group Calendar

Please note: The below information pertains to HTTP based access to the OnTime Group Calendar API that is for OnTime Group Calendar Web, Mobile and Social. It also pertains to Notes and Team-At-A-Glance if these are configured for HTTP access. If native IBM Notes API (NRPC) access is used for the latter two clients an OnTime Access Token is not used.

Users are solely authenticated to the OnTime Group Calendar API (the "service" that provides the data for the OnTime Group Calendar user interfaces such as Web, Mobile, Notes etc.) using an OnTime Access Token. An OnTime Access Token is an encrypted text token that identifies the user and has a point in time it expires encoded in it (among other things). In order to obtain an OnTime Access Token the user must be authenticated to IBM Domino in whatever way the organisation requires such as basic authentication, form based authentication (using LtpaToken), certificates based authentication etc. Once an OnTime Access Token has been obtained it is used on subsequent requests to the OnTime Group Calendar API and identifies the user to the OnTime Group Calendar API. Once an OnTime Access Token is issued it is valid until it expires. The expiration duration can be controlled in the OnTime Group Calendar server document(s) and may be set to a duration in hours. The OnTime Group Calendar API issues a new OnTime Access Token on each request so the expiration time set in the OnTime Group Calendar server document(s) should be considered an "Idle time between requests".

Please note: In the OnTime Group Calendar Configuration database the OnTime Access Token idle timeout is referred to as the "HTTP Token Timeout".

Once an OnTime Group Calendar client obtains an OnTime Access Token it is cached by the client (for Mobile and Web it is cached in a browser cookie) and attempted used on subsequent requests to the API. This means that a user may access OnTime Group Calendar Web or OnTime Group Calendar Mobile without reauthenticating to IBM Domino if a valid OnTime Access Token is available. It also means that a suitable idle time should be set that suits the organisations security policy. For example if permitted by the security policy an idle time of 24 hours allows a user to use OnTime Group Calendar Mobile or Web during the day and reopen the client next day without reauthentication to IBM Domino as the OnTime Access Token is still valid.

It follows from the above that all API requests following obtaining an OnTime Access Token may be unauthenticated ("anonymous") from an IBM Domino perspective. This is not a security hole but is simply because non-token requests are solely authenticated from the OnTime Access Token. It also means that the IBM Domino HTTP server must allow anonymous requests whether that be over HTTP or HTTPs.

Please note that an OnTime Access Token may be revoked from the OnTime Group Calendar Configuration database. This means that even though a user have obtained an OnTime Access Token valid a year into the future the administrator may revoke it requiring the user to reauthenticate to use OnTime Group Calendar. This is a security measure.

HOW LOGIN TO ONTIME GROUP CALENDAR WEB WORKS

Below we assume that your OnTime Group Calendar Client database (”Client database”) is called ”ontimegcclient.nsf” and is in the ”ontime” directory. To open OnTime Group Calendar Web you would redirect users to ”/ontime/ontimegcclient.nsf/web”.

The login process is as follows:

  1. User navigate to ”/ontime/ontimegcclient.nsf/web”.
  2. The code checks whether an OnTime Access Token is present as a browser cookie or in the URL if launched from the Notes workspace icon. If it is, access is attempted using it.
  3. If that OnTime Access Token doesn’t work (i.e. is expired) any browser cookie is cleared and the login process restarts.
    1. If no OnTime Access Token is found an API call is performed to obtain an OnTime Access Token. If the user is not authenticated to IBM Domino the API tells the client that and the user is redirected to the IBM Domino login page (hard coded which is why we only support form based authentication for this process).
    2. If an OnTime Access Token is obtained is it stored in a browser cookie and the login process restarts.

HOW LOGIN TO ONTIME GROUP CALENDAR MOBILE WORKS

Below we assume that your OnTime Group Calendar Client database (”Client database”) is called ”ontimegcclient.nsf” and is in the ”ontime” directory. To open OnTime Group Calendar Mobile you would redirect users to ”/ontime/ontimegcclient.nsf/mobile”.

Besides the URL required the login process is the same as for OnTime Group Calendar Web.

HOW LOGIN TO ONTIME GROUP CALENDAR NOTES AND TEAM-AT-A-GLANCE WORKS

When the OnTime Group Calendar Notes and/or Team-At-A-Glance clients are launched they need information about how to access the OnTime Group Calendar API. This information is stored in the users mail file in a profile document maintained by the OnTime Group Calendar synchronisation process. This profile document is updated every time OnTime Group  Calendar reads in (”synchronises”) appointment data from the mail file.

Please note: It follows from the above that while having multiple OnTime Group Calendar environments read appointment data from the same mail file it is important that only one environment is configured to write this profile document.

The launch process is as follows:

  1. User clicks the icon to launch the client.
  2. If access information is cached this information is attempted used to access the OnTime Group Calendar API. If this does not work (or any cached token has been explicitly revoked) this cached information is cleared the the launch process is restarted.
  3. The users mail file is located using the information specified in the users location document. If the user cannot press Ctrl-M (Cmd-M on Mac) to compose a new email this process will fail.
  4. The profile document is retrieved and access information is read.
    1. If OnTime Group Calendar is configured for HTTP access an OnTime Access Token is obtained using native IBM Notes API access using digital signatures to verify and identify the user. Once an OnTime Access Token has been obtained the API is accessed over HTTP identifying the user by the OnTime Access Token.
    2. If OnTime Group Calendar is configured for native Notes API access information is tranferred using the native IBM Notes API using digital signatures to verify and identify the user.

When using the native IBM Notes API and digital signatures to verify and identify the user both the OnTime Group Calendar client and the OnTime Group Calendar API participate in the cryptographic process.

SINGLE SIGN ON (SSO)

Often customers are looking to provide a Single Sign On solution to OnTime Group Calendar and its user interfaces. Choosing the correct solution depends on the security infrastructure in place but most times the user is authenticated by some other system and/or the user identity may not map to IBM Domino. It may also be the case that the user is authenticated to some other system but the credentials cannot be reused for IBM Domino. There are various ways to solve this as described below.

THE SIMPLE APPROACH

Use the OnTime Group Calendar security as-is but set a long idle time for the OnTime Access Token. While this strictly speaking does not provide Single Sign On it will only require the user to authenticate once as long as the idle time for the OnTime Access Token is long enough and the user access OnTime Group Calendar within the idle time period set. This option is available out-of-the-box.

THE API APPROACH

If you have purchased the OnTime Group Calendar Open API option (sold separately) you may also use the OnTime Group Calendar API to issue tokens to users. Using the OnTime Group Calendar API a system user may obtain an OnTime Access Token on behalf of other users and thus provide access to OnTime Group Calendar using an identity verified by some other system such as Microsoft Sharepoint, a CRM system or an MDM provider. We have previously created Single Sign On (SSO) solutions for customers wanting to provide SSO from non-IBM Domino platforms to OnTime Group Calendar running on IBM Domino.

For example we have a customer with an intranet based on Microsoft technologies where the user is automatically authenticated to the intranet using Windows Integrated Authentication (IWA). The customer wanted users to be able to open OnTime Group Calendar Web without having to re-authenticate which was tricky as the user was only authenticated to the Microsoft intranet and not IBM Domino. To solve this we employed the OnTime Group Calendar API.

We solved it by having the intranet, once the user had logged in to it, use the verified username to obtain an OnTime Access Token on behalf of the user (using the OnTime Group Calendar API). Once the intranet server obtained an OnTime Access Token for the user it set the correct browser cookie to complete the puzzle. Now when the user tries to access OnTime Group Calendar the browser automatically provides the obtained OnTime Access Token and the user may access OnTime Group Calendar without reauthentication thus achiving Single Sign On.

SPNEGO / KERBEROS (OR IF FORM BASED AUTHENTICATION CANNOT BE USED)

For customers using SPNEGO with IBM Domino the default access control list (ACL) setup of the OnTime Group Calendar Client database can cause problems. This is due to the fact that the Client database allows Anonymous access by default and hence the required HTTP 401 response code that cause the operating system to initialiate the authorization handshake is never sent. To solve this the Client database has a special page that does require the user to be authenticated. Instead of using the page called ”Web” you simply use the page called ”WebSSO”.

For example if your Client database is called ”ontimegcclient.nsf” and is in the ”ontime” directory you would normally redirect users to ”/ontime/ontimegcclient.nsf/web” to open the OnTime Group Calendar Web user interface. If using SPNEGO simply replace ”/web” with ”/websso” and redirect users to /ontime/ontimegcclient.nsf/websso”. Nothing more is required.

Please note: It’s very important that the ACL is configured correctly as described in the documentation for this to work.

Entwicklung

API - Is there an API Explorer to help me learn the API?

Yes.

The API Explorer is probably the easiest way to work with and learn the API. The API Explorer can be found online at http://demo.ontimesuite.com/apiexplorer (username: demo, password: demo) but this of course works on a set of demo data. To use the API Explorer in your own environment open the API Explorer from your web database by opening the following URL http://<hostname>/ontime/ontimegcweb.nsf/APIExplorer (given that the OnTime Group Calendar client database can be found in /ontime/ontimegcweb.nsf. Also please substitute <hostname> with the actual hostname of the server hosting your OnTime Group Calendar client database.

Please note: In versions prior to version 3.1.3 contains a slightly outdated API Explorer. If you running version 3.1.2 or newer please contact Support to obtain the latest version. The API Explorer will be current from version 3.1.3 and onwards.

Using the OnTime Group Calendar API using Notes native APIs (over NRPC)

Using the OnTime Group Calendar API (here after API) using Notes native API's is done using the following 5 basic steps:

  1. Create an API document in the OnTime Group Calendar API database (or reuse an existing document for the user if possible) and set the required back-end fields (see below for more info).
  2. Add the request JSON message to the API document.
  3. Digitally sign and then save the document.
  4. Run the ApiNotes agent in the API database supplying the note ID of the API document.
  5. Look up the API document you wrote the request to in step 1 and read the response.

The document you create should have the following backend items.

Item name Type Value
_Author Authors, Readers [ReadAll ]
[Developer]
<Distinguished name of effective user>
<Distinguished name of API server>
$Request_X Text The JSON request split into 32kb items named $Request_0, $Request_1, $Request_2 and so on

The request and response is in the same JSON format as the HTTP based API.

In the two questions below ("Using native Notes API's - LotusScript example" & "Using native Notes API's - Java example") are examples in Java and LotusScript.

 

Using native Notes API's - Java example

Please refer to the document describing using the OnTime Group Calendar API (here after API) using Notes native API's before reading this document (see the questions above "Using the OnTime Group Calendar API using Notes native API's (over NRPC).

import lotus.domino.Agent;
import lotus.domino.AgentBase;
import lotus.domino.Database;
import lotus.domino.Document;
import lotus.domino.Item;
import lotus.domino.Session;
import java.util.Vector;

public class JavaAgent extends AgentBase {

   public void NotesMain() {
      try {
         // get agent session
         Session session = getSession();

         // compose request
         String request = "{\"Main\": {\"ApplVer\": \"0.0.1\", \"ApplID\": \"Web2011\", \"APIVer\": 2}}";

         // get api database, agent and document
         final Database dbApi = session.getDatabase("Solace/Krynn", "ontime/ontimegcapi.nsf");
         final Agent agentApi = dbApi.getAgent("ApiNotes");
         Document docApi = dbApi.createDocument();

         final Vector v = new Vector();
         v.add("[ReadAll]");
         v.add("[Developer]");
         v.add(dbApi.getServer());
         v.add(session.getEffectiveUserName());
         Item item = docApi.replaceItemValue("_Authors", v);
         item.setReaders(true);
         item.setAuthors(true);
         docApi.replaceItemValue("$Request_0", request);
         docApi.sign();
         docApi.save();

         // get note id 
         final String noteid = docApi.getNoteID();
         docApi.recycle();
         docApi = null;

         // execute agent
         agentApi.runOnServer(noteid);

         // fetch api document
         docApi = dbApi.getDocumentByID(noteid);

         // get response
         StringBuilder b = new StringBuilder();
         for (int i=0; docApi.hasItem("$Response_" + i); i++) {
            b.append(docApi.getItemValueString("$Response_" + i));
         }

         // write response
         System.out.println(b.toString());
      } catch (Exception e) {
         e.printStackTrace();
      }
   }
}

Using native Notes API's - LotusScript example

Please refer to the document describing using the OnTime Group Calendar API (here after API) using Notes native API's before reading this document (see the questions above "Using the OnTime Group Calendar API using Notes native API's (over NRPC).

Option Public
Option Declare


Sub Initialize
   'declarations
   Dim session As New NotesSession
   Dim noteid As String
   Dim request As String
   Dim response As String
   Dim dbApi As NotesDatabase
   Dim agentApi As NotesAgent
   Dim docApi As NotesDocument
   Dim item As NotesItem
   
   'create request
   request = |{"Main": {"ApplVer": "0.0.1", "ApplID": "Web2011", "APIVer": 2}}|
   
   'get API database, agent and document
   Set dbApi = New NotesDatabase("Solace/Krynn", "ontime/ontimegcapi.nsf")
   Set docApi = New NotesDocument(dbApi)
   Set agentApi = dbApi.GetAgent("ApiNotes")
   
   'set items
   Dim v(4) As String
   v(0) = "[ReadAll]"
   v(1) = "[Developer]"
   v(2) = dbApi.Server
   v(3) = session.Effectiveusername
   Set item = docApi.Replaceitemvalue("_Authors", v)
   item.Isauthors = True
   item.Isreaders = True
   Call docApi.ReplaceItemValue("$Request_0", request)
   Call docApi.Sign()
   Call docApi.Save(True, false)
   
   'get note id
   noteid = docApi.Noteid
   Delete docApi
   
   'call agent
   Call agentApi.Runonserver(noteid)
   
   'fetch API document
   Set docApi = dbApi.Getdocumentbyid(noteid)
   
   'get response
   Dim i As Integer
   While docApi.Hasitem("$Response_" & i)
      'append
      response = response & docApi.GetItemValue("$Response_" & i)(0)
      
      'increment
      i = i + 1
   Wend
   
   'show (JSON) response
   Print response
End Sub

What are the limitations in the API Explorer?

The OnTime Group Calendar API is a separate offering and is purchased separately so the API Explorer is deliberately limited in what it can return. By default the API Explorer uses the ApiExplorer Application ID which is limited in the following way:

  • A Disclaimer is shown on all calls to the API
  • Will only return the first 5 calendar entries per user
  • Will only return 10 users at a time (UsersAll, UsersInfo, UserSearch)
  • Will only return 10 results in a freetime search for a maximum of 3 users
  • Suffix subject with a string indicating that the calendar entry was created with the ApiExplorer Application ID when creating calendar entries
  • Suffic subject with a string indicating that out-of-office was enabled using the ApiExplorer Application ID when saving out-of-office

Please note that none or these limitations are present when the Open API option has been purchased and using a custom Application ID issued by OnTime support.

OnBehalfOf - How do I enable it (allowing applications to run on behalf on someone else)?

OnBehalfOf is a way to allow certain users to impersonate other users in the API. Impersonation is required for most server application as they need to work on behalf of a user even though the code is signed by another user. For example OnBeHalfOf allows application XYZ to work on behalf the user name supplied to it.

Please note that OnBehalfOf is required to use the OnTime Group Calendar API Java wrapper from XPages.

To configure OnBehalfOf perform the steps below:

  1. Locate the OnTime Group Calendar Configuration database on your workspace and make sure you have the [Developer] role assigned to you in the ACL of the database. Please note that you may have to create the role if it hasn't yet been created.
  2. Open the OnTime Group Calendar Configuration database.
  3. Go to the "Server Settings" by clicking "Server Settings" at the top of the left hand navigator.
  4. Open the server settings document for the server you will be accessing to reproduce the issue (or just open the one server settings document if you only have one OnTime Group Calendar server).
  5. Bring the document into edit mode and locate the "Users allowed to run 'OnBehalfOf'" field left side of the form and specify the names of the users allowed to impersonate other users.
  6. Save and close the document.

See the question below "OnBehalfOf - How does it work? Do you have an example?" for documentation on how to use it in the API.

OnBehalfOf - How does it work? Do you have an example?

Developers new to using the OnBehalfOf functionality of the OnTime Group Calendar API (hereafter “API”) sometimes finds it awkward to understand when first introduced to it. This post aims to solve that by explaining exactly how it works.

All requests made to the API needs to run in the context of a user in OnTime Group Calendar as it needs to figure out the access to calendar data. This is why only users in OnTime Group Calendar can make requests against the API. By default when a request is made to the API the request run as the owner of the OnTime Group Calendar access token if using HTTP or the signer of the request if using NRPC. This is what you want when you write a client application where requests should be done as the logged in user. When for some reason you want to perform API operations using the access context of someone else than the OnTime Group Calendar access token (if using HTTP) or the signer of the request (if using NRPC) you use OnBehalfOf.

Examples could be a Domino agent running as under a server identity, applications on a Java Enterprise Edition server such as WebSphere Application Server or simply if a user needs to make requests for other users.

Example

Below is an example of using the OnBehalfOf functionality over HTTP where the Chris Holmes (Chris Holmes/OnTime, chris.holmes[at]ontimesuite.com) user makes requests for Linda Rohdes (linda.rohdes[at]ontimesuite.com) and Jane Fonda (Jane Fonda/OnTime).

Start by registering the caller identity (e.g. “Chris Holmes/OnTime”) in the “Users allowed to run OnBehalfOf” field on Server Settings in the OnTime Group Calendar Configuration database.

With Chris Holmes logged into IBM Domino a request to the apihttptoken endpoint is performed to obtain a HTTP access token.

Request

POST /ontime/ontimegcweb.nsf/apihttptoken HTTP/1.0
Host: ontime.example.com
Cookie: LtpaToken2=abc123
Content-Length: xyz
Connection: Close

{"Main": {"APIVer": 5, "ApplVer": 1, "ApplID": "MyCustomApp"}}

Response

{APIVersion: "3.10.0",
APIBuild: 567,
Status: "OK",
Token: "chris.holmes.token123"
}

Now using the access token (for Chris Holmes) I can perform a Login call as though I’m either Linda Rohdes.

Request

POST /ontime/ontimegcweb.nsf/apihttp HTTP/1.0
Host: ontime.example.com
Content-Length: xyz
Connection: Close

{"Main": {"APIVer": 5, "ApplVer": 1, "ApplID": "MyCustomApp", "Token": "chris.holmes.token123", "OnBehalfOf": "linda.rohdes[at]ontimesuite.com"}, "Login": {}}

Response

{APIVersion: "3.10.0",
APIBuild: 567,
Login: {
Global: {...},
User: {
ID: "5",
Name: "Linda Rohdes/OnTime",
Email: "linda.rohdes[at]ontimesuite.com",
MailSource: "Domino"
}},
Token: "chris.holmes.token234",
Status: "OK"
}

...or Jane Fonda (here using her DN).

Request

POST /ontime/ontimegcweb.nsf/apihttp HTTP/1.0
Host: ontime.example.com
Content-Length: xyz
Connection: Close

{"Main": {"APIVer": 5, "ApplVer": 1, "ApplID": "MyCustomApp", "Token": "chris.holmes.token234", "OnBehalfOf": "Jane Fonda/OnTime"}, "Login": {}}

Response

{APIVersion: "3.10.0",
APIBuild: 567,
Login: {
Global: {...},
User: {
ID: "23",
Name: "Jane Fonda/OnTime ",
Email: "jane.fonda[at]ontimesuite.com",
MailSource: "Domino"
}},
Token: "chris.holmes.token345",
Status: "OK"
}

If I do not add the OnBehalfOf information the request will be processed for Chris Holmes himself as show below:

Request

POST /ontime/ontimegcweb.nsf/apihttp HTTP/1.0
Host: ontime.example.com
Content-Length: xyz
Connection: Close

{"Main": {"APIVer": 5, "ApplVer": 1, "ApplID": "MyCustomApp", "Token": "chris.holmes.token345"}, "Login": {}}

Response

{APIVersion: "3.10.0",
APIBuild: 567,
Login: {
Global: {...},
User: {
ID: "1",
Name: "Chris Holmes/OnTime ",
Email: "chris.holmes[at]ontimesuite.com",
MailSource: "Domino"
}},
Token: "chris.holmes.token456",
Status: "OK"
}

 

 

 

Weitere Hilfen

Anwendertutorials

Erfahren Sie mehr über die Interfaces und ihre Funktionen in unseren Handbüchern.

Handbücher

Schauen Sie unter den FAQ, um Antworten auf Ihre Fragen zu finden

Supportanfrage

Immer noch Fragen offen? Wenden Sie sich an unsere Experten.

Copyright © 2018 OnTime.
All rights reserved.

Company

Contact Us

Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!

 

Subscribe to our mailing list

* indicates required