fusion-help-docs

Fusion Help のドキュメント

fhelp CLI を使って、ヘルプドキュメント（記事、リリースノート、FAQ）を作成、構成、公開します。

使用する場面

• Fusion アプリのヘルプ記事を作成する
• リリースノートを作成／更新する
• ドキュメントフォルダーの構成と設定を行う
• ヘルプシステム向けに Markdown を構成する
• ドキュメントを Fusion 環境に公開／同期する
• FAQ の項目を追加する
• 自動公開する CI/CD パイプラインを設定する

使用しない場面

• fusion-help-cli のソースを変更する（tooling/fusion-help-cli/）
• Fusion.Services.Help バックエンド API を変更する
• Fusion Help と関係のない一般的な Markdown 編集
• ドキュメント作成以外のタスク

必要な入力

作成前に、以下の情報を収集してください。

入力	必須	説明
アプリキー	はい	Fusion アプリのキー（例：my-app、resource-allocation-landingpage）。ユーザーはこのアプリの管理者である必要があります。
コンテンツの種類	はい	articles、release-notes、または faqs
ドキュメントのルートパス	はい	チームがドキュメントを保存する場所（例：docs/help/）
対象環境	公開する場合	ci、fqa、tr、または fprd

不明なアプリキーの場合は、アプリ管理画面を確認してください。

• CI：https://fusion.ci.fusion-dev.net/apps/app-admin
• 本番環境：https://fusion.equinor.com/apps/app-admin

「Admins」セクションを確認してください。公開するには、管理者として登録されている必要があります。

手順

1. ドキュメントフォルダーの構成を設定する

次のフォルダーレイアウトを作成します。

docs/
  help/
    articles/                    # Markdown article files
      images/                    # Article images (PNG format)
    release-notes/               # Markdown release note files
      images/                    # Release note images (PNG format)
    faqs/                        # Optional: markdown FAQ body overrides
    help-articles.json           # Article config
    help-release-notes.json      # Release notes config (if using release notes)

フォルダー名と設定名は自由に決められますが、fhelp に渡す名前と一致させる必要があります。

2. 記事の設定ファイルを作成する

help-articles.json を作成します（CLI が同期する記事を指定します）。

{
  "articles": [
    {
      "slug": "my-app-getting-started",        // Must match the .md filename (without extension)
      "title": "Getting Started",               // Display title in Fusion Help
      "appKey": "my-app",                       // Your Fusion app key
      "sortOrder": 1.0,                         // Controls display order (lower = first)
      "summary": "Learn how to get started.",   // Short description shown in article list
      "tags": ["getting-started", "onboarding"],// Searchable tags
      "relevantApps": []                        // Optional: other app keys where this shows
    }
  ]
}

設定フィールドのリファレンス

フィールド	必須	型	説明
slug	はい	string	一意の識別子です。記事のルートフォルダーにある {slug}.md ファイルと一致する必要があります。ケバブケースを使用してください。
title	はい	string	Fusion Help に表示される、人が読めるタイトルです。
appKey	はい	string	この記事が属する Fusion アプリのキーです。このアプリの管理者である必要があります。
sortOrder	いいえ	number	表示順を制御します。数値が小さいものほど先に表示されます。既定値は状況によって異なります。順序を柔軟に設定するには、小数（1.0、1.1、2.0）を使用してください。
summary	はい	string	記事一覧に表示される短い説明です。
tags	いいえ	string[]	分類に使用する検索可能なタグです。
relevantApps	いいえ	string[]	この記事を表示する追加のアプリキーです。

3. 記事の内容を作成する

記事のルートフォルダーに Markdown ファイルを作成します。ファイル名（.md を除く）は、設定の slug と一致する必要があります。

記事作成のガイドライン：

• Fusion アプリのエンドユーザー向けに記述します
• 構成には ##、### を使用し、# は避けてください（タイトルは設定から取得されます）
• 画像は images/ に配置し、![Alt text](images/my-screenshot.png) のように参照します
• CLI が画像を自動でアップロードし、パスを CDN 向けに書き換えます
• 画像は PNG である必要があります（CLI の制限）
• 1 つの記事につき 1 つのトピックを扱います
• 関連記事はタイトルでリンクします（ディープリンクはプラットフォームが処理します）

記事の例（docs/help/articles/my-app-getting-started.md）：

## Overview

This guide walks you through the basics of using My App.

## Prerequisites

Before you begin, make sure you have:
- Access to the Fusion portal
- The correct role assigned to your user

## Step 1: Navigate to the app

Open Fusion and search for "My App" in the app launcher.

![App launcher](images/app-launcher.png)

## Step 2: Create your first item

Click the **New** button in the toolbar to create your first item.

## Need help?

Contact the team on Teams or check the FAQ section.

4. リリースノートの設定ファイルを作成する（任意）

チームがリリースノートを公開する場合は、help-release-notes.json を作成します。

{
  "releaseNotes": [
    {
      "slug": "my-app-v2-release",              // Must match the .md filename
      "title": "Version 2.0 Release",           // Display title
      "appKey": "my-app",                       // Your Fusion app key
      "publishedDate": "2026-03-14T00:00:00Z",  // Publication date (ISO 8601)
      "tags": ["release", "v2"],                // Searchable tags
      "relevantApps": []                        // Optional: other app keys
    }
  ]
}

リリースノート設定フィールドのリファレンス

フィールド	必須	型	説明
slug	はい	string	一意の識別子です。リリースノートのルートフォルダーにある {slug}.md ファイルと一致する必要があります。
title	はい	string	リリースノートのタイトルです。
appKey	はい	string	Fusion アプリのキーです。管理者である必要があります。
publishedDate	はい	ISO 8601 date	リリースが公開された日付です。
tags	いいえ	string[]	検索可能なタグです。
relevantApps	いいえ	string[]	追加のアプリキーです。

リリースノートの例（docs/help/release-notes/my-app-v2-release.md）：

## What's new in Version 2.0

### New dashboard

We've completely redesigned the dashboard with new charts and filtering capabilities.

![New dashboard](images/new-dashboard.png)

### Performance improvements

- Page load times reduced by 40%
- Search results now appear in under 1 second

### Bug fixes

- Fixed an issue where filters would reset on navigation
- Corrected date formatting in the export feature

5. CLI をインストールして認証する

Fusion Public フィードからインストールします：

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

既存のインストールを更新します：

dotnet tool uninstall --global Fusion.Help.Cli
dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

Azure CLI で認証します：

az login

CLI は DefaultAzureCredentials を使用します。az login のセッションが自動的に検出されます。

6. ドキュメントを公開する

記事を同期します：

fhelp article sync -f docs/help/help-articles.json -r docs/help/articles -e ci -v

リリースノートを同期します：

fhelp releasenotes sync -f docs/help/help-release-notes.json -r docs/help/release-notes -e ci -v

コマンドのフラグ：

フラグ	説明
-f, --file	JSON 設定ファイルのパス
-r, --root	Markdown ファイルを含むフォルダーのパス
-e, --env	対象環境：ci、fqa、tr、fprd
-t, --token	アクセストークンを上書きします（任意）
-v, --verbose	詳細なログ出力を表示します
--no-validation	ソースシステムのチェックをスキップします — 慎重に使用してください。UI で作成されたコンテンツを上書きする可能性があります

環境の昇格順序： ci → fqa → fprd（インフラストラクチャのテスト以外では tr をスキップします）。

fqa、続いて fprd に昇格する前に、ci でテストしてください。

7. CI/CD パイプラインを設定する（推奨）

Azure DevOps または GitHub Actions を使って公開を自動化します。

Azure DevOps パイプラインの例：

parameters:
  - name: environment
    type: string
    default: ci
    values: [ci, fqa, fprd]
  - name: azureSubscription
    type: string

steps:
  - checkout: self

  - script: |
      dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli
    displayName: "Install fusion help CLI"

  - task: AzureCLI@2
    displayName: "Sync help articles"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp article sync `
          -f ./docs/help/help-articles.json `
          -r ./docs/help/articles `
          -e "${{ parameters.environment }}" `
          -v

  - task: AzureCLI@2
    displayName: "Sync release notes"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp releasenotes sync `
          -f ./docs/help/help-release-notes.json `
          -r ./docs/help/release-notes `
          -e "${{ parameters.environment }}" `
          -v

GitHub Actions の例：

name: Sync Help Documentation

on:
  push:
    branches: [main]
    paths: ['docs/help/**']

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install fusion help CLI
        run: |
          dotnet tool install --global \
            --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" \
            Fusion.Help.Cli

      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: '3aa4a235-b6e2-48d5-9195-7fcf05b459b0'
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Sync articles
        run: |
          fhelp article sync \
            -f ./docs/help/help-articles.json \
            -r ./docs/help/articles \
            -e ci -v

8. よくある質問（補足）

よくある質問では Excel ベースのワークフローを使用し、アプリレベルのアクセスが必要です。これは一時的なソリューションであり、複数のアプリにまたがるよくある質問がある場合に最適です。

fhelp faq sync -f docs/help/faqs.xlsx -e ci -v

多くのチームにとって、https://fusion.equinor.com/apps/fusion-help-admin の Fusion Help Admin UI でよくある質問を管理するほうが簡単です。

期待される出力

• 記事、画像、設定を含む docs/help/ フォルダー
• 適切なコンテンツを含む Markdown 記事ファイル
• 有効な help-articles.json（および任意の help-release-notes.json）
• fhelp のインストール、認証、実行方法
• CI/CD パイプラインのスニペット（任意）

トラブルシューティング

問題	原因	解決策
DefaultAzureCredential failed to retrieve a token	認証されていない	az login を実行します
403 Forbidden	アプリキーの管理者ではない	アプリの管理ページで管理者リストを確認するか、設定の appKey を確認します
記事が作成されない（スキップされる）	ルートフォルダーに一致する .md ファイルがない	ファイル名がスラッグと完全に一致していることを確認します：{slug}.md
ソースシステム不一致の警告	記事は UI から作成されているため、CLI では上書きされない	--no-validation を慎重に使用するか、別のスラッグを使用します
画像がアップロードされない	形式が正しくない	画像は PNG 形式である必要があります

安全性と制約

• 内容を理解せずに --no-validation を使用しないでください — UI で作成されたコンテンツを上書きする可能性があります
• fprd に公開する前に ci でテストしてください
• sourceSystem は Fusion.Help.Cli に自動設定されます。CLI と UI の記事はソースシステムが異なるため、--no-validation を使用しない限り競合しません
• スラッグは全体で一意である必要があります — アプリ固有のプレフィックスを使用してください（例：my-app-getting-started）
• アクセストークンをコミットしないでください — az login またはパイプラインのサービスプリンシパルを使用してください