© 2013 Wellesley Information Services. All rights reserved.
C&S APIs in
IBM Notes and Domino
Dave Delay
IBM
2
Please Note ...
IBM’s statements regarding its plans, directions, and intent are subject to change or
withdrawal without...
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...
4
9.0 Social Edition C&S API Design Goals
• Allow an application to manage data on a user's calendar
 Includes robust and...
5
C&S APIs Available in 9.0 Social Edition
C API Toolkit (calapi.h)
Java Wrappers
LotusScript
Wrappers
Core C&S Logic
Note...
6
What is iCalendar?
• Text-based, standard representation of calendar data (see
RFC5545)
• Open source iCalendar librarie...
7
C&S API Features
• Working with calendar entries
 Read a range of entries
 Create, read, update or delete an individua...
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...
9
C&S in the C API Toolkit
• All functions defined in calapi.h
• The C API is the foundation for all other
language bindin...
10
A Few Calendar Entry Functions (C API)
• Read the iCalendar representation for a range of events
 STATUS CalReadRange(...
11
A Few Calendar Notice Functions (C API)
• Get a list of new invitations
 STATUS CalGetNewInvitations(DBHANDLE hDB, TIM...
12
Debugging the C API functions
• Notes.ini setting for tracing the C&S API
 CSDebugAPI=1
• This works for the LotusScri...
13
C API Documentation
• A complete function reference is included in the C API toolkit
• The calapi.h file also has lots ...
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 calenda...
15
C&S in LotusScript, Java & SSJS
• One object model
 NotesCalendar
 NotesCalendarEntry
 NotesCalendarNotice
• Three l...
16
C&S Backend Classes
Session
getCalendar(Database db) NotesCalendar
readRange(...)
getEntry(String uid)
createEntry(Stri...
17
A Few Calendar Entry Methods (Java)
• Read the iCalendar representation for a range of events
 (NotesCalendar class) S...
18
A Few Calendar Notice Methods (Java)
• Get a list of new invitations
 (NotesCalendar class) Vector getNewInvitations(D...
19
C&S Java API Demo
20
Tips for Using the C&S Backend Classes
• Remember the Notes.ini setting
 CSDebugAPI=1
• Don't forget to recycle (Java ...
21
C&S Backend Classes Documentation
• See Domino Designer for help on each language binding
• LotusScript help
 IBM Domi...
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 calenda...
23
Review of C&S APIs Available in 9.0 Social Edition
C API Toolkit (calapi.h)
Java Wrappers
LotusScript
Wrappers
Core C&S...
24
C&S APIs Planned for 9.x
C API Toolkit (calapi.h)
Java Wrappers
LotusScript
Wrappers
Core C&S Logic
NotesCalendar Back-...
25
Calendar Service Design
• Accessible from any HTTP client
 Web applications (Dojo, jQuery, etc.)
 Native mobile appli...
26
Calendar Service Design (continued)
• Functional design
 Create, read, update and delete calendar entries
 Get a list...
27
iCalendar vs. JSON
• Most calendar service requests support either iCalendar or JSON
• JSON may be easier to use with J...
28
A Few Calendar Entry Requests (REST)
• Read a range of events (JSON or iCalendar)
 GET /{database}/api/calendar/events...
29
A Few Calendar Notice Requests (REST)
• Get a list of new invitations
 GET /{database}/api/calendar/invitations
• Get ...
30
Sample JSON Response
• Read a range of events
 GET /{database}/api/calendar/events
JSON response:
{
"events": [
{
"id"...
31
Sample iCalendar Response
• Read a range of events
 GET /{database}/api/calendar/events?format=icalendar
iCalendar res...
32
Calendar Service Demo
33
Calendar Service Release Plan
• Like other REST services, it will be released on OpenNTF first
 Part of the XPages Ext...
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 calenda...
35
Additional Resources
• www-01.ibm.com/software/lotus/category/messaging
 IBM Notes and Domino 9.0 Social Edition
• www...
36
7 Key Points to Take Home
• One C&S implementation; multiple interfaces
• iCalendar model encapsulates internal complex...
37
Your Turn!
How to contact me:
Dave Delay
ddelay@us.ibm.com
Upcoming SlideShare
Loading in …5
×

C&S APIs in IBM Notes and Domino

1,627 views

Published on

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.

Published in: Software, Technology, Business
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,627
On SlideShare
0
From Embeds
0
Number of Embeds
8
Actions
Shares
0
Downloads
25
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

C&S APIs in IBM Notes and Domino

  1. 1. © 2013 Wellesley Information Services. All rights reserved. C&S APIs in IBM Notes and Domino Dave Delay IBM
  2. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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
  16. 16. 16 C&S Backend Classes Session getCalendar(Database db) NotesCalendar readRange(...) getEntry(String uid) createEntry(String ical) getNewInvitations() NotesCalendarEntry read() update(String ical) remove() delegate(...) ... getNotices() NotesCalendarNotice read() accept() decline() delegate(...) ...
  17. 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. 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);
  19. 19. 19 C&S Java API Demo
  20. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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}
  30. 30. 30 Sample JSON Response • Read a range of events  GET /{database}/api/calendar/events JSON response: { "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 } }, { "id": "09C4206D7BD743D685257AB0007BA513", "summary": "Repeating Appointment", "location": "test", "start": {...}, "end": {...} }, ... ] }
  31. 31. 31 Sample iCalendar Response • Read a range of events  GET /{database}/api/calendar/events?format=icalendar iCalendar response: BEGIN:VCALENDAR X-LOTUS-CHARSET:UTF-8 VERSION:2.0 BEGIN:VEVENT DTSTART:20130203T233000Z DTEND:20130204T030000Z SUMMARY:Super Bowl XLVII LOCATION:New Orleans UID:8A3941390301436885257AD700661DAE X-LOTUS-SUMMARYDATAONLY:TRUE END:VEVENT BEGIN:VEVENT DTSTART:20130205T140000Z DTEND:20130205T150000Z SUMMARY:Repeating Appointment LOCATION:test UID:09C4206D7BD743D685257AB0007BA513 X-LOTUS-SUMMARYDATAONLY:TRUE END:VEVENT ... END:VCALENDAR
  32. 32. 32 Calendar Service Demo
  33. 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. 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. 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. 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
  37. 37. 37 Your Turn! How to contact me: Dave Delay ddelay@us.ibm.com

×