6.2 UI

以下にUI定義と定義例を示します。UIの詳細については「UI設計」を参照してください。

（表）UI定義

ラベル				デフォルト値	必須	説明
apiVersion:				1.0	Yes	APIバージョン
kind:					Yes	UIの際はuiを指定する
type:					No	UIの際はresourceのみ指定可能
name:					Yes	UI定義の内部名。本YAMLファイルのディレクトリ名を指定
label:					Yes	YAMLファイルの表示名
includes:					No	このYAMLファイルで利用する関連YAMLファイルを記載
	- kind:				Yes	読み込むYAMLファイルの種類
	name:				Yes	読み込むYAMLファイルの内部名
description:					No	詳細説明
editmode:				normal	No	以下を指定できる。 normal: UI内を常に編集できる。 protected: “type”が“edit”のボタンを押さないと編集できない。 readonly:常に読み取り専用
components:					Yes	UIコンポーネント
	- name:				Yes	コンポーネントの内部名
	label:				No	コンポーネントの表示名
	type:				Yes	コンポーネントのタイプを指定する。コンポーネントタイプについては「（表）使用できるコンポーネント」を参照
	(properties):				No	タイプによって異なる。詳細については「（表）Gridのプロパティ」～「（表）buttonのプロパティ」を参照
	children:				No	コンポーネント内に配置する子コンポーネント
		- name:			No
		(others):			No
	(action):				No	コンポーネント内で実行するアクションを定義する。アクションについては「Script」を参照
buttons:					No	アクションボタンを定義
	- type:				Yes	標準で用意されたものか、ユーザーが独自に設定したものを指定する。タイプについては「（表）アクションボタンのタイプ」を参照
	name:				No	ボタンの内部的な名前
	label:				No	ボタンの表示名
	description:				No	ボタンの説明
	action:				No	“custom”タイプのボタンを押した時に実行されるアクションを指定する。“custom”タイプ以外の場合は、指定しないこと。詳細は「Script」を参照
	order:				No	ボタンの表示順序を決めるための値を設定する。昇順で表示される。
	tables:				No	“load”ボタンで表示されるテーブルリストを定義する。
		- table:			No	カスタムテーブルのテーブル名を指定する。 “load”ボタンで使用される。 “components”セクションで定義されていないカラムを取得する際に指定する。ソートすることはできません。
		fields:			No	カスタムテーブルから取得するカラムを定義。“load”ボタンで使用される。“components”セクションで定義されているカラムに加えて、次項の“field”で定義されている列を取得する。
			- field:		No	取得するカラム名
action:					No	UIで実行されるアクションを定義する。詳細は「Script」を参照

（表）アクションボタンのタイプ

タイプ	説明
start	ワークフローを開始する。
save	現在のレコードを保存する。
cancel	レコードの編集を破棄して前の画面に戻る。
load	過去のレコード一覧を開き、選択したレコードの選択したカラムの値を現在のフォームにコピーする。ダイアログに表示されるレコードは現在の画面に関連するレコードである。ワークフロー一覧とカスタムテーブルが対象です。
accept	core.ask アクションに {oi_response: "accept"}で応答する。ワークフローを次に進める場合に使用する。
reject	core.ask アクションに {oi_response: "reject"}で応答する。ワークフローを元に戻す場合に使用する。
complete	core.ask アクションに {oi_response: "complete"}で応答する。ワークフローを完了する場合に使用する。
custom	ユーザーが独自に設定するボタン。action項目に設定するスクリプトを実行する。
edit	“editmode”が“protected”に指定されているUIのフォームの編集可否を変更する。

core.askアクションにaccept、reject、completeのアクションボタンを用いて応答する場合、以下のようにTask modelのinputにschemaを追加し、応答の構造を指定する必要があります。

    input:
      schema:
        type: object
        properties:
          oi_response:
            type: string
            required: true

Task modelについては「Workflow」を参照してください。

UI定義ではReactとMaterial-UIを用いて画面を構成します。画面を構成する際のレイアウトは下図のようにGridやPaperなどを用いて階層構造になるように構成します。

（図）ReactとMaterial-UIを用いた画面構成の概念図

以下にUI定義内で使用できるコンポーネントとそのプロパティを示します。

（表）使用できるコンポーネント

コンポーネント	Material-UI	説明
Grid	Grid	UIのグリッド。詳細は以下参照 https://mui.com/components/grid/#main-content
Paper	Paper	Material-UIのPaperコンポーネント。コンテンツが紙の上に載っているようにする。詳細は以下を参照 https://mui.com/components/paper/
Form	TextField、 Checkbox、 Select	指定したテーブルのレコードの内容の表示、編集を行う。詳細は以下を参照 https://mui.com/components/text-fields/#main-content https://mui.com/components/checkboxes/#main-content https://mui.com/components/selects/#main-content
Table	DataGrid	Material-UIのDataGridコンポーネント。詳細は以下を参照 https://material-ui.com/components/data-grid/ 指定したテーブルのレコード一覧をリスト表示する。
Button	Button	各コンポーネントに対してアクションを定義して実行する。
Stepper	Stepper	Material-UIのStepperコンポーネント。ステップを表示する。

（表）Gridのプロパティ

ラベル			デフォルト値	必須	説明
components:				Yes	UIコンポーネント
	type:			Yes	“grid”を指定する。グリッドを調節することができる。詳細は以下を参照 https://material-ui.com/components/data-grid/
	breakpoint:			Yes	このコンポーネントのブレークポイントを設定する。
		xs:		No
		sm:		No
		md:		No
		lg:		No
		xl:		No
	isCon:		false	No	Trueを指定した場合、Grid ContainerとしてGridを定義する。この配下のGridコンポーネントをレイアウトして配置する際に指定する。

（表）Paperのプロパティ

ラベル		必須	説明
components:		Yes	UIコンポーネント
	type:	Yes	“paper”を指定する。詳細は以下を参照 https://material-ui.com/components/paper/
	icon:	No	Paperのラベルのアイコンを指定する。以下のMaterial iconsから指定できる。 https://material-ui.com/components/material-icons/ 例） AccountBalance
	tabs:	No	Paperの下にタブを追加する。Tabコンポーネントと同様にパラメータを設定できる。Toggleスタイルのみサポートされている。

（表）Formのプロパティ

ラベル						デフォルト値	必須	説明
components:							Yes	UIコンポーネント
	type:						Yes	formを指定する。レコードの表示、編集を行う。
	autorefresh:						Yes	データベースの更新を監視する間隔（秒）。 0（秒）を必ず指定する。
	source:						Yes	データソース。カスタムテーブルが指定可能
		tables:					No	表示するレコードのテーブルを指定する。
			- table:				Yes	参照されるテーブルを指定する。参照されるテーブルは、“includes”で指定されたドキュメントに含まれている必要がある。
		apis:					No	APIで取得した情報を参照する場合に利用する。利用するAPIは“includes”セクションで指定する必要がある。
			- <CRUD>:				Yes	利用するAPIのCRUDを指定する。 “read”のみ利用可能。
				name:			Yes	API名を指定する。 “itsm:otobo:searchCustomers”のみ利用可能。 “itsm:otobo:searchCustomers”を指定した場合は“includes”で以下の記載が必要。・kind: api ・name: opsi
	fields:						Yes	Formのフィールドを指定する。ここで定義した順に表示される。
		- type:					Yes	“table”を指定する。
		field:					Yes	カラム名を指定する。テーブル名とカラムは<table>.<column>の書式で指定する。
		label:					Yes	Form上での表示名を指定する。
		displayName:					“type”に” table”が指定されDatamodelで” ref-sys”が設定されている場合は必須。それ以外は任意	表示する値。検索に使用する。表示するカラム名を指定する。その際は<ref-sys table name>.<ref-sys column name>の書式で指定する。例） typeが“table”かつ、“ref-sys”が設定されている場合 displayName: user.name
		properties:					No	object array内のフィールド属性を設定する。“readOnly”、"required" を設定。例） properties: readOnly: false
			readOnly:			false	No	“true” または “false”を設定する。 “true”を設定した場合、当該フィールドの値は変更不可となる。
			required:			false	No	“true” または “false”を設定する。 “true”を設定した場合、当該フィールドの入力は必須となり、値が設定されていない状態で保存するとエラーが表示される。
		validation:					No	入力チェックルール
			regex:				No	テキストの正規表現を設定する。カラムのタイプが“varchar”、“text”の場合に使用可能。カラムタイプについては「（表）カラムのタイプ」を参照。
			min:				No	最小値を設定する。カラムのタイプが“integer”、“numeric”、“varchar”、“text”の場合に使用可能。カラムタイプについては「（表）カラムのタイプ」を参照。以下のカラムのタイプが設定されている場合、数値の大小で評価する。・“integer” ・“numeric” 以下のカラムのタイプが設定されている場合、文字数で評価する。・“varchar” ・“text”
			max:				No	最大値を設定する。カラムのタイプが“integer”、“numeric”、“varchar”、“text”の場合に使用可能。以下のカラムのタイプが設定されている場合、数値の大小で評価する。・“integer” ・“numeric” 以下のカラムのタイプが設定されている場合、文字数で評価する。・“varchar” ・“text”
			message:				No	入力チェックエラー時に表示するメッセージ例） Invalid e-mail address.
		load:				true	No	“load” ボタンを利用してコピーする際に、対象カラムとするかどうかを選択する。 true:コピー対象 false：コピー対象外
		lookup:					No	lookupが指定されるとルックアップフィールドとして扱われる。指定されたフィールドがドキュメントに関連している場合、指定されたフォルダパスまたはファイル名から選択肢が表示される。
			type:				Yes	下記のタイプが設定可能 “table” 、“api”
			filter:				No	フィルタリングコンディションを設定する。タイプが“table”の場合で指定されたフィールドがドキュメントに関連している場合、表示されるレコードをフィルタする。
				-			No
					- operator:		Yes	このコンディションの条件演算子。下記が使用可能 - eq, ne (==,!=) - in, notIn^※1 firstOperandで指定したFieldの値がsecondOperandで指定したリスト（“,”区切り）の要素に含まれるかどうか判断する。条件演算子はfirstOperandとsecondOperandの値を文字列形式で比較します。
					firstOperand:		Yes	比較の1番目のターゲット。テーブルのフィールド名を指定する。例）role.id タイプが“table”の場合、ドキュメントのパスでも指定可能。指定されたフォルダは以下のすべてのファイルが判定される。例） /myGroup/myRepository/MyDocPath
					secondOperand:		Yes	比較の2番目のターゲット。firstOperandと演算子の値を指定する。テンプレート定義を利用可能。使用できるテンプレート定義については「（表）使用可能なテンプレート定義」を参照。 operatorでin/notInを利用してテンプレートを利用しない場合は、“,”区切りのstringでリストを記載する。例）テンプレート定義を使用しない場合 “Service Desk Agent” タイプが“table”でテンプレート定義を使用する場合 ‘{{ .GetValue ".Requester.Customer" }}’ operatorでin/notInを利用してテンプレートを利用しない場合 groupA,groupB,groupC
			field:				Yes	参照テーブルのフィールド名。 typeが“table”の場合、カラム名を指定する。テーブル名とカラムは<table>.<column>の書式で指定する。例） group.id typeが“api”の場合、プロパティ名を指定する。プロパティ名は<api>.<property>の書式で指定する。指定できるのは以下のいずれかのみ・“itsm:otobo:searchCustomers.id” （顧客のID）・“itsm:otobo:searchCustomers.name” （顧客名）
			searchQuery:				No	オートコンプリートを利用するためのクエリパラメータを設定する。タイプが“api”の場合に利用し、“name”のみ指定可能。指定した場合、ルックアップフィールドの選択肢が表示される。
			displayColumn:				No	lookupで選択肢として表示されるカラムを<table name>.<column name>で指定する。テーブルの定義方法と詳細については「Datamodel」を参照。（例） user.id user.username タイプが“api”の場合、lookupで選択肢として表示されるプロパティを指定する。指定できるのは以下のいずれかのみ・“itsm:otobo:searchCustomers.id” （顧客のID）・“itsm:otobo:searchCustomers.name” （顧客名）指定しない場合はすべてのプロパティが表示される。例） displayColumn: - user.name - user.role - user.group

※1：この条件演算子を指定する場合は、テンプレート定義を利用してください。

（表）Tableのプロパティ

ラベル				デフォルト値	必須	説明
components:					Yes	UIコンポーネント
	type:				Yes	“table”を指定する。指定したテーブルのレコード一覧をリスト表示する。
	source:				Yes	データソース。カスタムテーブルを指定する。利用するテーブルは“includes”セクションで指定されている必要がある。
		table:			No	テーブル名を指定する。
	autorefresh:			5	No	データベースの更新を監視する間隔（秒）を指定する。データベースが更新された場合は、コンポーネントをリロードする。 0（秒）を指定すると、自動更新はされない。
	selection:				No	“checkbox”もしくは“radio”を指定する。指定した場合、チェックボックスまたはラジオボタンが追加される。 ※ラジオボタンは、単一指定のチェックボックス形式となります。
	toolbar:			false	No	“true”の場合、テーブルにツールバーを追加する。
	columns:				No	テーブルのカラムを指定する。ここで定義した順に表示される。
		- column:			Yes	テーブルのフィールド名を指定する。書式は以下とする。 “table”: <table name>.<column name>
		label:			No	カラムの表示名を指定する。
		editable:		false	No	編集可能かどうかを設定する。 true : 編集可能 false : 編集不可データベースへ変更を反映するには、保存アクションを実行する必要がある。
		sortable:		false	No	ソート可能かどうかを設定する。 true : ソート可能 false : ソート不可
		hide:		false	No	カラムを非表示にするかどうかを指定する。 “true”を指定した場合、非表示になる。
		type:		auto	No	カラムの表示形式。以下を指定できる。 “auto” “chip” “attachment” 詳細は「（表）Tableのカラムタイプ」を参照
		properties:			No	プロパティを設定する。現在は“chip”タイプにのみ使用できる。 “chip”タイプの場合、propertiesを設定していないとエラー（An error occurred）が表示される。
			color:	primary	No	以下のcolor prop を指定できる。デフォルトはprimary https://mui.com/components/chips/#color-chip
			variant:	filled	No	以下を指定できる。 “filled”: 塗りつぶし “outlined”: 外枠
		attachment:			No	attachmentを指定していた場合、添付ファイルを指定する。
			kind:		Yes	ドキュメントの種類を指定する。
			name:		Yes	ドキュメントの名前を指定する。

（表）Tableのカラムタイプ

カラムタイプ	説明
auto	Datamodelの指定されたカラムに沿って設定される。
chip	チップをカラムの値とともに表示する。詳細は以下を参照。 https://mui.com/components/chips/
attachment	レコードにファイルを添付する。

（表）buttonのプロパティ

ラベル			必須	説明
components:			Yes	UIコンポーネント
	type:		Yes	“button”を指定する。コンポーネントごとに定義されるアクションを実行する。グリッドの右端に配置される。
	buttons:		Yes	ボタンの詳細を設定する。
		- name:	Yes	ボタンの名前
		label:	No	ボタンの表示名
		action:	Yes	ボタンを押した時に実行されるアクションを指定する。詳細は「Script」を参照

（表）Stepperのプロパティ

ラベル		デフォルト値	必須	説明
components:			Yes	UIコンポーネント
	type:		Yes	“stepper”を指定する。ワークフロー画面にのみ配置が可能。
	maxDepth:	3	No	サブフローの階層数
	maxIndentDepth:	3	No	サブフローの階層ごとのインデント数
	indentRem:	1.5	No	インデント単位。詳細は以下を参照。 https://www.w3.org/TR/css-values-3/#rem
	stepWidthRem:		No	各ステップの幅
	collapsed:	false	No	サブフロータスクの初期表示設定 true:サブフロータスクを折りたたむ false:サブフロータスクを開く
	sx:		No	Material-UIのsxプロパティに基づいて指定可能。詳細は以下を参照。 https://mui.com/system/getting-started/the-sx-prop/ 例）高さの調整 sx: maxHeight: 35rem
	targetSteps:		No	表示されるステップのリスト。指定された名前でステップをフィルタ表示する。この属性が指定されていない場合、ワークフローで定義されているすべてのステップが表示される。例: 以下の場合、# step2 は表示されない - step1 # - step2 - step3

（表）使用可能なテンプレート定義

テンプレート	説明
{{ .GetValue ".Requester.Customer" }}	同じ名前のユーザーがOTOBOで顧客ユーザーとして登録されている場合、顧客ユーザーが属するOTOBOのID
{{ .GetValue ".Requester.Groups" }}	ユーザーが属するグループIDの一覧 "," で区切られた文字列によって/users/{id} の応答 assignedGroups.id を返す。
{{ .GetValue ".Requester.Roles" }}	ユーザーが持っているロールIDの一覧 "," で区切られた文字列によって/users/{id} の応答 effectiveRoles.id を返す。

＜定義例＞

apiVersion: 1.0
kind: ui
type: resource
name: create_vm_ui_01
label: create_vm_ui_01
description: 申請画面のYAML定義です
includes:
- kind: datamodel
name: lend_vm_datamodel

components:
  - name: lend_vm_grid
    label: grid
    type: grid
    breakpoint:
      xs: 12
    children:
      - name: lend_vm_paper
        label: 申請フォーム
        type: paper
        icon: Assignment
        children:
          - name: lend_vm_form
            label: 申請フォーム
            type: form
            autorefresh: 0
            source:
              tables:
                - table: lend_vm_table
            fields:
              - field: lend_vm_table.app_number
                label: 申請番号
                type: table
                properties:
                 readOnly: true
                 required: false

              - field: lend_vm_table.sys_name
                label: システム名
                type: table
                properties:
                 readOnly: false
                 required: true

（中省略）

              - field: lend_vm_table.cpu
                label: CPU（コア数）
                type: table
                properties:
                 readOnly: false
                 required: true
                validation:
                  min: 4
                  max: 128
                message: 4~128の整数値を入力してください。

              - field: lend_vm_table.memory
                label: メモリ（GB）
                type: table
                properties:
                 readOnly: false
                 required: true
                validation:
                  min: 32
                  max: 256
                message: 32~256の整数値を入力してください。

              - field: lend_vm_table.storage
                label: ストレージ（GB）
                type: table
                properties:
                 readOnly: false
                 required: true
                validation:
                  min: 10
                  max: 4096
                message: 10~4096の整数値を入力してください。

              - field: lend_vm_table.created_by
                label: 利用申請者
                type: table
                properties:
                 readOnly: true
                 required: false

              - field: lend_vm_table.start_date
                label: 利用開始日
                type: table
                properties:
                 readOnly: false
                 required: true

              - field: lend_vm_table.message
                label: 申し送り事項
                type: table
                properties:
                 readOnly: false
                 required: false

buttons:
  - type: start
    name: start
    label: 申請
  - type: cancel
    name: cancel
    label: キャンセル

似たセクションが続く箇所は（中省略）として省略しています。