マーケットプレイス版Oracle WebCenter Content For OCIのApplinkを使ってカスタムアプリケーションにWCCのフォルダUIを埋め込み表示する

# はじめに

マーケットプレイス版Oracle WebCenter Content For OCI(以降**WCC For OCI**)は、Oracle Cloud Infrastructure上のVMベースのソリューションとして提供されます。マーケットプレイス版のOracle WebCenter Contentを使用すると、顧客は数回クリックするだけで環境をプロビジョニング/セットアップでき、クラウド上でコンテンツ・ソリューションを提供できるようになります。

詳細は製品ドキュメントおよび概要紹介資料をご確認ください

**製品ドキュメント**

https://docs.oracle.com/en/cloud/paas/webcenter-content/webcenter-content-marketplace/index.html

**概要紹介資料(SpeakerDeck)**

https://speakerdeck.com/oracle4engineer/oracle-webcenter-content-for-oci-on-marketplace

# この記事で説明すること、しないこと

この記事では、先日リリースされた**25.2.1 - February 2025**より利用可能になった**Applink**を利用し、カスタムアプリケーションにWCCのフォルダUIを連携(埋め込み表示)する方法について説明します

https://docs.oracle.com/en/cloud/paas/webcenter-content/content-marketplace-new/index.html#february-2025

なお、WCC For OCIのプロビジョニング手順の詳細は割愛します。具体的なプロビジョニング手順は、上記の製品ドキュメントやあとの章で紹介するQiita記事を参考にしてください

# Applinkとは

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/a53466f4-24a8-4a89-ba2b-6f648d1d1c29.png)

**説明**
- Applinkは**REST API**として提供されます
- カスタムアプリケーションから`このユーザーがこのアクセス権限でこのフォルダ（もしくはファイル）にアクセスします`とREST APIにリクエストを送信すると、WCCはアクセスに必要な **アクセストークン** と **埋め込み用URL** などを払い出します
- WCCから払い出された**埋め込み用URL**と**アクセストークン**を利用し、カスタムアプリケーションはWCCのフォルダ（もしくはファイル）を自身のUIに**埋め込み表示**します
- （WCCのユーザーアカウントを持たない）カスタムアプリケーションのユーザーは、埋め込み表示されたWCCのフォルダ（もしくはファイル）を許可されたアクセス権限で操作することができます
- 払い出された埋め込み用URLは、ブラウザのアドレスバーに直接入力して使用することはできません。
- Applinkは本質的に**開発者中心の機能**であり、カスタムアプリケーション側でのプログラム開発が必要です


**関連ドキュメントおよび記事**

https://docs.oracle.com/en/cloud/paas/webcenter-content/use-public-links/index.html#manage-applinks

https://docs.oracle.com/en/cloud/paas/webcenter-content/use-redwood-ui/index.html#embedding-folders-and-files-with-applinks

https://docs.oracle.com/en/cloud/paas/webcenter-content/webcenter-content-api/index.html#applinks

https://qiita.com/nakasato310/items/779a752b65e75fc63453


# 1. 構築する環境の説明と準備

## 1.1 説明

今回は以下のような環境を準備します

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/4bdf37b9-8fd5-4e41-befc-4745ef96275d.png)

## 1.2 カスタムアプリケーション(Apache)
ローカルPC(ここではMacOS)にApache HTTP Serverを構成し、ブラウザから`http://localhost`でアクセスできるようにします。
私は以下の記事を参考に、MacOSにApacheをローカルのWebサーバとしてセットアップしました

https://qiita.com/shuntaro_tamura/items/bdabcb77926dc92617b1

ブラウザで`http://localhost`にアクセスし、いつもの **It Works!** が表示されればOKです
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/4cc1ccfe-570c-4f0f-902d-7c58a33fa661.png)

## 1.3 WCC For OCIインスタンス

WCC For OCIの環境を作成し、起動します。以下のQiita記事などを参考にしてください

https://qiita.com/shinwata/items/d7b478031ea45f0a3565

なお、過去にWCC For OCI環境を作成済で、最新バージョン(25.2.1以上)を利用していない場合は、以下の製品ドキュメントを参考に**WCC環境へのパッチ適用**を実施してください

https://docs.oracle.com/en/cloud/paas/webcenter/webcenter-marketplace/index.html#about-the-patch-tool

ブラウザでWCCのネイティブUI`https://<ロードバランサのパブリックIPアドレス>:16200/cs/`にアクセスし、以下の画面が表示されればOKです
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/a295181c-64b2-4ce4-82de-9fe0f9308984.png)

## 1.4 カスタムアプリケーションのドメインへの埋込み表示を許可する

WCC For OCIのconfig.cfgに`RedwoodUIFrameAncestors`パラメータを追加し、指定ドメイン（今回は`http://localhost`）に対してWCCのUIを埋め込み表示することを許可します

1. WCC For OCIの**ネイティブUI**にシステム管理者でサインインします
1. **管理→管理サーバー→一般構成**を開きます
1. **追加の構成変数:** に`RedwoodUIFrameAncestors=http://localhost`パラメータを追加し、**保存**をクリックします
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/668796f9-1b61-4c05-99c1-930974987687.png)

1. UCMサーバー(UCM_server1)を再起動します

## 1.5 埋め込み用フォルダを作成する

WCC For OCIの**Redwood UI**にWebブラウザでアクセスし、埋め込み表示するフォルダを作成します

1. WCC For OCIの**Redwood UI**にサインインします
1. **参照**を開き、任意のライブラリ配下にフォルダを作成します（ここでは`TESTLibrary`の下に**テスト**フォルダを作成）
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/71b16905-cf21-4541-9512-576a3c93d714.png)
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/1af03f16-13c6-42af-9547-dac0ec949709.png)
1. 作成したフォルダ選択し、**プロパティ**を開きます
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/ebf9ce82-9f5d-4f42-b52d-a80ea4e06527.png)
1. **フォルダID**をメモします
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/d511bc25-fe93-406e-9a48-e2419450662c.png)

# 2. カスタムアプリケーションの開発

## 2.1 REST APIの確認

今回は以下のREST APIを利用し、**フォルダのApplink**を作成します

https://docs.oracle.com/en/cloud/paas/webcenter-content/webcenter-content-api/index.html#create-an-applink-to-a-folder

PostmanなどのRESTクライアントからこのREST APIを実行し、その動作を確認します

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/4d3e0afd-441b-48c7-afbb-1302ce82195a.png)


レスポンスのBodyを確認すると、以下のようなJSONデータを受信します
```json:レスポンスデータ
{
   "dAppLinkID":"LFVODdd9lvUc1NO9gW6kEY24aR5yh...",
   "dAppLinkAccessToken":"RrDcdPJp30-gsTpvaOo8DVhJnK1vufxkkdpK_Fcw...",
   "dAppLinkRefreshToken":"9FaB_48sSWe_ekfQi6OvcV...",
   "dEmbedUrl":"https://<LoadBalancer Public IP>:16200/cs/idcplg?IdcService=REDWOODUI_FOLDER_VIEWER&fFolderGUID=80E6A267BFBFA519665D6F96DD13FC7F&dAppLinkID=LFVODdd9lvUc1NO9gW6kEY24aR5yh...&ActAsAnonymous=1"
}
```

カスタムアプリケーションはこれらレスポンスデータを利用して、WCCのフォルダUIを埋め込み表示するプログラムを実装します

## 2.2 カスタムアプリケーションの開発

製品ドキュメントにサンプルコードがありますので、まずはご確認ください

https://docs.oracle.com/en/cloud/paas/webcenter-content/use-redwood-ui/index.html#applink_sample.html

では、実際に開発していきます。Webサーバに配置するHTMLファイル`applink.html`とJavaScriptファイル`applink.js`を作成します。以下サンプルです

```html:applink.html
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Applink Sample</title>
</head>

<body>
  <p>Embed WCC Redwood UI using Applink API</p>
  <iframe id="applink_frame" name="applink" src="" width="1024" height="640"></iframe>

  <script src="./applink.js"></script>
</body>
</html>
```

```javascript:applink.js
async function callApi() {
	// WCC Access User info
	const username = "weblogic"; // ユーザー名
	const password = "xxxxxxxx"; // パスワード
	const auth = btoa(username + ":" + password); // Base64でエンコード

	// REST API - Create an applink to a Folder
	const base = "https://<Load Balancer Public IP>:16200/documents/wcc/api/v1.1/applinks/.by.folder/";
	const folderid = "<Folder ID>";
	const callurl = new URL(folderid, base);

	try {
		const res = await fetch(callurl, {
			method: "POST",
			headers: {
				"Content-Type": "application/json",
				"Authorization": "Basic " + auth
			},
			body: JSON.stringify({
				"dAssignedUser": "AppUser1",
				"dLinkPrivilege": "RW",
				"dUserLocale": "ja-JP",
				"dUserTimeZone": "Asia/Tokyo"
			})
		})

		const createApplinkResponse = await res.json();

		const wccOrigin = new URL(createApplinkResponse.dEmbedUrl).origin;

		const iframe = document.getElementById('applink_frame');

		window.addEventListener('message', (event) => {
			if (event.origin !== wccOrigin) return; // ensure message is from WCC

			if (event.data?.message === 'appLinkReady') {
				var iframewindow = iframe.contentWindow ? iframe.contentWindow : iframe.contentDocument.defaultView;
				iframewindow.postMessage({
					message: 'setAppLinkTokens',
					dAppLinkID: createApplinkResponse.dAppLinkID,
					dAppLinkAccessToken: createApplinkResponse.dAppLinkAccessToken,
					dAppLinkRefreshToken: createApplinkResponse.dAppLinkRefreshToken,
				}, '*');
			}
		}, false);

		iframe.src = createApplinkResponse.dEmbedUrl;
	} catch {
		console.error(error.message);
	}
};

callApi();
```

作成したhtmlとjsをWebサーバのドキュメントルートに配置します。今回（MacOS）の場合は、`/Library/WebServer/Documents/`です

**説明**
WCCのフォルダにアクセスできる**ユーザー名**と**パスワード**を指定します
```javascript
	// WCC Access User info
	const username = "weblogic"; // ユーザー名
	const password = "xxxxxxxx"; // パスワード
	const auth = btoa(username + ":" + password); // Base64でエンコード
```

`<Load Balancer Public IP>`は、WCC For OCIインスタンスの**ロードバランサのパブリックIPアドレス**を指定します
`<Folder ID>`は、準備時にメモした**フォルダID**を指定します
```javascript
    // REST API - Create an applink to a Folder
	const base = "https://<Load Balancer Public IP>:16200/documents/wcc/api/v1.1/applinks/.by.folder/";
	const folderid = "<Folder ID>";
	const callurl = new URL(folderid, base);
```

作成するApplinkの定義(条件)を指定します。`dAssignedUser`のみ**必須**で、その他は**オプション**です

- `dAssignedUser`: 埋め込みリンクを利用するユーザー名を指定します。埋め込みUIからフォルダやファイルを作成すると、**作成者**として記録されます
- `dLinkPrivilege`: 埋め込みリンクのアクセス権限を指定します。R/RW/RWD/RWDAから選択。デフォルトは**R**
- `dUserLocale`: 埋め込みリンクで表示されるUIのロケール(言語)を指定します。選択するロケールは、事前にWCC側で有効化されている必要があります
- `dUserTimeZone`: 埋め込みリンクで表示されるUIのタイムゾーンを指定します

```javascript
	body: JSON.stringify({
		"dAssignedUser": "AppUser1",
		"dLinkPrivilege": "RW",
		"dUserLocale": "ja-JP",
		"dUserTimeZone": "Asia/Tokyo"
	})
```

# 3. 確認

1. ブラウザを開き、`http://localhost/applink.html`を開きます。WCCのフォルダが埋め込み表示されます
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/5823f858-8f1b-4267-88a4-d06b537c72f7.png)

1. **フォルダの作成**をクリックし、フォルダを作成します（ここでは**サブフォルダ**を作成）
  ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/dc66d590-5f1d-47f9-a5b2-f4174434fba7.png)
  ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/decbbdab-f00f-4d45-8b83-2bd4de8eacc3.png)

1. 作成したフォルダ（ここでは**サブフォルダ**）を開きます
1. **アップロード**ボタンをクリックし、ファイルを1件アップロードします。
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/fcc1a199-2b4a-447b-88ab-79bf1e0ae174.png)
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/243062dc-726a-4f5d-a8af-aaacf886b1d3.png)
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/7578ee13-f2b6-433b-a2fe-31f866e35e90.png)
  ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/e5102435-0576-4c49-9316-f892d0f58d1d.png)

1. ファイルを選択すると、RW権限で利用できる**表示**や**ダウンロード**、**チェックイン**などの操作ができることを確認します。また、**削除**のメニューは**表示されない**こともあわせて確認します
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/c9001246-1eb4-4783-b838-132dc3afd78f.png)

1. WCCのRedwood UIに戻り、**テスト**フォルダを開きます。カスタムアプリケーションの埋め込み用UIから作成した**サブフォルダ**とアップロードしたファイルを確認します
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/9832a041-ee25-48cc-8fe5-7e1891463308.png)
1. ファイルを選択し、**プロパティ**を開きます。Applink作成時に`dAssignedUser`に指定した**AppUser1**が、**作成者**として記録されていることを確認します
  ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/2751bad6-8349-48a8-b943-7332a3031990.png)

# おわりに

Applink機能をつかって、カスタムアプリケーションにWCCのフォルダUIを埋め込み表示する方法を説明しました。皆さまのお役に立てば幸いです