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.
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”
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:
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
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.
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:
message : ‘test’
projectId : ‘projectId’
Once you save this webhook, there will be a webhook URL that is generated along with the token.
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
Replace the osn with osn-public, this becomes your webhook base URL.
So in this example, the webhook URL will be
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.
Select New Webhook, which will take you to the ‘Create Webhook’ form
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.
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.
This should show up in our “Webhooks 2016” conversation in Documents Cloud Service.
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.