C&S APIs in IBM Notes and Domino
-
Upload
dave-delay -
Category
Software
-
view
512 -
download
10
description
Transcript of C&S APIs in IBM Notes and Domino
![Page 1: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/1.jpg)
© 2013 Wellesley Information Services. All rights reserved.
C&S APIs in IBM Notes and Domino
Dave DelayIBM
![Page 2: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/2.jpg)
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.
![Page 3: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/3.jpg)
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
![Page 4: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/4.jpg)
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
![Page 5: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/5.jpg)
5
C&S APIs Available in 9.0 Social Edition
C API Toolkit (calapi.h)
Java WrappersLotusScript 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
![Page 6: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/6.jpg)
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:VCALENDARPRODID:-//Renovations Inc//MyApp 1.0//ENBEGIN:VEVENTDTSTART:20130204T140000ZDTEND:20130204T143000ZSUMMARY:Team meetingORGANIZER;CN="Samantha Daryn":mailto:[email protected];CN="Ted Amado":mailto:[email protected]:Discuss statusLOCATION:My officeEND:VEVENTEND:VCALENDAR
![Page 7: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/7.jpg)
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.)
![Page 8: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/8.jpg)
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
![Page 9: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/9.jpg)
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++
![Page 10: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/10.jpg)
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, ...);
![Page 11: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/11.jpg)
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, ...);
![Page 12: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/12.jpg)
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 tooSample 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)
![Page 13: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/13.jpg)
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: ... */
![Page 14: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/14.jpg)
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
![Page 15: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/15.jpg)
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 WrappersLotusScript 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
![Page 16: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/16.jpg)
16
C&S Backend Classes
SessiongetCalendar(Database db) NotesCalendar
readRange(...)
getEntry(String uid)
createEntry(String ical)
getNewInvitations()
NotesCalendarEntryread()
update(String ical)
remove()
delegate(...)
...
getNotices()
NotesCalendarNoticeread()
accept()
decline()
delegate(...)
...
![Page 17: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/17.jpg)
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.
![Page 18: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/18.jpg)
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);
![Page 19: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/19.jpg)
19
C&S Java API Demo
![Page 20: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/20.jpg)
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.
![Page 21: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/21.jpg)
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)
![Page 22: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/22.jpg)
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
![Page 23: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/23.jpg)
23
Review of C&S APIs Available in 9.0 Social Edition
C API Toolkit (calapi.h)
Java WrappersLotusScript 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
![Page 24: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/24.jpg)
24
C&S APIs Planned for 9.x
C API Toolkit (calapi.h)
Java WrappersLotusScript Wrappers
Core C&S Logic
NotesCalendar Back-end Classes
Customer solutions
using LotusScript
Customer solutions
usingNotes Java
APICustomer 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
![Page 25: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/25.jpg)
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
![Page 26: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/26.jpg)
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
![Page 27: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/27.jpg)
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:VCALENDARVERSION:2.0PRODID:-//Lotus ... //NONSGML ...BEGIN:VEVENTDTSTART:20130203T233000ZDTEND:20130204T030000ZLAST-MODIFIED:20121217T183957ZDTSTAMP:20121217T184244ZSUMMARY:Super Bowl XLVIILOCATION:New OrleansUID:8A3941390301436885257AD700661DAEEND:VEVENTEND:VCALENDAR
![Page 28: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/28.jpg)
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.
![Page 29: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/29.jpg)
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}
![Page 30: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/30.jpg)
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": {...} }, ... ]}
![Page 31: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/31.jpg)
31
Sample iCalendar Response
• Read a range of events GET /{database}/api/calendar/events?format=icalendar
iCalendar response:
BEGIN:VCALENDARX-LOTUS-CHARSET:UTF-8VERSION:2.0BEGIN:VEVENTDTSTART:20130203T233000ZDTEND:20130204T030000ZSUMMARY:Super Bowl XLVIILOCATION:New OrleansUID:8A3941390301436885257AD700661DAEX-LOTUS-SUMMARYDATAONLY:TRUEEND:VEVENTBEGIN:VEVENTDTSTART:20130205T140000ZDTEND:20130205T150000ZSUMMARY:Repeating AppointmentLOCATION:testUID:09C4206D7BD743D685257AB0007BA513X-LOTUS-SUMMARYDATAONLY:TRUEEND:VEVENT...END:VCALENDAR
![Page 32: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/32.jpg)
32
Calendar Service Demo
![Page 33: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/33.jpg)
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)
![Page 34: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/34.jpg)
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
![Page 35: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/35.jpg)
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
![Page 36: C&S APIs in IBM Notes and Domino](https://reader030.fdocuments.in/reader030/viewer/2022012315/5564229ed8b42a69298b4e53/html5/thumbnails/36.jpg)
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