16 Replies Latest reply on Apr 1, 2014 6:13 AM by Ryan Rutan

    Is there a story based Developer Guide?

    scoffey

      Ryan Rutan

      Mark Weitzel

       

      I am completely new to Jive. I have used Spring, Struts, FreeMarker, etc., but this is my first go around with Jive.

      What I am looking for is a developer guide that will explain the terminology in use, and the means by which one can integrate with Jive.

       

      So, you might ask, what is it you want to do?

       

      Very soon I will need to modify the behavior when a user logs in. I need to have access to their screen name. Both acquiring what Jive thinks the screen name should be, and changing that screen name. I need to know when they change the screen name or set the screen name for the first time so that it can be manipulated by another service. I need to get other user information and send it to other systems so that if the user changes information in Jive, the other system knows about it. And I want to do this without modifying the login or account data behavior in other ways.


      How do I do this?



      There is a lot of documentation and user contribution all over the Jive Developer Community.

      But I can't find a high level explanation for what is available, or what integration is intended.

       

      I might expect the following possible types of integration:

       

      1) Integration for events in Jive: When jive does this (like logging on), you provide a class with interface X and Jive calls it before or after it does it's own thing.

      2) Integration for components in Jive: When jive does this, instead of calling it's own component it calls the one you write instead.

      3) Integration for new UI elements in Jive: Jive lets you create UI elements, instead of one of the UI elements provided you can write your own and they show up in "create" then on the page or list where you created them.

      4) Integration for modifications to UI elements in Jive: You can use the @ Mention link to call out a particular user, here is how you add features to the text editor to do some new cool thing.

      5) Use of the data in Jive: Jive has a set of users, possible UI elements, groups, etc. Here is the API to get this information, modify it, or use it in a new way.


      Actions and Plug-ins seem to cover (3) right? But I haven't found a strait forward user manual, I've just spent hours exploring.


      Thanks for your help,


      Sean


        • Re: Is there a story based Developer Guide?
          scoffey

          (5) I believe that this type of integration is covered by the REST API [ Jive REST Rest API v3.6 ].

          Right?

          • Re: Is there a story based Developer Guide?
            scoffey

            (1) I believe that this type of integration is covered by Webhooks [ Jive REST Rest API v3.6 → Webhooks service ].

            Right?

            • Re: Is there a story based Developer Guide?
              Ryan Rutan

              Sean Coffey,

               

              Welcome to the Developer Community.  A few things to help get you oriented:

              Jive Platform - Developer Resources

              is definitely going to be your friend.  When it comes to extending Jive, this is going to be the master page for all Learn More (Stories), Tutorials, Examples, etc... and we are actively working to improve this experience and visibility as we speak (note the date of the document).

               

              Now, per your questions, one thing to note is that from the technology set you outlined (Struts, Freemarker, Spring), it sounds like you are asking for information about developing legacy plugins (that run in the Jive container), which are limited to on-premise/hosted versions of Jive.

              The recommended universal means of integrating with Jive (7+ and Cloud) is via the Add-On Framework, which I linked to the core documentation page above.

              1) Integration for events in Jive: When jive does this (like logging on), you provide a class with interface X and Jive calls it before or after it does it's own thing.

              • When it comes to Events, the WebHook resources in REST & Webhooks - Developer Resources are the way to go.  In most events though, these are asynchronous after the fact notifications, so more after than before ..per your words.
                • Note: In the legacy plugin architecture there is a concept of EventListening that has (in some cases) a synchronous concept; however, again this limits the environment options for Jive should you choose to go down this path.

              2) Integration for components in Jive: When jive does this, instead of calling it's own component it calls the one you write instead.

              • Jive Add-Ons support a concept for "Embedding Experiences", that you can check out here:  Jive Apps (OpenSocial) - Developer Resources.  While not a "show this instead of this" logic", Jive Apps integration points are strategically placed into the product allowing people to integrate with Jive in relevant and actionable locations.
                • Note: In the legacy plugin architecture, you have more power to change things like UI implementations ... but in most cases, this will create overhead to upgrading your Jive instance to the latest version.

              3) Integration for new UI elements in Jive: Jive lets you create UI elements, instead of one of the UI elements provided you can write your own and they show up in "create" then on the page or list where you created them.

              4) Integration for modifications to UI elements in Jive: You can use the @ Mention link to call out a particular user, here is how you add features to the text editor to do some new cool thing.

              5) Use of the data in Jive: Jive has a set of users, possible UI elements, groups, etc. Here is the API to get this information, modify it, or use it in a new way.

              As I said before, we are actively working on the landing experience (in fact some small changes are moving out today/Monday) until we can overhaul more of the experience.  Greatly appreciate any feedback you might have, and let me know how I can help get you started in the right direction.

               

              Hope this helps,

              RR

              1 person found this helpful
                • Re: Is there a story based Developer Guide?
                  scoffey

                  Thanks Ryan for the timely response, and all the good links and advice!

                   

                  I guess my immediate concern has to do with synchronous behavior integration. If I need to do some extra checks or data modification prior to actually giving the user access to the Jive forum how would I do it? I can't user webhooks because it is asynchronous. I can't place a service in front of Jive which does the needful and then redirects to Jive because the user would end up going through a secondary login procedure.

                   

                  What I really need is to be be able to insert a synchronous task after the user enters their information (at login or register), but before they actually get access, and have that access dependent on the same synchronous task.

                   

                  I don't see a login or registrar service that would allow a facade to log in on behalf of the user. I guess that would also solve the problem, but at the cost of a lot of reworking if the API should change in the future. It would also require a separate interface outside of the Jive environment and that UI would have to be skinned separately.

                   

                  We could also roll our own by modifying the Jive code directly but that seems like a maintenance issue.

                   

                  The best solution would be a synchronous interlude as discussed.

                   

                  Any ideas?

                   

                  Thanks again,

                   

                  Sean

                    • Re: Is there a story based Developer Guide?
                      whoiskevin

                      Sean,

                       

                      I think you have stumbled on what I struggle with constantly.  The Jive API and integrations are still what I would call immature.  Before a big thread of discussion starts I do not mean that as an insult simply an observation given the things I need to accomplish.  Your example is as example of one of those things that I seem to need to accomplish in every project. Every time the registration process simply has additional steps that companies insist on having.  Probably a result of too many lawyers and HR involved ;-)   So from my view of Jive the current Javascript focused integration points are only useful for minor integrations, often with external systems and more UI oriented than what I call "backend data" oriented.

                      Again this is not meant to be negative just based on use cases that I have there has not been a case where the current suggested integrations (apps, add-ons, tiles, extensions) serve the needs.  I think that is a sticky point for work that has to be done now (6 months or less) and concern for upgrades should only be a small part of that decision.

                      My point to all of this is that I still feel in the current environment that the fastest modification path is though plugins modifying the code via Spring and when required the core war file as well.  Are these to be avoided?  Sure if the current API layer can quickly serve your purpose but I've found pretty much all my use cases lead me to the same conclusion.

                      I think the API will improve and as more people use it there will be improvement.  But user registration is a prime example of something that based on my experience will still require a more "hands on the code" approach.

                       

                      I wouldn't fear the maintenance issue.  A nice plugin can do what you are looking to accomplish and the modifications to the code would be only in that plugin.  Upgrading such a plugin in my experience has only been a day or two of work and a few days of testing and I have upgraded similar plugins all the way through versions since 3.x.

                       

                      Just "my two cents" as the saying goes.

                      • Re: Is there a story based Developer Guide?
                        Ryan Rutan

                        Kevin Brown - I dont think your opinion is going to cause a major debate, because as you said, it's just your opinion.

                         

                        Me personally, I am a strong advocate for managing your technology portfolio to the skills at your / (your team's) disposal.  For me, plugin technologies and power is very attractive, but I choose to steer away from them if it means that it takes pathways to Cloud off the table.  The value of the speed of innovation in Cloud is better, IMO, than any customization I can write.  That being said, if Cloud is off the table for other reasons ... then using plugins should be (as Kevin's stated), when the API cannot meet the functional requirements, and should stay within your comfort zone in terms of total cost of ownership.

                         

                        Depending on what you are trying to do, you can use the Core V3 API - Run-As Feature & Signed Add-Ons with an Add-On to execute service calls on behalf of people. Not sure what functions you are trying to do, but perhaps this will help.

                         

                        Again, you need to do what you need to do, but as long as you approach your solutions in an Add-On 1st mentality and be open with your obstacles, we can work together to try and find ways to promote feature requests to engineering and see what falls into alignment.

                         

                        As always, appreciate the questions ... and Kevin, appreciate you sharing your opinion =)

                          • Re: Is there a story based Developer Guide?
                            scoffey

                            Ryan Rutan,

                             

                            Thanks again for your assistance.

                             

                            I know we are moving from our own servers to Jive Hosted (Not cloud). I do not know what the future plans are, but the integration Use Cases around Login and Registration appear to be of the utmost importance at this time.

                             

                            I am not sure what solution you are suggesting with the Core V3 Run-As feature. Could you elaborate on what that solution might look like. It would seem that if it is login or registration that we want to facade, that Run-As would not yet come into play at that time.

                             

                            Kevin Brown 's suggestion of replacing the endpoint for login and registration seems to make the most sense. Basically create the obvious missing integration point by placing a facade in front of those two requests, then use this integration point. This might require augmentation to the Jive code directly, but might be possible without changing the built-in code if I knew how those particular calls were configured.

                             

                            The issues I foresee include:

                            The body of those two requests, or the query parameters might change.

                            Encryption of the data might not allow for use of that data by the code I wish to write.

                            Discrepancies in the Headers, Cookies, or other such security might prevent me from calling the built-in Login and Registration requests properly.

                             

                            Ryan, do you see any other way around this conundrum, other than Kevin's suggestion?

                             

                            Kevin, it sounds like you have done this, could you perhaps point me in the right place, and provide some insight into the issues I might encounter?

                             

                            Thanks again,

                             

                            Sean

                              • Re: Is there a story based Developer Guide?
                                whoiskevin

                                The devil is in the details.  But generally you can track down the actions (either struts or API calls) and extend the existing classes.  If you do that then your code simply runs in front of the existing call allowing you to make adjustments and send notices to your external system.  This should only be needed if you are truly modifying the data.  If you are only sending notices to the external system then you should be able to register an event handler (async) and send notice.  But just overriding the action for something like registration and user creation might be the easiest path for you.  That is very light since you are just looking at the data prior (or after) a call to the parent class.

                                 

                                Start with looking through the struts-community.xml file and using your debugger to find the calls you are interested in. 

                                Some examples from the community:  Override struts login action in Jive 6

                                Developer doc section: Jive 7.0 Community Admin Documentation

                                And I like this old but good explanation of authentication filters: Jive Documentation

                                 

                                Ultimately more details about exactly what you are doing will involve a lot of decisions and while this use case may fit with a customization like this I would make sure you cannot avoid the "change" requirement.  Because it sounds like that change requirement is what is really making it difficult for you to just have a very light notification using a simple event or if the webhooks would tell you about user registrations then you could use those.

                                1 person found this helpful
                                • Re: Is there a story based Developer Guide?
                                  Ryan Rutan

                                  Sean,

                                   

                                  Not trying to steer you off course regarding the Run-As feature, you had mentioned,

                                  I don't see a login or registrar service that would allow a facade to log in on behalf of the user

                                  and hence the reason I shared it.  Based on the following description of the problem/use-case:

                                  Very soon I will need to modify the behavior when a user logs in. I need to have access to their screen name. Both acquiring what Jive thinks the screen name should be, and changing that screen name. I need to know when they change the screen name or set the screen name for the first time so that it can be manipulated by another service. I need to get other user information and send it to other systems so that if the user changes information in Jive, the other system knows about it. And I want to do this without modifying the login or account data behavior in other ways.

                                  This is how I would design this as an Add-On, if it meets your extended requirements or not, that is up to you. =)

                                  • Create an Add-On, that is signed (similar to the steps in Core V3 API - Run-As Feature & Signed Add-Ons), such that you can listen for System Webhooks
                                    • Jive REST Rest API v3.6 → Webhooks service => Specifically, jive:user_account_created and jive:user_session_login and possibly, jive:user_profile_modified
                                    • Key field for users should be their ID (never changes) rather than their username, but if you want to use username, then you will need to persist some historical tracking of this field as it changes on your own.
                                  • On user_account_created
                                    • Run your business logic to register with other services/systems
                                      • Not sure about the concept "what the username should be", Jive doesn't (to my knowledge) seed usernames with default values (unless this is a customization on your end).
                                  • On user_profile_modified
                                    • Run your business to update other services/systems
                                  • On user_session_login
                                    • Run your business to update other services/systems

                                   

                                  My questions to you would be:

                                  • What are the concerns if a person for a period of <5 minutes is able to log in to the community without business processes doing their job?  What behavior are you controlling/enabling with these processes?  I agree with you that processing synchronously is appealing in some cases, but I dont recall seeing in this thread what those use-cases are that warrant that behavior.
                                  • Admittedly, the above solution is quite simplistic and based on the snippet, I can see it working quite well, but I'm guessing there are other requirement lurking in the background which poke holes. 

                                   

                                  All that being said, if you are going down the plugin route and avoid customizing the UI in any form, then you are insulated from most of the volatile changes between versions.  Hope this conversation has helped.   =)

                                    • Re: Is there a story based Developer Guide?
                                      scoffey

                                      Thanks again Ryan Rutan & Kevin Brown .

                                       

                                      I am sorry I wasn't clear about the use cases driving the question.

                                       

                                      The Use Cases are:

                                      Synchronize username (screen name) between all systems accessed by the SSO.

                                      Synchronize email between all systems accessed by the SSO.

                                      Always provide a _Jive_specific_ End User License Agreement (EULA) when accessing Jive for the first time. So if they set up an account on some other system, then they would be allowed logged-in access to Jive after passing the SSO, but would be required to accept the EULA on Jive before proceeding.

                                       

                                      I was trying to avoid the solution Kevin suggested to allow for a cloud configuration. I am not even sure if this solution is possible give that it will be Jive Hosted. However, it does appear that to meet the requirements something like Kevin's suggestion is warranted.

                                       

                                      This link was very helpful. Example: Authentication and Authorization

                                       

                                      Looks like I have some archaeology to do. I hope this works in the Hosted environment.

                                       

                                      Ryan, is there any reason it might not?

                                       

                                      Thanks.

                                        • Re: Is there a story based Developer Guide?
                                          whoiskevin

                                          I think there has been some confusion this doesn't sound like you need a customization at all.

                                           

                                          If your SSO solution supports SAML for instance you can configure out of the box to synchronize users and they will not create their accounts.  You will assign their user id from the SSO.  The terms of use can be configured in Jive.  The Email would be one of those fields that is synchronized to those federated user accounts.

                                          1 person found this helpful
                                            • Re: Is there a story based Developer Guide?
                                              Ryan Rutan

                                              Kevin is correct.  There is a feature in the product called Terms & Conditions that you can configure that do just this.  You can embed them with the editor and/or you can reference an external URL.

                                              Screen Shot 2014-03-31 at 3.44.55 PM.png

                                              Using the WebHooks plus this feature should get you almost all the way there, if not 100%.  Glad to hear some more of the detail. =)

                                               

                                              Update, see these pieces of content in the documentation:

                                              Configuring User Registration

                                              Configuring Terms and Conditions

                                                • Re: Is there a story based Developer Guide?
                                                  scoffey

                                                  Thanks,

                                                   

                                                  It is very nice that there is a Terms and Conditions feature. However, we have our own EULA service which keeps track of which users have accepted which EULAs and when. For legal reasons we need to be able to have strong provable guarantees that the EULA has been accepted before allowing access. We also need to have control of the EULA text from this separate system. It's a bit more complex.

                                                    • Re: Is there a story based Developer Guide?
                                                      whoiskevin

                                                      I knew there would be too many lawyers and HR people involved!  :-p

                                                       

                                                      Seriously the Terms of Use in Jive works well and they will have to accept it to continue and since it can come from an external URL it can be controlled outside the system.  I think with some well structured conversations you can just use the out of the box feature to supply those guarantees.

                                                      • Re: Is there a story based Developer Guide?
                                                        Ryan Rutan

                                                        Sean,

                                                         

                                                        Question. Jive's T&C feature records when a person accepts the event ... I would need to look it up where it stores it, but it has a mechanism in place for updated T&C's which timestamps are compared to determine if someone needs to re-accept the terms.  Assuming this information is persisted appropriately and accessible via the API, I would imagine you could poll this on the WebHook login feature and trust Jive to gate access to those who haven't accepted.

                                                         

                                                        The item I do not have an answer for are the remotely managed T&C text.  You can see the option for a remote T&C location, but not sure about how this is managed and "acceptance" is measured.

                                                         

                                                        Just thought I'd throw that into the hat, as this T&C feature has been around and evolved for sometime, so the feature is pretty battle tested when it comes to stringent environments IMO.

                                                         

                                                        Perhaps its worth a try?

                                                         

                                                        RR

                                          • Re: Is there a story based Developer Guide?
                                            it2000

                                            Re: login process

                                            With a load balancer or maybe also with Apache you could redirect the auth POST to a custom backend server. This server may use the rest v2 api (x-jcapi-token) to validate the credentials and then forward the post to Jive to get the browser cookie.

                                            So there would be at least no theming issues.

                                            No idea whether this is also possible in the cloud.