Using a App Tab in a Purposeful Place to view GitHub issues in Jive
- (0,1) App contributes a place config modal view
- (1) The modal HTML references JS, which launches 3-legged OAuth with Jive & GitHub
- (1) At the conclusion of OAuth dancing, the browser invokes service endpoints for storing the access tokens
- GitHub endpoint and controller for storing the access token @ /github/oauth/callback
- Jive endpoint and controller for storing Jive access token @ /jive/oauth/callback
- (2) Fetch a list of GitHub repos to choose from, using access token @ /github/user/repos
- (3) On config save, modal calls Jive to save ext place properties identifying selected repo @ /api/core/v3/places/[placeID]/extprops
- (5) App contributes a place tab view
- (6) The tab view HTML references JS, calls service to proxy fetch of GitHub issues
- Service endpoint for fetching GitHub issues @ /github/place/issues
- (9,10) Places tab JS recieves list of issues and updates the tab DOM
Using Tiles in a Purposeful Place to track GitHub issues
- Tiles contribute a place config modal
- Recent issues and project info tile definitions declare a source for config modal
- Endpoint and controller serves up the modal HTML and its JS @ /github4jive/basicTileConfig
- (12) Service tile registration handler responds to tile registrations
- Tile webhooks setup logic establishes a (13)(14) GitHub issue state change handler
- Handler injects its callback function into gitHubFacade for the purpose of subscribing to issue events
- (15) Fetches recent issues and pushes an update to the tile
- (Sequence 16) GitHub calls service endpoint in response to GitHub issue creation @ /github/WebHookPortal
- (16) Service controller forwards event from request to gitHubFacade to trigger event handlers
- (16,17) gitHubFacade locates registered event handlers
- (18) Endpoint URL specified in tile definition creates clickable tile entries
- The tile push logic defines issue metadata as part of tile JSON push which is provided to the modal
- The tile action endpoint serves the modal HTML and the JS for closing an issue
- JS calls the endpoint for proxying close issue calls to GitHub @ /github/place/changeIssueState
- GitHub calls service endpoint in response to GitHub issue update @ /github/WebHookPortal
- Registered webhook handler is invoked to update the recent issues tile
Using a Jive discussion to comment on a GitHub issue
- During place config, webhooks are established to model GitHub issues as Jive discussions
- The [config modal JS calls place setup endpoint] (https://github.com/jivesoftware/GitHub4Jive/blob/master/GitHub4Jive-Addon/public/javascripts/configurePlace.js#L291) to trigger webhooks setup @ /github4jive/place/setupDiscussionWebhooks
- The endpoint and its (*) controller kicks off GitHub and Jive webhooks setup
- The GitHub webhooks setup code defines an issue handler
- (20) Calls jive to create discussion when triggered by an incoming GitHub event @ /api/core/v3/contents
- (21) Calls Jive to write ext props linking the discussion to a GitHub issue, using the jiveApiFacade to make the actual call @ /api/core/v3/contents/[contentID]/extProps
- GitHub calls the service webhook endpoint in response to GitHub issue comment @ /github/WebHookPortal
- Place issue comment handler is invoked
- (22) Queries Jive for related discussion via ext props @ /api/core/v3/extprops/github4jiveIssueId/[issueID]
- (23) [Creates a reply based on issue comment] (https://github.com/jivesoftware/GitHub4Jive/blob/master/GitHub4Jive-Addon/services/places/backend/webhooks/issueCommentHandler.js#L73), calls Jive to post the reply @ /api/core/v3/messages/contents/[discussionID]
- During place config, a Jive service webhook is registered
- (24) Jive invokes service webhook endpoint in response to a Jive discussion reply
- (24) The endpoint controller forwards the event to the webhook processor which determines its a discussion reply and delegates processing to its issue comment handler
- The issue comment handler resolves the related GitHub issue and posts the comment based on the reply
- (24) Handler fetches jive message based on webhook payload @ /api/core/v3/message/[messageID]
- (24) Handler fetches associated discussion's ext props to locate linked GitHub issue @ /api/core/v3/contents/[discussionID]/extProps
- (25) Handler calls GitHub facade to post a new comment on the issue
- (25) GitHub facade posts a new issue comment
Using dynamic Jive app actions to open and close GitHub issues
- (26) The app contributes close action to the discussion. For a new issue:
- The reopen action is hidden as the closed ext prop (github4jiveIssueClosed) is not set; correspondingly, the close action is visible
- See the app action contribution reference
- Clicking the close action produces an app view modal and its JS
- The JS calls the change issue service endpoint @ /github/place/changeIssueState
- The service endpoint and its controller closes the specified issue
- GitHub calls the service webhook endpoint, triggering the github place issue handler
- (27) The handler updates discussion ext properties, setting the property indicating closure
- On view, the app contributes reopen action to the discussion