チュートリアル：データモデルエンティティとその API リソースの拡張
このチュートリアルでは、Postman を使用する環境を設定し、適切なサンプルデータセットを用意していることを前提としています。詳細については、チュートリアル：Postman 環境のセットアップを参照してください。
このチュートリアルでは、フィールドを追加してベースコンフィギュレーションのデータモデルエンティティを拡張します。その後、拡張フィールドごとに関連付けられた一連のプロパティを使用して、対応する API リソースをコンフィギュレーションします。データモデル拡張は Guidewire Studio を通じて行います。このチュートリアルでは、Studio の操作に習熟していることを前提としています。
シナリオ
あなたは、Common API で Activity リソースのリソース拡張を作成するよう求められています。このリソースは、ClaimCenter Activity エンティティに基づいています。あなたは、次のエンティティフィールドをサポートするようリソースプロパティを拡張しようとしています。
| エンティティフィールド名 | リソースプロパティ名 | 値の型 | POST および PATCH をサポートしているか |
ActivityClass |
activityClass_Ext |
ActivityClass タイプリストへのタイプキー |
|
CreateTime |
createTime_Ext |
日時 | |
CreateUser |
createUser_Ext |
User エンティティへの外部キー |
|
ShortSubject |
shortSubject_Ext |
varchar(10) | はい |
IsAutogenerated_Ext（ユーザー作成のフィールド拡張） |
isAutogenerated_Ext |
ビット | はい |
最後のエントリが、カスタムエンティティフィールド拡張であることに注意してください。まず、Studio でこのフィールドを作成します。次に、リソース、マッピング、およびアップデータ拡張をコンフィギュレーションし、システム API を通じてこれらのプロパティを使用できるようにします。最後に、Swagger UI と Postman でリソース拡張を検証します。
エンティティフィールド拡張の作成
システム API を通じてカスタムエンティティ拡張にアクセスできるようにするには、まずその拡張を作成します。次の操作で、カスタムエンティティ拡張を作成できます。
- Studio で、編集する Activity エンティティを開きます。このファイルは、Project > configuration > config > Extensions > Entity > Activity.etx にあります。
- ［+］ をクリックして、［列］ を選択します。
- 新しい列で、以下の名前と値のペアを入力します。
- ［名前］ フィールドに「IsAutogenerated_Ext」と入力します。
- ［型］ フィールドに「bit」と入力します。
- ［NullOk］ フィールドに「true」と入力します。
- ファイルを保存します。
- 変更を連携させるには、［実行］＞［Debug 'Server'］を選択して、開発サーバーをデバッグモードで起動します。
- 作業を検証するには、ClaimCenter のデータディクショナリを再生成してから、ディクショナリでこの拡張の存在を確認します。
スキーマの拡張
- Studio で、Common API と関連付けられているスキーマ拡張ファイルを開きます。
このファイルは、Integration > schemas > ext > common > v1 > common_ext-1.0.schema.json にあります。
{ "$schema": "http://json-schema.org/draft-04/schema#", "x-gw-combine": [ "gw.content.cc.common.v1.common_content-1.0", "ext.framework.v1.framework_ext-1.0" ], "definitions": {} } } - 定義フィールドで
Activityのスキーマ定義拡張を作成し、これにproperties属性を追加します。{ . . . "definitions": { "Activity": { "properties": {} } } } - 前出の「シナリオ」セクションで概要を示したように、
properties属性内で、拡張するリソースプロパティごとにフィールドを作成します。{ . . . "definitions": { "Activity": { "properties": { "activityClass_Ext": {}, "createTime_Ext": {}, "createUser_Ext": {}, "shortSubject_Ext": {}, "isAutogenerated_Ext": {} } } } } activityClass_Extプロパティフィールド内で、タイプキーのプロパティ値の型を追加します。タイプキーの型は、URI 参照によってスキーマで定義されます。プロパティ値の型を設定するには、
$ref属性を入力して、#/definitions/TypeKeyReferenceの値をアサインします。さらに、タイプキーをタイプリストと関連付ける必要があります。タイプリストを設定するには、プロパティに
x-gw-extensions属性を追加してから、タイプリストフィールドに適切なタイプリストをアサインします。この例では、タイプリストはActivityClassです。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "definitions": { "Activity": { "properties": { "activityClass_Ext": { "$ref": "#/definitions/TypeKeyReference", "x-gw-extensions": { "typelist": "ActivityClass" } }, . . . } } } }createTime_Extプロパティフィールドで、日時のプロパティ値の型を追加します。プロパティ値の型を設定するには、type 属性を入力して、string の値をアサインします。次に、format 属性を追加して、
date-timeの値をアサインします。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "definitions": { "Activity": { "properties": { . . . "createTime_Ext": { "type": "string", "format": "date-time" }, . . . } } } }createUser_Extプロパティフィールドで、オブジェクトのプロパティ値の型を追加します。リソースプロパティに
$ref属性を追加して、インラインリソースの URI 参照をアサインすることで、オブジェクトのプロパティ値の型を宣言します（詳細については、本書の「attributes セクション」を参照してください）。この例では、$ref属性を入力して、#/definitions/SimpleReferenceの値をアサインします。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "definitions": { "Activity": { "properties": { . . . "createUser_Ext": { "$ref": "#/definitions/SimpleReference" }, . . . } } } }shortSubject_Extプロパティフィールドで、文字列のプロパティ値の型を追加します。プロパティ値の型を設定するには、type 属性を入力して、
stringの値をアサインします。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "definitions": { "Activity": { "properties": { . . . "shortSubject_Ext": { "type": "string" }, . . . } } } }isAutogenerated_Extプロパティフィールドで、ビットのプロパティ値の型を追加します。プロパティ値の型を設定するには、type 属性を入力して、
booleanの値をアサインします。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "definitions": { "Activity": { "properties": { . . . "isAutogenerated_Ext": { "type": "boolean" } } } } }- 変更を保存します。
マッパーの拡張
- Studio で、Common API と関連付けられているマッパー拡張ファイルを開きます。
このファイルは、Integration > mappings > ext > common > v1 > common_ext-1.0.mapping.json にあります。
ベースファイルは次のようになります。
{ "schemaName": "ext.common.v1.common_ext-1.0", "combine": [ "gw.content.cc.common.v1.common_content-1.0", "ext.framework.v1.framework_ext-1.0" ], "mappers": {} } mappersフィールドで、Activityのマッパー拡張を作成します。{ . . . "mappers": { "Activity": {} } }Activityマッパー拡張で、schemaDefinitionプロパティを追加してActivityの値を付与します。これにより、マッパーとActivityリソースが関連付けられます。{ . . . "mappers": { "Activity": { "schemaDefinition": "Activity" } } }- root プロパティを追加して、
entity.Activityの値を付与します。これにより、Activityリソースと ClaimCenterActivityエンティティが関連付けられます。{ . . . "mappers": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity" } } } propertiesプロパティを追加し、その中で、先ほどスキーマ定義拡張に追加したプロパティごとにフィールドを作成します。{ . . . "mappers": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { "activityClass_Ext": {}, "createTime_Ext": {}, "createUser_Ext": {}, "shortSubject_Ext": {}, "isAutogenerated_Ext": {} } } } }activityClass_Extプロパティをコンフィギュレーションします。- path 属性を追加して、
Activity.ActivityClassの値をアサインします。これにより、リソースプロパティが
ActivityClassエンティティフィールドにマッピングされます。 mapper属性を追加して、#/mappers/TypeKeyReferenceの値をアサインします。URI 参照で型を宣言したすべてのプロパティに、関連するマッパースキーマの URI 参照へのマッピングセットを含める必要があります。
次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "mappers": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { "activityClass_Ext": { "path": "Activity.ActivityClass", "mapper": "#/mappers/TypeKeyReference" }, . . . } } } }- path 属性を追加して、
createTime_Extプロパティで、path 属性を追加してActivity.CreateTimeの値をアサインします。これにより、リソースプロパティが
CreateTimeエンティティフィールドにマッピングされます。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "mappers": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { . . . "createTime_Ext": { "path": "Activity.CreateTime" }, . . . } } } }createUser_Extプロパティをコンフィギュレーションします。path属性を追加して、Activity.CreateUserの値をアサインします。これにより、リソースプロパティが
CreateUserエンティティフィールドにマッピングされます。mapper属性を追加して、#/mappers/SimpleReferenceの値をアサインします。URI 参照で型を宣言したすべてのプロパティに、関連するマッパースキーマの URI 参照へのマッピングセットを含める必要があります。
次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "mappers": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { . . . "createUser_Ext": { "path": "Activity.CreateUser", "mapper": "#/mappers/SimpleReference" }, . . . } } } }shortSubject_Extプロパティで、path 属性を追加してActivity.ShortSubjectの値をアサインします。これにより、リソースプロパティが
ShortSubjectエンティティフィールドにマッピングされます。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "mappers": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { . . . "shortSubject_Ext": { "path": "Activity.ShortSubject" }, . . . } } } }isAutogenerated_Extプロパティで、path属性を追加してActivity.IsAutogenerated_Extの値をアサインします。これにより、リソースプロパティが
isAutogenerated_Extエンティティフィールドにマッピングされます。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "mappers": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { . . . "isAutogenerated_Ext": { "path": "Activity.IsAutogenerated_Ext" } } } } }- 変更を保存します。
アップデータの拡張
アップデータの場合は、POST または PATCH 操作で更新できるリソースプロパティを追加するだけで済みます。リソース拡張にそうしたプロパティが含まれていない場合、アップデータ拡張を作成する必要はありません。
isAutogenerated_Ext プロパティの POST または PATCH 操作をサポートするアップデータを作成するには、次の手順に従います。
- Studio で、Common API と関連付けられているアップデータ拡張ファイルを開きます。
このファイルは、Integration > updaters > ext > common > v1 > common_ext-1.0.updater.json にあります。
ベースファイルは次のようになります。
{ "schemaName": "ext.common.v1.common_ext-1.0", "combine": [ "gw.content.cc.common.v1.common_content-1.0", "ext.framework.v1.framework_ext-1.0" ], "updaters": {} } updatersフィールドで、Activityのアップデータ拡張を作成します。{ . . . "updaters": { "Activity": {} } }Activityアップデータ拡張で、schemaDefinitionプロパティを追加してActivityの値を付与します。これにより、アップデータと Activity リソースが関連付けられます。
{ . . . "updaters": { "Activity": { "schemaDefinition": "Activity" } } }rootプロパティを追加して、entity.Activityの値を付与します。これにより、
Activityリソースと ClaimCenterActivityエンティティが関連付けられます。{ . . . "updaters": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity" } } }propertiesプロパティを追加し、その中で、スキーマ定義拡張の定義に従ってサポートされているプロパティごとにフィールドを作成します。{ . . . "updaters": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { "shortSubject_Ext": {}, "isAutogenerated_Ext": {} } } } }isAutogenerated_Extプロパティで、path属性を追加してActivity.IsAutogenerated_Extの値をアサインします。これにより、リソースプロパティが
IsAutogenerated_Extエンティティフィールドにマッピングされ、InsuranceSuite データベースにプロパティデータを書き込めるようになります。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "updaters": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { "isAutogenerated_Ext": { "path": "Activity.IsAutogenerated_Ext" }, . . . } } } }shortSubject_Extプロパティで、path属性を追加してActivity.ShortSubjectの値をアサインします。これにより、リソースプロパティが
ShortSubjectエンティティフィールドにマッピングされ、InsuranceSuite データベースにプロパティデータを書き込めるようになります。次のコードブロックは、完了したプロパティフィールドを示しています。
{ . . . "updaters": { "Activity": { "schemaDefinition": "Activity", "root": "entity.Activity", "properties": { . . . "shortSubject_Ext": { "path": "Activity.ShortSubject" } } } } }- 変更を保存します。
拡張リソースの検証
スキーマ定義拡張を作成後、Swagger UI で変更したスキーマ定義を確認できます。
- Swagger UI を起動して、Common API を読み込みます。
- GET
/common/v1/activities/{activityId}エンドポイントを選択します。 - ［応答］ の下にある ［モデル］ ビューを選択します。
data.attributesセクションと関連付けられているActivityスキーマで、拡張プロパティの存在を確認します。
さらに、Postman とサンプルデータを使用して、変更したスキーマ定義のテスト運用ができます。このチュートリアルでは、Postman を使用する環境を設定し、適切なサンプルデータセットを用意していることを前提としています。詳細については、『Cloud API ビジネスフローと設定ガイド』を参照してください。
まず、リソースプロパティ拡張に対する GET 操作の応答オブジェクトを確認できます。
- Postman で、［Launchpad］タブの右側の［+］をクリックして、新しい要求を開始します。
- ユーザー名
aapplegateとパスワードgwを使用して Basic Auth 認証を指定します。 - 次の呼び出しを入力して、［送信］をクリックします。
GET
http://localhost:8080/cc/rest/common/v1/activites/cc:201 - 応答の本文を確認します。次のようになります。
{ "data": { "attributes": { "activityClass_Ext": { "code": "task", "name": "Task" }, "activityPattern": "vendor_did_not_accept_work", "activityType": { "code": "general", "name": "General" }, "assignedByUser": { "displayName": "System User", "id": "systemTables:2" }, "assignedGroup": { "displayName": "Auto1 - TeamA", "id": "demo_sample:31" }, "assignedUser": { "displayName": "Andy Applegate", "id": "demo_sample:1" }, "assignmentStatus": { "code": "assigned", "name": "Assigned" }, "createTime_Ext": "2020-06-04T22:10:00.091Z", "createUser_Ext": { "displayName": "System User", "id": "systemTables:2" }, "description": "Follow up with vendor - work not accepted in timely manner", "dueDate": "2020-06-05T22:10:00.035Z", "escalated": false, "externallyOwned": false, "id": "cc:201", "importance": { "code": "high", "name": "High" }, "mandatory": false, "priority": { "code": "high", "name": "High" }, "recurring": false, "status": { "code": "open", "name": "Open" }, "subject": "Follow up with vendor - work not accepted in timely manner" }, . . . } } }
同じリソースに PATCH 操作を実行して、アップデータをテストできます。
- Postman で、［Launchpad］タブの右側の［+］をクリックして、新しい要求を開始します。
- ユーザー名
aapplegateとパスワードgwを使用して Basic Auth 認証を指定します。 - 次の呼び出しを入力しますが、［送信］はクリックしません。
PATCH
http://localhost:8080/cc/rest/common/v1/activites/cc:201 - 要求ペイロードを指定します。
- タブの先頭行（［パラメータ］で始まる行）で、［本文］をクリックします。
- ラジオボタンの行で［raw］を選択します。
- ラジオボタンの行の末尾で、ドロップダウンリストの値を［テキスト］から［JSON］に変更します。
- 以下を、ラジオボタンの下のテキストフィールドに貼り付けます。
{ "data": { "attributes": { "isAutogenerated_Ext": true, "shortSubject_Ext": "shortsub" } } }
- ［送信］をクリックします。応答ペイロードが要求ペイロードの下に表示されます。
{ "data": { "attributes": { "activityClass_Ext": { "code": "task", "name": "Task" }, "activityPattern": "vendor_did_not_accept_work", "activityType": { "code": "general", "name": "General" }, "assignedByUser": { "displayName": "System User", "id": "systemTables:2" }, "assignedGroup": { "displayName": "Auto1 - TeamA", "id": "demo_sample:31" }, "assignedUser": { "displayName": "Andy Applegate", "id": "demo_sample:1" }, "assignmentStatus": { "code": "assigned", "name": "Assigned" }, "createTime_Ext": "2020-06-04T22:10:00.091Z", "createUser_Ext": { "displayName": "System User", "id": "systemTables:2" }, "description": "Follow up with vendor - work not accepted in timely manner", "dueDate": "2020-06-05T22:10:00.035Z", "escalated": false, "externallyOwned": false, "id": "cc:201", "importance": { "code": "high", "name": "High" }, "isAutogenerated_Ext": true, "mandatory": false, "priority": { "code": "high", "name": "High" }, "recurring": false, "shortSubject_Ext": "shortsub", "status": { "code": "open", "name": "Open" }, "subject": "Follow up with vendor - work not accepted in timely manner" }, . . . } }