Slides presented at the Developer 2013 conference in April 2013. Although this deck is one year old, it is still a good primer for C&S APIs in Notes and Domino. The most notable change is the REST calendar service is now part of Domino 9.0.1.
2. 2
Please Note ...
IBM’s statements regarding its plans, directions, and intent are subject to change or
withdrawal without notice at IBM’s sole discretion.
Information regarding potential future products is intended to outline our general product
direction and it should not be relied on in making a purchasing decision.
The information mentioned regarding potential future products is not a commitment,
promise, or legal obligation to deliver any material, code or functionality. Information
about potential future products may not be incorporated into any contract. The
development, release, and timing of any future features or functionality described for our
products remains at our sole discretion.
3. 3
What We’ll Cover …
• Overview of C&S APIs
• C&S in the C API toolkit
• C&S in LotusScript, Java and SSJS
• REST calendar service
• Wrap-up
4. 4
9.0 Social Edition C&S API Design Goals
• Allow an application to manage data on a user's calendar
Includes robust and reliable scheduling
Does not include ToDos, busy-time, and rooms & resources
• Keep it simple
Encapsulate the Notes/Domino data and recurrence model
Leverage the iCalendar standard
• Available to developers working in C/C++, LotusScript, Java and
server-side JavaScript
• Easily expandable in future releases
5. 5
C&S APIs Available in 9.0 Social Edition
C API Toolkit (calapi.h)
Java Wrappers
LotusScript
Wrappers
Core C&S Logic
NotesCalendar Back-end Classes
Customer
solutions
using
LotusScript
Customer solutions using
Notes Java API
Customer
solutions
using C / C++
Customer
solutions
using
SSJS
JS Wrappers
• One C&S implementation; multiple interfaces
• All four interfaces are new in 9.0
6. 6
What is iCalendar?
• Text-based, standard representation of calendar data (see
RFC5545)
• Open source iCalendar libraries available (e.g. ical4j & libical)
iCalendar Example:
BEGIN:VCALENDAR
PRODID:-//Renovations Inc//MyApp 1.0//EN
BEGIN:VEVENT
DTSTART:20130204T140000Z
DTEND:20130204T143000Z
SUMMARY:Team meeting
ORGANIZER;CN="Samantha Daryn":mailto:sdaryn@renovations.com
ATTENDEE;CN="Ted Amado":mailto:tamado@renovations.com
DESCRIPTION:Discuss status
LOCATION:My office
END:VEVENT
END:VCALENDAR
7. 7
C&S API Features
• Working with calendar entries
Read a range of entries
Create, read, update or delete an individual calendar entry
Implicit scheduling for meetings
Simple actions on meetings (decline, delegate, cancel, etc.)
Complete support for repeating entries
Support for all entry types (meetings, appointments, all day
events, anniversaries, reminders)
• Working with calendar notices
Read the list of new invitations
Read a list of unapplied notices (for an entry)
Process a notice (accept, decline, delegate, counter, etc.)
8. 8
What We’ll Cover …
• Overview of C&S APIs
• C&S in the C API toolkit
• C&S in LotusScript, Java and SSJS
• REST calendar service
• Wrap-up
9. 9
C&S in the C API Toolkit
• All functions defined in calapi.h
• The C API is the foundation for all other
language bindings
• Implemented using core C&S and iCalendar logic
• Can be used with open source libical
C API Toolkit (calapi.h)
Core C&S Logic
Customer
solutions
using C / C++
10. 10
A Few Calendar Entry Functions (C API)
• Read the iCalendar representation for a range of events
STATUS CalReadRange(DBHANDLE hDB, TIMEDATE tdStart,
TIMEDATE tdEnd, ...);
• Read the iCalendar for a single event
STATUS CalReadEntry(DBHANDLE hDB, const char* pszUID,
const char* pszRecurID, ...);
• Create a new event from iCalendar
STATUS CalCreateEntry(DBHANDLE hDB, const char*
pszCalEntry, DWORD dwFlags, ...);
11. 11
A Few Calendar Notice Functions (C API)
• Get a list of new invitations
STATUS CalGetNewInvitations(DBHANDLE hDB, TIMEDATE*
ptdStart, ...);
• Get a list of notices for a single event
STATUS CalGetUnappliedNotices(DBHANDLE hDB, const char*
pszUID, ...);
• Process a single notice (accept, decline, etc.)
STATUS CalNoticeAction(DBHANDLE hDB, NOTEID noteID,
DWORD dwAction, ...);
12. 12
Debugging the C API functions
• Notes.ini setting for tracing the C&S API
CSDebugAPI=1
• This works for the LotusScript, Java and SSJS classes too
Sample console log:
[268C:000A-188C] 04/05/2013 09:03:30.65 AM [CS API]> Enter CalReadEntry,
UID:A6F3B8508B90461A85257B4100601786-Lotus_Notes_Generated, RID:NULL, Flags:0x0.
[268C:000A-188C] 04/05/2013 09:03:30.69 AM [CS API]> Exit CalReadEntry,
return:0x0000, No error.
[268C:000A-188C] 04/05/2013 09:07:49.97 AM [CS API]> Enter CalCreateEntry,
Flags:0x0.
[268C:000A-188C] 04/05/2013 09:07:50.45 AM [CS API]> PRODID required in C&S API
input but was not found
[268C:000A-188C] 04/05/2013 09:07:50.45 AM [CS API]> Error |
ConvertIcal2NoteRequest.cpp(189) : Missing VEvent components (0x892)
[268C:000A-188C] 04/05/2013 09:07:50.49 AM [CS API]> Error |
VersitInterface.cpp(1769) : Missing VEvent components (0x892)
[268C:000A-188C] 04/05/2013 09:07:50.49 AM [CS API]> Error |
VersitInterface.cpp(1966) : Missing VEvent components (0x892)
[268C:000A-188C] 04/05/2013 09:07:50.49 AM [CS API]> Error |
calendarapiworker.cpp(405) : Missing VEvent components (0x892)
[268C:000A-188C] 04/05/2013 09:07:50.49 AM [CS API]> Exit CalCreateEntry,
return:0x0892, Missing VEvent components.
[268C:000A-188C] 04/05/2013 09:07:50.49 AM [CS API]> Error | calendarapi.c(370) :
Missing VEvent components (0x892)
13. 13
C API Documentation
• A complete function reference is included in the C API toolkit
• The calapi.h file also has lots of useful comments
Sample comment:
/*********************************************************************************
* CalReadRange
* This will return data for all entries that begin within a specified date range,
* with paging capabilities (similar to NIFReadEntries) in cases where there is
* more data than can be returned in a single call.
* Specifically, this can return one or both of:
* 1) iCalendar generated from view level data about the calendar entries in the
* date range
* 2) A list of UIDs for each calendar entry in the date range
*
* ...
*
* Inputs: ...
*
* Outputs: ...
*
* Returns: ...
*/
14. 14
What We’ll Cover …
• Overview of C&S APIs
• C&S in the C API toolkit
• C&S in LotusScript, Java and SSJS
• REST calendar service
• Wrap-up
15. 15
C&S in LotusScript, Java & SSJS
• One object model
NotesCalendar
NotesCalendarEntry
NotesCalendarNotice
• Three language bindings
• Java developers can use
open source ical4j
C API Toolkit (calapi.h)
Java Wrappers
LotusScript
Wrappers
Core C&S Logic
NotesCalendar Back-end Classes
Customer
solutions
using
LotusScript
Customer
solutions
using
Notes Java
API
Customer
solutions
using
SSJS
JS Wrappers
17. 17
A Few Calendar Entry Methods (Java)
• Read the iCalendar representation for a range of events
(NotesCalendar class) String readRange(DateTime start,
DateTime end);
• Read the iCalendar for a single event
(NotesEntryCalendar class) String read();
• Create a new event from iCalendar
(NotesCalendar class) NotesCalendarEntry createEntry(String
icalentry);
Compare
these
methods
with the
equivalent C
functions.
18. 18
A Few Calendar Notice Methods (Java)
• Get a list of new invitations
(NotesCalendar class) Vector getNewInvitations(DateTime start,
DateTime since);
• Get a list of notices for a single event
(NotesCalendarEntry class) Vector getNotices();
• Process a single notice (accept, decline, etc.)
(NotesCalendarNotice class) void accept(String comments);
(NotesCalendarNotice class) void decline(String comments);
20. 20
Tips for Using the C&S Backend Classes
• Remember the Notes.ini setting
CSDebugAPI=1
• Don't forget to recycle (Java and SSJS)
For example NotesCalendarEntry.recycle() frees any native
memory associated with the entry
Particularly important when the parent database and session
remain open
• See the NotesError class for useful error codes (Java and SSJS)
NOTES_ERR_ERRSENDINGNOTICES
NOTES_ERR_NOTACCEPTED
NOTES_ERR_NEWERVERSIONEXISTS, etc.
21. 21
C&S Backend Classes Documentation
• See Domino Designer for help on each language binding
• LotusScript help
IBM Domino Designer Basic User Guide and Reference >
LotusScript/COM/OLE Classes > LotusScript Classes A-Z > NotesCalendar
(LotusScript)
• Java help
IBM Domino Designer Basic User Guide and Reference > Java/CORBA
Classes > Java Classes A-Z > NotesCalendar (Java)
• Server-side JavaScript help
IBM Domino Designer XPages Reference > Domino > NotesCalendar
(JavaScript)
22. 22
What We’ll Cover …
• Overview of C&S APIs
• C&S in the C API toolkit
• C&S in LotusScript, Java and SSJS
• REST calendar service
• Wrap-up
23. 23
Review of C&S APIs Available in 9.0 Social Edition
C API Toolkit (calapi.h)
Java Wrappers
LotusScript
Wrappers
Core C&S Logic
NotesCalendar Back-end Classes
Customer
solutions
using
LotusScript
Customer solutions using
Notes Java API
Customer
solutions
using C / C++
Customer
solutions
using
SSJS
JS Wrappers
• Each interface works on either Notes or Domino
• But your application must be co-located with Notes or Domino
24. 24
C&S APIs Planned for 9.x
C API Toolkit (calapi.h)
Java Wrappers
LotusScript
Wrappers
Core C&S Logic
NotesCalendar Back-end Classes
Customer
solutions
using
LotusScript
Customer
solutions
using
Notes Java
API
Customer
solutions
using C / C++
Customer
solutions
using
SSJS
JS Wrappers
Customer
solutions
using
REST
REST Service
HTTP
• Calendar service will provide remote access to the
same C&S implementation
25. 25
Calendar Service Design
• Accessible from any HTTP client
Web applications (Dojo, jQuery, etc.)
Native mobile applications
Open Social gadgets
Server-to-server applications
• Keep it simple
Uses the C&S back-end classes
Uses any authentication scheme supported by Domino (basic,
session, SAML, etc.)
Same syntax as other IBM services
26. 26
Calendar Service Design (continued)
• Functional design
Create, read, update and delete calendar entries
Get a list of new invitations or unapplied notices
Simple actions to process entries and notices
Control implicit scheduling
• Resource-oriented
Calendars, events and notices are resources – each with a
unique URL
Use simple verbs to act on resources (GET, PUT, POST &
DELETE)
Navigate between resources
27. 27
iCalendar vs. JSON
• Most calendar service requests support either iCalendar or JSON
• JSON may be easier to use with JavaScript
• iCalendar may be easier to use with an open source parser / generator (ical4j,
libical, etc.)
JSON event:
{
"events": [
{
"id": "8A3941390301436885257AD700661DAE",
"summary": "Super Bowl XLVII",
"location": "New Orleans",
"start": {
"date": "2013-02-03",
"time": "23:30:00",
"utc": true
},
"end": {
"date": "2013-02-04",
"time": "03:00:00",
"utc": true
}
}
]
}
iCalendar event:
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Lotus ... //NONSGML ...
BEGIN:VEVENT
DTSTART:20130203T233000Z
DTEND:20130204T030000Z
LAST-MODIFIED:20121217T183957Z
DTSTAMP:20121217T184244Z
SUMMARY:Super Bowl XLVII
LOCATION:New Orleans
UID:8A3941390301436885257AD700661DAE
END:VEVENT
END:VCALENDAR
28. 28
A Few Calendar Entry Requests (REST)
• Read a range of events (JSON or iCalendar)
GET /{database}/api/calendar/events
GET /{database}/api/calendar/events?format=icalendar
• Read a single event (JSON or iCalendar)
GET /{database}/api/calendar/events/{uid}
GET /{database}/api/calendar/events/{uid}?format=icalendar
• Create a new event
POST /{database}/api/calendar/events
Compare
these REST
requests
with the
other C&S
APIs.
29. 29
A Few Calendar Notice Requests (REST)
• Get a list of new invitations
GET /{database}/api/calendar/invitations
• Get a list of notices for a single event
GET /{database}/api/calendar/events/{uid}/notices
• Process a single notice (accept, decline, etc.)
PUT /{database}/api/calendar/events/{uid}/action?type={action}
33. 33
Calendar Service Release Plan
• Like other REST services, it will be released on OpenNTF first
Part of the XPages Extension Library
Available to early adopters, source included
Limited support by the OpenNTF community
• Product release vehicle is TBD
• More on the extension library development model:
Continuous development released as open source
8.5.3 UP1
N/D 8.5.3 N/D 9.0 Social Edition
9.0 UP1 (not in plan)
34. 34
What We’ll Cover …
• Overview of C&S APIs
• C&S in the C API toolkit
• C&S in LotusScript, Java and SSJS
• REST calendar service
• Wrap-up
35. 35
Additional Resources
• www-01.ibm.com/software/lotus/category/messaging
IBM Notes and Domino 9.0 Social Edition
• www-10.lotus.com/ldd/ddwiki.nsf
IBM Notes and Domino Application Development Wiki
• extlib.openntf.org
Extension library on OpenNTF
• tools.ietf.org/pdf/rfc5545.pdf
iCalendar standard specification
• ical4j.sourceforge.net/index.html
Java library for parsing and generating iCalendar
36. 36
7 Key Points to Take Home
• One C&S implementation; multiple interfaces
• iCalendar model encapsulates internal complexity
• Take advantage of implicit scheduling
• Choose an open source iCalendar library
• Use CSDebugAPI=1 for development
• Watch OpenNTF for the REST calendar service
• REST services are strategically important for remote access to
Domino