1. © 2006 Intland Software1 Aron Gombas Architect, Intland Software Extending & customizing CodeBeamer

2. © 2006 Intland Software2 Customize, extend and integrate: why? To adapt CB to your business! CB conceptual extension points: Remote API (also known as "web services API"): –extend remotely, by accessing CB functionality from remote clients Listeners –extend on the server side, by implementing event listeners Wiki plugins –extend the wiki syntax (the wiki markup language), visualize your custom information

3. © 2006 Intland Software3 Typical use cases: when to use what? Remote API: –importers & exporters (data exchange/backup, migration from legacy systems) –integration with external systems (e.g. Lotus Notes) –IDE plugins (e.g. our Eclipse plugin) Listeners: –custom business rules: "tracker items can't be deleted unless their status is CLOSED" –integration with external systems (e.g. sending JMS messages) Wiki plugins: –integrate with external info providers (e.g. reports from an external system) –aggregate info from multiple sources to a single (portal-like) wiki page

4. © 2006 Intland Software4 Remote API: basics High-performance –based on the binary protocol: Hessian Language independent –clients in other languages than Java (C#, PHP, etc.) Secure –fine-grained security model (like at the web front-end) authentication: remote user must authenticate (with username + password) authorization: access rights control Extremely easy to use (see sample code later) –remote method calls look like local method calls

5. © 2006 Intland Software5 Remote API: supported ops What can you do remotely? –authentication: login, logout, getServerInfo –users: create, update, delete ("CRUD"), findByName, findByProject ("finders") –projects: CRUD, finders + createFromTemplate –artifacts ("documents"): CRUD, finders + lock, unlock, upload, download –artifact comments: CRUD, finders –trackers: CRUD, finders + layout, options –tracker items: CRUD, finders + history, statistics –tracker items comments/attachments: CRUD, finders –associations: CRUD, finders –source code files: finders + commit history –forums: CRUD, finders –forum posts: CRUD, finders –reports: finders + execute –wiki pages: CRUD, finders + lock, unlock, upload, download, history –wiki page comments: CRUD, finders

6. © 2006 Intland Software6 Remote API: sample sequence

7. © 2006 Intland Software7 Remote API: sample code // get all projects from the remote server RemoteApi api = RemotingUtils.connect("https://localhost:8080/cb/remote- api"); String token = api.login("bond", "007"); ProjectDto projects[] = api.findAllProjects(token); for(int i = 0; i < projects.length; i++) { ProjectDto project = projects[i]; System.out.println(project.getName()); } api.logout(token); See more sample code in "cb-remote-api-4.1.1.zip"

8. © 2006 Intland Software8 Listeners CB listener architecture: listeners can receive notifications from events inside the CB server clear interface between the CB core and your custom code –portability for future versions of CB follows the "Observer" design pattern conventions –similar to AWT, SAX parsers, event driven system easy to use (see sample code later)

9. © 2006 Intland Software9 Listeners: supported events Types –Created-updated-deleted event for any entity type: "projectCreated", "trackerUpdated", "forumDeleted", etc. –A couple of specials events like: "documentOpened", "sourceCodeModificationCommitted“, etc. Timing –pre ("before the actual operation") events and post ("after") events Vetoable changes –any listener can cancel the operation its "pre" phase by throwing a VetoException –no vetoing in "post"

10. © 2006 Intland Software10 Listener: event sample 1.User clicks “OK” when creating a new tracker 2.All tracker listeners receive the “pre tracker created” event 3.If vetoed, the operation is rejected  end 4.The tracker gets created 5.All tracker listeners receive the “post tracker created” event 6.End

11. © 2006 Intland Software11 Listeners: listener types ArtifactListener AssociationListener ForumListener ForumPostListener ProjectListener SccListener TrackerListener TrackerItemListener TrackerItemAttachmentListener TrackerItemCommentListener UserListener WorkflowListener

12. © 2006 Intland Software12 Listeners: developing listeners 1.Write a concrete implementation class that implements one of the previous Java interfaces 2.Register it to CB declaratively: by configuring it in "general.xml" That's it!

13. © 2006 Intland Software13 Listeners: sample code public class LoggerListener implements ArtifactListener { final static protected Logger log = Logger.getLogger(LoggerListener.class); public void identifiableCreated(BaseEvent event) { log.debug("identifiableCreated: " + getEventDescriptor(event)); } public void identifiableUpdated(BaseEvent event) { log.debug("identifiableUpdated: " + getEventDescriptor(event)); } public void identifiableDeleted(BaseEvent event) { log.debug("identifiableDeleted: " + getEventDescriptor(event)); } //... other event handlers here protected String getEventDescriptor(BaseEvent event) { return (event.isPreEvent() ? "PRE " : "POST ") + event.getUser() + " ["+ event.getRemoteAddress() +"] on "+ event.getSource(); }

14. © 2006 Intland Software14 CodeBeamer wiki plugins What is a "wiki plugin“? –when referenced from the wiki markup, it is invoked by the wiki engine and its output inserted into the page –mechanism to extend the wiki syntax [{TableOfContents title="My favourite things"}] CB wiki is built on the top of JSPWiki, but adding: –tight integration with other CB facilities –fine grained security –many more CB is using JSPWiki as its internal wiki rendering engine: –many times: a JSPWiki plugin can be used without any modification –sometimes: little tweaking is necessary –generally: writing a CB wiki plugin is 95% identical with writing a JSPWiki plugin (a lot of sample code available!)

15. © 2006 Intland Software15 Wiki plugins: developing a Hello World sample package cv.wiki.plugins; import java.util.Map; import com.ecyrd.jspwiki.WikiContext; import com.ecyrd.jspwiki.plugin.WikiPlugin; public class HelloWorldDemoPlugin implements WikiPlugin { public String execute(WikiContext context, Map params) { String name = (String)params.get("name"); if(name == null) { name = "World"; } return "Hello " + name + "!"; } Compile, add to CLASSPATH, try: [{HelloWorldDemoPlugin}] [{HelloWorldDemoPlugin name='Joe'}] will print: Hello World! Hello Joe!

16. © 2006 Intland Software16 Wiki plugins: more complicated samples Extend AbstractCodeBeamerWikiPlugin by your wiki class –rendering with Velocity: wiki output generated from templates (separate presentation from logic, don't hardwire formatting to Java code) –accessing CB-specific info getUserFromContext() returns the currently signed in user getPageFromContext() returns the currently rendered wiki page access more info transitively: – "getPageFromContext().getProject().getName()“ Using the CB Service Layer (also known as Business Layer or Business Tier), e.g.: –“find all tracker items assigned to the currently signed in user” –“find all forum posts in the current projects posted in the last 3 days” Read our 3 part tutorial at "CB Knowledge Base"

17. © 2006 Intland Software17 13. QA