Hello Jivers,

Recently I have been using webhooks heavily for some of our integrations.

Its one awesome feature in the Jive platform which can have great use cases.

 

Basically the Jive webhook services notifies about some events happening in Jive. Simple.

It might be about a user created, group created, some action on a content, recently in 8c5, users following a content, group or user in some stream (email enabled or a simple stream).

 

I am using system webhooks to perform some actions on an external system which is integrated with Jive.

 

In our case, this external system is google group.

Let me give some context on this.

 

What we wanted to achieve?

 

  • When a new user account is created, a new email enabled stream should be auto generated for the account
  • When user creates a jive group, there should be a google group created with some configs
  • When user deletes jive group, corresponding google group should be disabled / archived.
  • When user follows a jive group in an email enabled stream, the user account should be added to corresponding google group
  • When user unfollows a jive group from an email enabled stream, the user account should be removed from corresponding google group, provided that he is not following that group in any other email enabled stream.
  • When user follows / unfollows a group in a stream with emails off, no action is taken
  • When user turns on emails for a stream from preferences, then for every jive group he is following in that stream, he should be added to corresponding google group.
  • When user turns off emails for a stream from preferences, then for every jive group he is following in that stream, he should be removed to corresponding google group, provided he is not following that group in any other email stream.


The reason we need this is our custom streamonce solution.

Default streamonce syncs content generated in google groups to jive. Beyond that comments generated on both jive and google are synced.

Our custom streamonce even handles discussions created in jive.

We have disabled default jive email notifications for discussions and instead emails are handled through google.

 

Now for above tasks, we have some rules /restrictions on how things should be setup.

  • A new google group created should have email id same as the url name of jive group. This helps streamonce service to auto map the groups and also our add-ons to detect google group name from jive group's url name.
  • Also our add-on assumes the url name and google group name are same. So its easy for us to process incoming webhook events and get google group details from jive data.
  • If a user wants to receive emails for discussions, he has to follow that group in emails enabled stream so that he is added as member to corresponding google mailing list to receive emails.
  • We even have an app to assist group admins to do this from jive.

 

Lets see how we are using webhooks to automate this.

 

The first part of creating a google group for a jive group is taken care by a new app I posted about yesterday.

Its the new flow we have for create group. Check more about that here --> Developer: Alternative to default create group ... | Jive Community

 

We use webhooks for all other tasks..

 

Event : User account created

When a new user account is created, we would like to have an email enabled stream called Email Watches ready for him so that he can use it to receive google emails.

We can even do some other setup before the user logs in.

 

In the webhook event json, jive sends the user id and also the resource url for the user so that we can directly call the api and add streams to the new user.

 

{
    "verb":"jive:user_account_created",
    "timestamp":"2014-11-17T11:07:23.983+0000",
    "jive":{
            "objectID":1000,
            "objectType":3
        },
    "object":{
            "id": "https://company.jiveon.com/api/core/v3/people/1000"
        }
    }
}































 

 

Event : Group created


We have an app to create google and jive group, ideally that same app could have handled the extra configs on these groups. But we wanted to make that app light weight, so we moved config part here.

When a new jive group is created, we configure the corresponding google group created by our app.

 

In the event below I get the api resource url for the jive group. Using this I can get the display name of the group which is also email id of the corresponding google group. Then I call google apis to configure the group.

 

{
    "verb":"jive:social_group_created",
    "timestamp":"2014-11-17T11:09:23.983+0000",
    "jive": {
        "objectID": 3727,
        "objectType" : 700
        },
        "object" : {
            "id" : "https://uat.my.company.com/api/core/v3/places/4000"
        }
    }
}































 

 

Event : Group deleted

When jive group is deleted, we disable the google group.

In this event, jive does not send a resource url as the group no more exists.

It send this internal jive id for the group.

We had an interesting solution here.

While creating google group, we add alias to it which is a unique key generated using the internal jive id.

So if my jive group displayName or google group name is jivetestgroup which has internal id as 1000, I add an alias called integration-group-1000 to the google group.

This is used only to get the google group name in the event when jive group is deleted and all i get is jive internal id.

We had an option to use jive DES as it reports the group name, but its not recommended to use for webhooks purpose.

 

{
    "timestamp":"2014-11-27T12:25:52.802+0000",
    "verb":"jive:social_group_deleted",
    "jive":{
        "objectID":3727,
        "objectType":700
        }
}
































 


Event : User starts following group in a stream

In 8c5 cloud release, Jive introduced stream event webhooks, which were of great help for us.

My next 3 examples are related to stream events.

 

Check the first example where I get a notification that user is following something.

The json sent here by jive is rich in content.

 

As seen below, here's what I get about the stream association event

  • user id of the user who triggered this event
  • objectId is the stream id of that user in which he is following something.
  • In properties
    • associatedObjectId is the id of object which the user is following in the stream. This can be place, content or person.
    • associatedObjectURI is the api resource uri of this object. This is particularly helpful in case of content or place where the object id might be different than the one used in api. There are still ways to get data from object id, but this url gives the object directly instead of using a search api on places on content.
    • receiveEmails tells if the stream in which this object was followed has emails on or off.
    • associatedObjectType is a number which tells type of object (example 700 is social group)

 

{
    verb: 'jive:stream_association_added',
    timestamp: '2015-01-14T23:15:15.312+0000',
    jive: {
            userID: 2014,
            objectID: 10,
            properties:
            {
                associatedObjectID: '1004',
                associatedObjectURI: "https://company.jiveon.com/api/core/v3/places/1529",
                receiveEmails: 'false',
                associatedObjectType: '700'
            },
        objectType: -891990144
        }
}































 

In our case when we get this event, if a user is following an object type of group in an email enabled stream, then using apis i will get the username of the user, display name of the group and then add this user to the google group (displayName@domain.com).

If user is following something in non email enabled stream, we ignore the event

 

 

Event : User stops following a group from a stream


In this case if a user stops following a group from an email enabled stream, we remove the user form corresponding google group, provided he is not following this group in any other email enabled stream.

This second part to verify if any other association is present between user and place is a simple api call.

Check the REST api documentation here --> Jive REST Rest API v3.10 → Place service

As admin I have to use run-as feature to call followingIn for the group under consideration (https://company.jiveon.com/api/core/v3/places/placeID/followingIn)

 

This will give me list of streams in which the user is following the group, with the stream email preferences too.

This helps me decide if I should be removing the user from google group or not.

 

{
    verb: 'jive:stream_association_removed',
    timestamp: '2015-01-14T23:14:56.859+0000',
    jive: {
            userID: 2014,
            objectID: 10,
            properties:
            {
                associatedObjectID: '1004',
                associatedObjectURI: "https://company.jiveon.com/api/core/v3/places/1529",
                receiveEmails: 'false',
                associatedObjectType: '700'
            },
            objectType: -891990144
        }
}































 

 

 

Event : User changes email preferences for a stream


Some day a user might decide to just turn off emails for all or one of his streams.

Even this preference change is sent by webhook stream event.

Whenever I change my email preferences for stream, Jive sends me user id who is owner of the stream and also detail about each stream with previous and current receive email status, though the change is only on one stream .


The stream which ha a change in preferences, I will pull all the group associations for that streams (as there might be people and content associations).

And then check where I need to add or remove user from a google group.

 

 

{
    verb: 'jive:stream_config_modified',
    timestamp: '2015-01-14T23:17:38.982+0000',
    jive: {
            userID:10004,
            objectID: 10,
            properties: {
                receiveEmails: 'false',
                previousReceiveEmails: 'false'
            },
            objectType: -891990144
        }
}
{
    verb: 'jive:stream_config_modified',
    timestamp: '2015-01-14T23:17:38.982+0000',
    jive: {
            userID: 1000,
            objectID: 11,
            properties: {
                receiveEmails: 'false',
                previousReceiveEmails: 'true'
            },
            objectType: -891990144
        }
}































 

 

Event : User's membership with a group removed


Our google group memberships have no connection with jive group memberships. Its more connected with email preferences and email streams.

So we never have to handle membership created event.

By default when user joins as member, he starts following that group in connection stream too, and jive does notify about it through webhooks.


Now when users group membership is revoked, all his stream associations with that group are also removed.

But in this case jive sends only one event "'jive:user_membership_removed". There is no association removed event.


But as we know all associations are removed as thats the way jive works, we simply get the group id from the event, call jive api to get the displayName and then call google group api to revoke user's membership for that group in google world.

{
    verb: 'jive:user_membership_removed',
    object : {
        id: 'https://company.jiveon.com/api/core/v3/people/2113'
    },
    timestamp: '2015-03-04T10:06:06.310+0000',
    jive : {
        containerType: 700,
        containerID: 1195,
        objectID:2113,
        objectType:3
    }
}




 

This is how we are using webhooks to improve the experience with our integrations.

Obviously there is much more you can do with this kind of data that you get from jive webhooks service.