Using sites management APIs with an application user: A quick start guide

May 14, 2021 | 12 minute read
Christopher A. DeGrace
Senior Principal Product Manager
Text Size 100%:

If you’ve ever worked with Oracle Content Management, you’re likely aware of the powerful site-building and hosting tools it provides. Many of our customers use sites to present a face to their business, while others build compelling product showcases that highlight the value they provide to their customers.

But there‘s another emerging use case we’re seeing more and more—collaboration and internal communications. In fact, it’s one of the main reasons why we invested in site governance features that allow our customers to control who can create and use sites, and when sites should be removed once they’ve served their purpose.

At Oracle, we “eat our own dog food” and use Oracle Content to power many of our internal, one-to-many, information-sharing portals. If you’re picturing an extremely large corporate intranet, you’re in the right ballpark. Not only does Oracle Content allow us to use our IT resources efficiently, but it also allows us to:

  • Confirm compliance with corporate policies.
  • Verify that information is kept up to date.
  • Avoid ending up with an unwieldy number of sites.

Perhaps someone out there enjoys hounding people with questions like, “Do you still need this site that hasn’t been updated since 2005?” or “Do you know the document on this page can’t be shared with a partner yet?” I certainly wouldn’t.     

While standard governance features go a long way in satisfying the needs of a large organization like ours, there are some situations where it doesn’t go far enough. For example, I recently spoke to a coworker who wanted to use an Oracle Content site to interact with one of his clients. He wanted a place where he could share sensitive documents and collaborate on works-in-progress, while simultaneously showcasing what Oracle Content could do. This got me thinking. If I was in IT, how would I give the ability to create such a site to my sales team without creating a logistical nightmare?

I’d create a template or two that would serve as the basis for such a site—something that could be customized for a specific client or project without having to start from square one every time. Then, I’d configure the template policies so that any sites created could only be used the way I want them to be and make them accessible only to the appropriate individuals. Last but not least, I would need to give my sales team the ability to request a site and share some pertinent information before I create the site for them—or better yet, the system creates it automatically.

To do all of this, I would need the help of Site Management APIs.

This post walks you through everything you need to securely authenticate and make a REST API call that results in a new site being created in OCE, based on a template you’ve specified, using the metadata you’ve supplied in the API call.

First, a few prerequisites

Administrator access

To setup the Application User we’ll be creating to run this application, you’ll either need the Identity Domain Administrator or Application Administrator role in your tenant. If you don’t have that level of access, pull in someone from your group that can get you through the Application User setup steps outlined below.

Existing template

In this example, we’ll be creating a site from an existing template. If you’re Oracle Content instance doesn’t have any templates yet, please create one using these instructions. We’ll be referencing the name of the template in the API call later, so keep that handy.

Test tool

While the eventual goal for this type of application would be to build it into a site form, for this article, I’m going to use the popular Postman API development tool. This should make it easier to focus on authentication and interacting with the Oracle Content APIs. Once you’ve got this working, you can worry about the many other considerations of building a site that accepts and processes form submissions.

Postman is powerful, visual, intuitive, cross-platform, and potentially free depending on your needs. However, everything I describe here can be accomplished with other tools, such as curl, so use what’s familiar to you.

Determine if site governance is enabled

This is a quick one, but it’s good to know. If Site Governance is enabled in your instance, the request we’ll be making to Oracle Content will need an additional field, and the sites that are created will likely be in a “pending-approval” state until you approve or reject them.

Review Oracle Content Management API documentation

The following resources came in handy when I was learning to work with the Oracle Content APIs and will come in handy as you work through this article and hopefully expand upon it in the future.

Authentication – Developer access to Oracle Content REST APIs is protected by CG/WTSS using OAuth clients.

Access Using 2-Legged OAuth – For access using 2-legged OAuth, you can use client credentials to acquire the client ID and secret required to get an access token from Oracle Identity Cloud Service (IDCS).

Oracle Content REST APIs – The REST APIs are available in Oracle Content for delivery and management of content, conversations, documents, sites, users, and groups.

Site Management APIs – The Oracle Cloud REST API for Sites Management provides the ability to create sites from templates and then manage the lifecycle of those sites in Oracle Content.

Let’s get started

Set up your Application User

As we won’t be working with a user interface, a username and password isn’t the right solution to access the APIs we’ll be using. Instead, we’re going to create a Confidential Application and provide that application with the appropriate access so it’s clear modifications are being made by this application and that changing your password won’t break it.

To authenticate to the APIs from this user, we’ll us 2-legged OAuth. This is a method used to grant applications appropriate access without using a password. If you’re not familiar with OAuth, you should read up on that technology before proceeding with this process.

If you’re looking for more details about this step in the process, please visit Access Using 2-Legged OAuth.

If you have the Identity Domain Administrator or Application Administrator role, begin by authenticating to your Oracle Content instance. From your Oracle Content domain, which is in the format of something like mycompanyname.cec.ocp.oraclecloud.com, you’ll be forwarded to an Identity Cloud Service domain that looks something like idcs-alphaNumericValue.identity.oraclecloud.com/ui/v1/signin/

Throughout this process, you’re going to be gathering several values you’ll need later. Before proceeding, grab this IDCS domain [idcs-alphaNumericValue.identity.oraclecloud.com] and put it in a notepad. We’ll be using this value in the Access Token URL field explained later on.

Instead of authenticating as normal, change the path of the URL to be /ui/v1/adminconsole and hit go. This will bring you back to the authentication screen again but this time you should actually sign in. Once authenticated, you’ll be taken to the admin console that looks like this:

IDCS homepage

On the Applications and Services card, click the New Application button in the card header. Smaller screens may first need to click on the Go to Applications page button in the card’s body. On the resulting pop-up, select Confidential Application. This will create an application user meant to be used by a server-to-server authentication using OAuth 2.0.

On this first page, the only required field is *Name. It’s always a good idea to pick a memorable name so it’s clear this user is being used to power your application. Objects you create using this “Confidential Application” will show this name as the owner/creator. All other fields and checkboxes can be left blank.

Add confidential application

On Step 2 of this wizard, select Configure this application as a client now. In the Authorization section, check the box to the left of Client Credentials.

Configure this Application

Scroll down to the Token Issuance Policy section and click Add Scope under Resources to give the application access to the Oracle Content instance in which you’ll be working. Look for an entry on this list in the form of “CECSAUTO_” and then the name of your instance. Instead of clicking the main checkbox, click on the button to the right (looks like a > symbol). This will display three scopes for your instance. Put a check on the item that ends in “urn:opc:cec:all” and click add.

Copy and paste the full URL shown in the Scope column to your notepad of important values.

This should bring you back to the Add Confidential Application wizard, remaining on step 2. Continue clicking Next as the other settings don’t need to be modified at this point.

Add Scope

After the last step, you’ll receive a pop-up that provides you with a new Client ID and a Client Secret. Copy these values to the notepad you’ve been using. You’ll need them going forward.

Application Added

The last step: Click the Activate button at the top right.

At this point, you should have the following six values:

6 example values

Set up a Postman Environment

Now that we have a user with access to our Oracle Content instance, we’re going to make our first call to make sure everything is working. As I mentioned above, we’re going to be using Postman to manage our credentials, authenticate using OAuth, and put together the request package we’ll be firing off at Oracle Content.

Create a new Request

Click on the + New button at the top left, and select Request from the Create New tab. Give it a name, description, and put it in an existing Collection or create a new one. Finally click Save.

Create New Request

You should now be looking at a blank request form.

New Blank Request

Basic Request Details

From here, you can control all aspects of the request. We’re going to start with setting up the request Method [POST] and URL [https://yourInstanceName.cec.ocp.oraclecloud.com/sites/management/api/v1/sites/]

Post Request URL

Authorization

From the Authorization tab, change the Type drop-down to OAuth 2.0 and Add authorization data to Request Headers.

Authorization

To properly generate an OAuth token, we’re going to need those special values I asked you to keep on a notepad. Add your values to the Configure New Token section of this screen.

Configure New Token values

Next, click Get New Access Token. You should see a pop-up window and then a response for the Access Token field (an extremely long alphanumeric value about a page long). Click the Use Token button, and you should now see it listed in the Current Token form.

Access Token

Note: If something goes wrong, you may see an error or some HTML code that suggests something didn’t work. Go back and check the user provisioning steps and values discussed above. Until this works properly, there is no point continuing.

Headers

With authorization set up, we can move on to headers. A number of headers will automatically be included in the request. Leave those in place. Add a new header (Prefer) to the bottom of the list with a value of respond-async. This may not be needed by all our APIs, but the site creation API we’ll be using does require it. You’ll always receive a helpful error telling you if this header is needed or not.

Body

The last thing we need to set up is the Body. For these APIs, we’ll be sending “raw, JSON,” so make sure those options are selected so you can properly add the JSON.

Body - Raw - JSON

Per the documentation, this API requires three fields when site governance is disabled and four when it’s enabled. The only field you must update before sending the request is the template. This field must contain the name of a valid template in your instance.

Without Governance:

{
  "template": "name:Access",
  "name": "ProductLaunch",
  "description": "Marketing site for the New Product Launch."
}

With Site Governance:

{
  "template": "name:Access",
  "name": "ProductLaunch",
  "description": "Marketing site for the New Product Launch.",
  "justification": "I require a marketing site for our new product."
}

Once you’ve added this to the body field and supplied proper values, click the blue Send button. Remember: The template must already exist and be active, and the site name must be unique.

A successful request will only receive a “202: Accepted” response.

If you receive an error, such as Inactive Template Policy, you should confirm a few things. Confirm the name of the template you’re referencing is spelled correctly and is preceded by name: in the template field of the JSON body. You can also use the GUID of the template, in which case do not prepend name: in the JSON. Lastly, confirm the template is active. To check this, you’ll need to open the template details from OCE and view the status field.

Active Template

Other common error situations should be pretty easily fixed by reviewing the error message you receive. For example, a site name must be unique, so you will need to change it while you test.

Note: If Site Governance is enabled in your Oracle Content instance, the new site will show up in the Requests view until it is approved. If Site Governance is disabled, the new site will show up in the default sites list.

Next steps

Did that seem like a lot? It did the first time I went through it, but honestly, that’s 80% of the effort you’ll need to interact with just about any of our APIs. Once you have this working, little changes like GET vs. POST, different API end-points, and different JSON bodies are all it takes to fully leverage Oracle Content from a server application rather than our UI. The possibilities are endless.

Look for another tutorial soon with all of the details you’ll need to:

  • Stand up such an application using Oracle Cloud Infrastructure.
  • Build a site with a form that will accept all these values.
  • Make the appropriate request behind the scenes.
  • Allow you to publish the form where your coworkers can actually use it to request sites.

If you’ve made it this far, my guess is it’s time for a coffee break. Hopefully, you found this helpful and can use it to build something that saves you tons of time and brings even more value to your organization.

To familiarize yourself even more with Oracle Content APIs, review our comprehensive documentation on:

Christopher A. DeGrace

Senior Principal Product Manager

Christopher DeGrace is a Product Manager with a background in SaaS and PaaS product lines. He currently works on the Oracle Content Management team focusing on Governance and CDN distribution.


Previous Post

Oracle’s latest innovations support today’s CRO and multi-experience sales engagement

Katrina Gosek | 5 min read

Next Post


The Cost of CRM Software: Cloud vs. On Premise

Benjamin Hunting | 4 min read