サービスポータル API - ServiceNow Fluent

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：23分

    • サービスポータル API は、ポータルページのカスタムウィジェット [sp_widget] を定義します。

    注:
    最新の ServiceNow Fluent API ドキュメントと例については、 ServiceNow Fluent API リファレンス および ServiceNow SDK のサンプルリポジトリ ( GitHub)。

    ポータルに関する一般的な情報については、「 Service Portal」を参照してください。

    SPWidget オブジェクト

    ポータルページに含めるカスタムウィジェット [sp_widget] を作成します。

    カスタムウィジェットの作成に関する一般的な情報については、「 Developing custom widgets」を参照してください。

    表 : 1. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。ウィジェットの名前。
    category 文字列 ウィジェットのタイプ。
    有効な値：
    • standard
    • その他のアプリケーション
    • カスタム
    • sample
    • ナレッジベース
    • サービスポータル
    • サービスカタログ

    デフォルト:カスタム
    クライアントスクリプト スクリプト AngularJS コントローラーを定義するクライアント側スクリプト。 このプロパティは、インライン JavaScript、またはスクリプトを含むアプリケーション内の別のファイルへの参照をサポートします。
    Format (形式)：
    • 別のファイルのテキストコンテンツを使用するには、 Now.include('path/to/file') の形式を使用してアプリケーション内のファイルを参照します。詳細については、「ServiceNow Fluent 言語構成」を参照してください。
    • インラインスクリプトを指定するには、複数行のコードに文字列リテラルまたはテンプレートリテラルを使用します ( 「スクリプト」または「スクリプト」)。
    Default (デフォルト)： 
    api.controller=function() { /* widget controller */ var c = this;};
    サーバースクリプト スクリプト ウィジェットの初期状態を設定するサーバー側スクリプト、 データ オブジェクトを使用してウィジェットのクライアントスクリプトにデータを送信するサーバー側スクリプト、またはサーバー側のクエリーを実行するスクリプト。 このプロパティは、インライン JavaScript、またはスクリプトを含むアプリケーション内の別のファイルへの参照をサポートします。
    Format (形式)：
    • 別のファイルのテキストコンテンツを使用するには、 Now.include('path/to/file') の形式を使用してアプリケーション内のファイルを参照します。詳細については、「ServiceNow Fluent 言語構成」を参照してください。
    • インラインスクリプトを指定するには、複数行のコードに文字列リテラルまたはテンプレートリテラルを使用します ( 「スクリプト」または「スクリプト」)。
    Default (デフォルト)：
    (function () { /* populate the 'data' object */ /* e.g., data.table = $sp.getValue('table'); */ })();
    controllerAs 文字列 ディレクティブのスコープ内のコントローラーへの参照の変数。クライアントスクリプトは、デフォルトで c.data 変数を使用してサーバーデータオブジェクトにアクセスします。

    デフォルト値:c
    htmlTemplate 文字列 ページが表示されるときに何をレンダリングするかを定義する本文 HTML コード。静的 XHTML、Jelly として定義された動的に生成されたコンテンツを含めるか、またはスクリプトインクルードと UI マクロを呼び出すことができます。 このプロパティは、HTML またはインライン HTML を含むアプリケーション内の別のファイルへの参照をサポートします。
    Format (形式)：
    • 別のファイルのテキストコンテンツを使用するには、 Now.include('path/to/file') の形式を使用してアプリケーション内のファイルを参照します。詳細については、「ServiceNow Fluent 言語構成」を参照してください。
    • インライン HTML を提供するには、複数行のコードに文字列リテラルまたはテンプレートリテラルを使用します ( 「HTML」または「HTML」)。
    Default (デフォルト)：
    <div><!-- your widget template --></div>
    customCss 文字列 ウィジェットのスタイルを定義する CSS または SCSS。 このプロパティは、CSS またはインライン CSS を含むアプリケーション内の別のファイルへの参照をサポートします。
    Format (形式)：
    • 別のファイルのテキストコンテンツを使用するには、 Now.include('path/to/file') の形式を使用してアプリケーション内のファイルを参照します。詳細については、「ServiceNow Fluent 言語構成」を参照してください。
    • インライン CSS を提供するには、複数行のコードに文字列リテラルまたはテンプレートリテラルを使用します ( 「CSS」または「CSS」)。
    データテーブル 文字列 ウィジェットインスタンスオプションを格納するテーブル。カスタムオプションスキーマを定義するには、ウィジェットインスタンス [sp_instance] テーブルを拡張するテーブルにフィールドを追加し、拡張テーブルをデータソースとして使用するようにウィジェットを設定します。詳細については、「Store instance options in a table」を参照してください。

    デフォルト値:sp_instance
    デモデータ 文字列またはオブジェクト ウィジェットの機能を示すデータ。このプロパティは、インライン文字列、JSON を含むアプリケーション内の別のファイルへの参照、またはインライン JSON シリアル化可能オブジェクトをサポートします。
    Format (形式)：
    • 別のファイルのテキストコンテンツを使用するには、 Now.include('path/to/file') の形式を使用してアプリケーション内のファイルを参照します。詳細については、「ServiceNow Fluent 言語構成」を参照してください。
    • インライン JSON を提供するには、キーと値のペアを持つオブジェクト { key: value } を使用します。
    説明 文字列 ウィジェットとその目的の説明。
    ドキュメント 参照 ウィジェットとその目的に関する追加情報を提供する サービスポータル ドキュメント [sp_documentation] の変数識別子。

    サービスポータルドキュメントを定義するには、「レコード API - ServiceNow Fluent」を参照してください。
    フィールド アレイ ウィジェットオプションスキーマで使用するデータテーブルの列名のリスト。
    hasPreview ブール ウィジェットエディターからウィジェットをプレビューできるかどうかを示すフラグ。
    有効な値：
    • true:ウィジェットエディターからウィジェットをプレビューできます。
    • false:ウィジェットエディターからウィジェットをプレビューすることはできません。

    デフォルト値：false
    ID 文字列 ウィジェットの一意の ID。ID にスペースを含めることはできません。
    リンクスクリプト スクリプト AngularJS を使用して DOM を直接操作するリンク関数。 このプロパティは、インライン JavaScript、またはスクリプトを含むアプリケーション内の別のファイルへの参照をサポートします。
    Format (形式)：
    • 別のファイルのテキストコンテンツを使用するには、 Now.include('path/to/file') の形式を使用してアプリケーション内のファイルを参照します。詳細については、「ServiceNow Fluent 言語構成」を参照してください。
    • インラインスクリプトを指定するには、複数行のコードに文字列リテラルまたはテンプレートリテラルを使用します ( 「スクリプト」または「スクリプト」)。
    Default (デフォルト)： 
    function link(scope, element, attrs, controller) { }
    ロール アレイ ものにアクセスできるロールオブジェクトの変数識別子またはロールの名前のリスト ウィジェット。 詳細については、「ロール API - ServiceNow Fluent」を参照してください。
    オプションスキーマ アレイ サービスポータルアドミニストレーター (sp_admin) がウィジェットインスタンスに設定できるパラメーターのリスト。ウィジェットオプションスキーマは、ウィジェットの再利用と、異なるページでのウィジェットのインスタンスの一意の構成をサポートしています。詳細については、「Widget option schema」を参照してください。
    optionSchema: [
  {
    name: 'String',
    label: 'String',
    section: 'String',
    type: 'String',
    defaultValue: 'String',
    hint: 'String'
  },
...
]
    • 名前:必須。パラメーターの名前。
    • label:必須です。ウィジェットインスタンスオプションに表示されるパラメーターのラベル。
    • セクション:必須です。パラメーターが表示されるウィジェットインスタンスオプションのセクション。
      有効な値：
      • データ
      • behavior
      • ドキュメント
      • プレゼンテーション
      • その他
    • タイプ:必須。パラメーターのデータタイプ。
      有効な値：
      • 文字列
      • ブール
      • 整数
      • 参照
      • 選択
      • フィールドリスト
      • fieldName
      • glideList
      • グリフアイコン
    • defaultValue:パラメーターのデフォルト値。
    • hint:パラメーターにカーソルを合わせるとツールヒントとして表示されるパラメーターの簡単な説明。
    公開 ブール 非認証ユーザーがウィジェットを利用できるかどうかを示すフラグ。
    有効な値：
    • true:非認証ユーザーはウィジェットにアクセスできます。
    • false:認証されたユーザーのみがウィジェットにアクセスできます。

    デフォルト値：false
    依存関係 アレイ SPWidgetDependency オブジェクトの変数識別子のリスト、またはウィジェットの依存関係の名前またはsys_ids。詳細については、「SPWidgetDependency オブジェクト」を参照してください。
    angularProvider アレイ SPAngularProvider オブジェクトの変数識別子のリスト、またはウィジェットの Angular プロバイダーの名前またはsys_ids。詳細については、「SPAngularProvider オブジェクト」を参照してください。
    テンプレート アレイ ウィジェットに関連付ける Angular ng テンプレート [sp_ng_template] のリスト。Angular ng テンプレートには、レンダリングを指示した場合にのみレンダリングされるコンテンツが含まれています。
    templates: [
  {
    $id: Now.ID['String' or Number]
    id: 'String'
    htmlTemplate: 'HTML' or `HTML` 
  },
  ...
]
    • $id:必須です。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。

      形式: Now.ID['string' or number]

    • ID:必須。Angular ng テンプレートの ID。
    • htmlTemplate:必須です。HTML テンプレートのコンテンツ。 このプロパティは、HTML またはインライン HTML を含むアプリケーション内の別のファイルへの参照をサポートします。
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    import { SPWidget } from '@servicenow/sdk/core'

SPWidget({
    $id: 'my_simple_widget',
    name: 'My Simple Widget',
    category: 'knowledgeBase',
    clientScript: Now.include('./client.js'),
    serverScript: Now.include('./server.js'),
    controllerAs: '$ctrl',
    customCss: Now.include('./custom_css.css'),
    dataTable: 'sp_instance',
    demoData: { message: 'Hello, World!' },
    description: 'This is a test widget',
    docs: widgetDoc,
    htmlTemplate: Now.include('./template.html'),
    fields: ['color', 'class_name'],
    hasPreview: true,
    id: 'my-simple-widget',
    linkScript: Now.include('./link.client.js'),
    optionSchema: [
        {
            name: 'my_option',
            label: 'My Option',
            type: 'string',
            section: 'behavior'
        }
    ],
    roles: [manager, 'admin'],
})

    SPAngularProvider オブジェクト

    Angular プロバイダー [sp_angular_provider] を作成して、複数のウィジェットでコンポーネントを再利用し、ポータルのパフォーマンスを向上させます。

    表 : 2. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。Angular プロバイダーの名前。
    クライアントスクリプト スクリプト ウィジェットで再利用するクライアント側スクリプト。このプロパティは、インライン JavaScript、またはスクリプトを含むアプリケーション内の別のファイルへの参照をサポートします。
    Format (形式)：
    • 別のファイルのテキストコンテンツを使用するには、 Now.include('path/to/file') の形式を使用してアプリケーション内のファイルを参照します。詳細については、「ServiceNow Fluent 言語構成」を参照してください。
    • インラインスクリプトを指定するには、複数行のコードに文字列リテラルまたはテンプレートリテラルを使用します ( 「スクリプト」または「スクリプト」)。
    タイプ 文字列 Angular プロバイダーのタイプ。
    有効な値：
    • ディレクティブ
    • ファクトリー
    • サービス

    デフォルト:directive
    必要な条件 アレイ 他の SPAngularProvider オブジェクトの変数識別子、または Angular プロバイダーの名前またはsys_idsのリスト。
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    import { SPAngularProvider } from '@servicenow/sdk/core'
const OTHER_ANGULAR_PROVIDER = 'd11f285fe069e1f119b44bd05c0770aa'

SPAngularProvider({
    $id: 'my_angular_provider',
    name: 'my_angular_provider',
    clientScript: Now.include('my_angular_provider.client.js'),
    type: 'directive',
    requires: [OTHER_ANGULAR_PROVIDER]
})

    SPWidgetDependency オブジェクト

    ウィジェットの依存関係 [sp_dependency] を作成して、JavaScript および CSS ファイルをウィジェットにリンクし、サードパーティのライブラリ、外部スタイルシート、または Angular モジュールを使用します。

    依存関係は、必要に応じてサーバーから非同期にロードされます。ウィジェットには、必要な数の依存関係を含めることができます。ただし、追加すればするほど、ウィジェットがページに表示するためにダウンロードする必要があるコンテンツが増えます。ロード時間を短くするため、依存関係はできる限り少なくしてください。詳細については、「Create a widget dependency」を参照してください。

    表 : 3. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。ウィジェット依存関係の名前。
    angularモジュール名 文字列 JS インクルードが Angular モジュールである場合にロードする Angular モジュールの名前。
    includeOnPageLoad ブール 依存関係がページにロードされるタイミングを示すフラグ。
    有効な値：
    • true:依存関係は最初のページロードとともにロードされます。
    • false:依存関係は、リンクされたウィジェットがページにロードされた場合にのみロードされます。

    デフォルト値：false
    cssIncludes アレイ CssInclude オブジェクトの変数識別子または CSS インクルードのsys_idsとその順序のリスト。詳細については、「CssInclude オブジェクト」を参照してください。
    cssIncludes: [
  {
    order: Number,
    include: 'String' or Reference,
  },
  ...
]
    jsIncludes アレイ JsInclude オブジェクトまたは JS インクルードのsys_idsのリスト変数識別子とその順序。詳細については、「JsInclude オブジェクト」を参照してください。
    jsIncludes: [
  {
    order: Number,
    include: 'String' or Reference,
  },
  ...
]
    portalsForPageLoad アレイ ウィジェットの依存関係をロードするポータル [sp_portal] のsys_idsのリスト。空の場合、依存関係はすべてのポータルのページロードに含まれます。
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    import { SPWidgetDependency } from '@servicenow/sdk/core'

SPWidgetDependency({
    $id: 'samplejs',
    name: 'Sample',
    angularModuleName: 'samplejs',
    includeOnPageLoad: true,
    portalsForPageLoad: ['b4572a48262a16df3032b48cef75a853', 'fe12dbbed14bd3f712f0787141c2f656'],
    cssIncludes: [
        {
            order: 100,
            include: localCss,
        },
        {
            order: 200,
            include: '94112ccb0fb3c2ed072b01d3cb401196',
        },
    ],
    jsIncludes: [
        {
            order: 100,
            include: localJs,
        },
        {
            order: 200,
            include: 'f8af18a5e6c71a3702c4f2038b43cf62',
        },
    ],
})

    CssInclude オブジェクト

    CSS インクルード [sp_css_include] を作成して、ウィジェット依存関係内のスタイルシートまたは外部 CSS を参照します。

    表 : 4. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。CSS インクルードの名前。
    URL 文字列 外部 CSS ファイルへの URL。スタイルシートに spCss プロパティが指定されていない場合、このプロパティは必須です。
    spCs 文字列 スタイルシート [sp_css] のsys_id。このプロパティは、外部 CSS ファイルに url プロパティが指定されていない場合に必要です。
    rtlCssUrl 文字列 セッション言語がヘブライ語などの右から左に記述する言語である場合に、ウィジェットの方向をミラーリングするための外部右から左 (RTL) CSS ファイルの URL。詳細については、「Styling for right-to-left languages in portals」を参照してください。
    lazyLoad ブール CSS インクルードのロード方法を示すフラグ。このプロパティは、 spCSS プロパティを使用してスタイルシートを指定する場合にのみ適用されます。
    有効な値：
    • true:CSS インクルードは非同期にロードされ、ページのロード時間を短縮します。
    • false:CSS インクルードは非同期的にロードされません。

    デフォルト値：false
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    import { CssInclude } from '@servicenow/sdk/core'

const localCss = CssInclude({
    $id: '22bcf16da81e2bc0340c53d50d531adf',
    name: 'Sample Styles',
    spCss: '50e3e32aa321b1c7d1945c5f423228bd',
})

    JsInclude オブジェクト

    ウィジェット依存関係内の UI スクリプトまたは外部 JavaScript コードを参照するための JS インクルード [sp_js_include] を作成します。

    表 : 5. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。JS インクルードの名前。
    URL 文字列 外部 JavaScript ファイルへの URL。URL は絶対パスである必要があります。このプロパティは、UI スクリプトに sysUiScript プロパティが指定されていない場合に必要です。
    sysUiScript 文字列 UI スクリプト [sys_ui_script] のsys_id。このプロパティは、外部 JavaScript ファイルに url プロパティが指定されていない場合に必要です。
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    import { JsInclude } from '@servicenow/sdk/core'

const localJs = JsInclude({
    $id: '98239e4eadfac88b01cce7daa23b6fc3',
    name: 'Sample Framework',
    sysUiScript: 'b67af05645f738df1f286bb3e9ecd55f',
})