Oracle Documents Cloud Service  provides “Conversations” – which is a great way for to share information with each other in an enterprise.  This can reap great benefits by extending to the developer teams in your enterprise by integrating with the Developer Cloud Service to automatically provide updates about the latest status of a project.  Furthermore, conversations can be accessed by any user on the go, using the Android/iPhone mobile app for Documents Cloud Service (for downloads refer to this page) and ensure that everybody is on the same page always with regards to what is happening in the project.

 

Do note that conversations are actually a feature of Oracle Social Network Cloud (OSN) which is bundled along with a Documents Cloud Service instance and I will be using these interchangeably in this blog.

 

This blog post will demonstrate how to achieve this via Webhooks provided by the Developer Cloud Service (version 16.3.5) and the Documents Cloud Service (version 16.3.5). Webhooks are a callback mechanism for a producer application to provide updates about itself to other consumer applications in real time.  This eliminates the need for polling for the destination applications and improves efficiency for both.

 

So any activities in the project, like issue updates, commits, branch creation etc, will be automatically published into Documents Cloud Service (or Oracle Social Network Cloud) as posts to a conversation.  This way the entire team (which has access to the conversation) can be aware about the latest updates to the project, and can collaborate with each other to clear impediments during development like failed builds, merge conflicts etc.

 

In the case of Documents Cloud Service and Developer Cloud Service, this can be accomplished without any code using an incoming webhook at the Documents Cloud Service side and an outgoing webhook at the Developer Cloud Service as illustrated in the below figure.

 

Webhooks system.png

An outgoing webhook is used to push data out of the system, i.e. convert the event data into the required payload and post the same to the target URL, in this case the URL for the DOCS/OSN incoming webhook.  An incoming webhook is used at the destination system as a service listening for these post events and converts the payload into the meaningful destination data – in this case, conversations.

 

Below are the steps for achieving this setup:

 

Step 1 – Create a conversation in Documents Cloud Service

First, we need to create the conversation to which all the Developer Cloud Service updates would be automatically posted.  Go to the Documents Cloud Service console, click on “Conversations” on the left-hand menu and create a conversation.  I am going to name this conversation – “Webhooks 2016”

 

incoming webhook - 1.png

incoming webhook - 2.png

 

Step 2 – create a DCS (Developer Cloud Service) incoming hook in Documents Cloud Service

In the Documents Cloud Service, click on your user name on the top right hand corner, and select “Administration” from the menu.  This will take you to the Documents Cloud Service Administration console.  Select “Webhooks” from the administration menu as shown:

 

incoming webhook - 3.png

 

You would see 3 options –

  • DCS Incoming Webhook – handles incoming updates from a Developer Cloud Service Instance
  • Generic Incoming Webhook – handles incoming updates from any application
  • JIRA Incoming Webhook – handles incoming updates from a JIRA application

 

 

incoming webhook - 4.png

 

We will create a DCS Incoming Webhook as our source is a Developer Cloud Service project.  Click on New Instance and provide the various parameters to create the webhook.

 

incoming webhook - 5.png

 

For the fields:

Webhook Name – a relevant name to identify the webhook

Webhook enabled – tick this to enable the webhook

Target conversation – select the conversation created in Step 1

Message template - would be populated by default and contain two variables data.projectId and data.message.  The structure of the data object is as follows:

data {

message : ‘test’

projectId : ‘projectId’

}

 

Once you save this webhook, there will be a webhook URL that is generated along with the token.

 

incoming webhook - 6.png

 

Here the webhook URL is a relative URL.  The full webhook URL would be the following:

https://<OSN instance URL>/osn-public/hooks/webhooks

 

And the token here would be ‘6361690deedf10aad6147533636dfd49’

 

To find out the OSN (Oracle Social Network) instance URL attached to the Documents Cloud Service, open the following endpoint in your browser (note that you have to be logged in to the documents cloud service to access this)

https://<documents instance URL>/documents/web?IdcService=GET_SERVER_INFO

This will return a JSON payload containing a lot of server side information.  Look for an attribute called OSNServiceURL

[

"OSNServiceURL",

"https://instancexyz-test.socialnetwork.us.oraclecloud.com:443/osn"

],

 

Replace the osn with osn-public, this becomes your webhook base URL.

So in this example, the webhook URL will be

https://instancexyz-test.socialnetwork.us.oraclecloud.com:443/osn-public/hooks/webhooks

 

And the token will be 6361690deedf10aad6147533636dfd49

 

Step 3 – create an Outgoing webhook in Developer Cloud Service

The next step is to create an outgoing webhook in Developer cloud service to post updates to the Documents Cloud Service incoming webhook.  Note that you have to be the administrator for the project for which you want to configure the webhook to achieve this.

 

Here for demonstration purposes, I have created an empty GIT project called “test” for which I am the administrator.  Select the project and go to the administration tab, and click on Webhooks.

 

outgoing webhook - 1.png

 

Select New Webhook, which will take you to the ‘Create Webhook’ form

 

outgoing webhook - 2.png

 

In the “Create Webhook” form, use the following

Type = Oracle Social Network

Name = any description, I am using “test webhook” in this example

Active = Yes

URL = give the OSN webhook URL i.e. https://instancexyz-test.socialnetwork.us.oraclecloud.com:443/osn-public/hooks/webhooks

Authentication token – give the token value - 6361690deedf10aad6147533636dfd49

Event groups – You can select specific events, or Failed Builds.  For the purpose of this example, I am going to select “All events”

Click on Done when all the details are complete.  This will create a new Webhook ready to be used.

 

outgoing webhook - 3.png

 

Step 4 – Test the outgoing webhook


Developer Cloud Service provides a way to test the webhook by simply clicking on the “Test” button.  You can also go to Logs and see the full details of the webhook interactions including the message payload.  If the test is successful, it will show up in green as below.

 

outgoing webhook - 4.png

 

This should show up in our “Webhooks 2016” conversation in Documents Cloud Service.

 

conversation.png

 

If the test is successful, try performing some activity in the Developer Cloud Service project, like commit or create a wiki, and check whether the same is being populated in the conversation.

 

You can track this conversation from the mobile client for Documents Cloud Service as well (available for iPhone and Android).  An effortless way of increasing developer collaboration and keeping track of project activities!  Consult the official documentation of Developer Cloud Service and Documents Cloud Service for more on Webhooks.

 

**The views expressed in this post are my own and do not necessarily reflect the views of Oracle.