Lernprogramm: Ressourcen-Erweiterung erstellen

Werkzeuge

Im Rahmen dieser Übung werden Sie Studio, Swagger UI und Postman nutzen. In diesem Lernprogramm wird davon ausgegangen, dass Sie mit der Arbeit in Studio bereits vertraut sind. Weitere Informationen zur Swagger UI oder zum Einrichten von Postman finden Sie im Cloud-API-Geschäftsabläufe- und Konfigurationshandbuch.

Szenario

Sie wurden aufgefordert, eine Ressourcenerweiterung für die Activity-Ressource in der Common API zu erstellen. Diese Ressource basiert auf der ClaimCenter Activity-Entität. Sie werden die Ressourceneigenschaften so erweitern, dass die folgenden Entitätsfelder unterstützt werden:

Beachten Sie, dass der letzte Eintrag eine Erweiterung für benutzerdefinierte Entitätsfelder ist. Sie erstellen dieses Feld zunächst in Studio. Anschließend konfigurieren Sie die Ressourcen-, Mapping- und Updater-Erweiterungen, um diese Eigenschaften über die System-API verfügbar zu machen. Abschließend verifizieren Sie die Ressourcenerweiterung in Swagger UI und Postman.

Eine Entitätsfelderweiterung erstellen

Damit über eine System-API auf eine benutzerdefinierte Entitätserweiterung zugegriffen werden kann, muss diese Erweiterung zuerst vorhanden sein. Sie können eine benutzerdefinierte Entitätserweiterung wie folgt erstellen:

1. Öffnen Sie in Studio die Activity-Entität zur Bearbeitung. Diese Datei finden Sie unter Project > configuration > config > Extensions > Entity > Activity.etx.
2. Klicken Sie auf + und wählen Sie column aus.
3. Geben Sie in der neuen Spalte die folgenden Paare, bestehend aus Namen und Wert, ein:
4. Geben Sie im Feld name den Wert IsAutogenerated_Ext ein
5. Geben Sie im Feld type den Wert bit ein
6. Geben Sie im Feld nullok den Wert true ein
7. Speichern Sie die Datei.
8. Um Ihre Änderungen zu integrieren, starten Sie den Entwicklungsserver im Debugging-Modus, indem Sie Ausführen > „Server“ debuggen auswählen.
9. Um Ihre Arbeit zu überprüfen, erstellen Sie das Datenwörterbuch für ClaimCenter neu und bestätigen Sie dann, dass diese Erweiterung im Wörterbuch vorhanden ist.

Schemadefinition erweitern

1. Öffnen Sie in Studio die der Common API zugeordneten Schemaerweiterungsdatei.

   Diese Datei befindet sich unter 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": {}
     }
   }

2. Erstellen Sie im Definitionsfeld eine Schemadefinitionserweiterung für Activity und fügen Sie diesem ein properties-Attribut hinzu.

   {
     . . .
     "definitions": {
       "Activity": {
         "properties": {}
       }
     }
   }

3. Erstellen Sie innerhalb des Attributs properties Felder für jede der zu erweiternden Ressourceneigenschaften, wie im Abschnitt „Szenario“ oben beschrieben.

   {
     . . .
     "definitions": {
       "Activity": {
         "properties": {
           "activityClass_Ext": {},
           "createTime_Ext": {},
           "createUser_Ext": {},
           "shortSubject_Ext": {},
           "isAutogenerated_Ext": {}
         }
       }
     }
   }

   Hinweise zu Namenskonventionen für Eigenschaften finden Sie im Abschnitt „Eigenschaftennamen“ von Erweiterungssyntax für Schemadefinitionen.

4. Fügen Sie im Eigenschaftenfeld activityClass_Ext einen Eigenschaftswertetyp für Typenschlüssel hinzu.

   Der Typenschlüsseltyp ist im Schema durch eine URI-Referenz definiert. Um den Wertetyp der Eigenschaft festzulegen, geben Sie ein $ref-Attribut ein und weisen ihm den Wert #/definitions/TypeKeyReference zu.

   Darüber hinaus muss der Typenschlüssel mit einer Typenliste verknüpft sein. Um die Typenliste festzulegen, fügen Sie der Eigenschaft ein x-gw-extensions-Attribut hinzu und weisen Sie dann dem Typenlistenfeld die entsprechende Typenliste zu. In diesen Beispiel heißt die Typenliste ActivityClass.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "definitions": {
       "Activity": {
         "properties": {
           "activityClass_Ext": {
             "$ref": "#/definitions/TypeKeyReference",
             "x-gw-extensions": {
               "typelist": "ActivityClass"
             }
           },
           . . .      }
       }
     }
   }

5. Fügen Sie im Eigenschaftenfeld createTime_Ext einen Eigenschaftswertetyp für datetime hinzu.

   Um den Wertetyp der Eigenschaft festzulegen, geben Sie ein Typen-Attribut ein und weisen Sie ihm den Wert „string“ zu. Fügen Sie anschließend ein Formatattribut hinzu und weisen Sie ihm den Wert date-time zu.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "definitions": {
       "Activity": {
         "properties": {
           . . .
           "createTime_Ext": {
             "type": "string",
             "format": "date-time"
           },
           . . .      }
       }
     }
   }

6. Fügen Sie im Eigenschaftenfeld createUser_Ext einen Eigenschaftswertetyp für das Objekt hinzu.

   Sie können einen Eigenschaftswertetyp für ein Objekt deklarieren, indem Sie ein $ref-Attribut zur Ressourceneigenschaft hinzufügen und ihr einen URI-Verweis für eine eingebettete Ressource zuweisen (weitere Informationen finden Sie im Abschnitt „Attribute“ in diesem Handbuch). Geben Sie hier ein $ref-Attribut ein und weisen Sie ihm den Wert #/definitionen/SimpleReference zu.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "definitions": {
       "Activity": {
         "properties": {
           . . .
           "createUser_Ext": {
             "$ref": "#/definitions/SimpleReference"
           },
           . . .
         }
       }
     }
   }

7. Fügen Sie im Eigenschaftenfeld shortSubject_Ext einen Wertetyp für die Eigenschaft Zeichenfolge hinzu.

   Um den Wertetyp der Eigenschaft festzulegen, geben Sie ein Typen-Attribut ein und weisen ihm den Wert string zu.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "definitions": {
       "Activity": {
         "properties": {
           . . .
           "shortSubject_Ext": {
             "type": "string"
           },
           . . .
         }
       }
     }
   }

8. Fügen Sie im Eigenschaftenfeld isAutogenerated_Ext einen Eigenschaftswertetyp für das Bit hinzu.

   Um den Wertetyp der Eigenschaft festzulegen, geben Sie ein Typen-Attribut ein und weisen ihm den Wert boolean zu.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "definitions": {
       "Activity": {
         "properties": {
           . . .
           "isAutogenerated_Ext": {
             "type": "boolean"
           }
         }
       }
     }
   }

9. Speichern Sie Ihre Änderungen.

Mapper erweitern

1. Öffnen Sie in Studio die der Common API zugeordnete Mapper-Erweiterungsdatei.

   Diese Datei befindet sich unter Integration > mappings > ext > common > v1 > common_ext-1.0.mapping.json.

   Die Basisdatei wird wie folgt angezeigt:

   {
     "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": {}
   }

2. Erstellen Sie im Feld mappers eine Mapper-Erweiterung für Activity.

   {
     . . .
     "mappers": {
       "Activity": {}
     }
   }

3. Fügen Sie in der Activity-Mapper-Erweiterung eine schemaDefinition-Eigenschaft hinzu und geben Sie ihr den Wert Activity. Dadurch wird der Mapper mit der Ressource Activity verknüpft.

   {
     . . .
     "mappers": {
       "Activity": {
         "schemaDefinition": "Activity"
       }
     }
   }

4. Fügen Sie eine Stammeigenschaft hinzu und weisen Sie ihr den Wert entity.Activity zu. So wird die Activity-Ressource mit der ClaimCenterActivity-Entität verknüpft.

   {
     . . .
     "mappers": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity"
       }
     }
   }

5. Fügen Sie die Eigenschaft properties hinzu und erstellen Sie darin Felder für jede der Eigenschaften, die Sie zuvor der Schemadefinitionserweiterung hinzugefügt haben.

   {
     . . .
     "mappers": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity",
         "properties": {
           "activityClass_Ext": {},
           "createTime_Ext": {},
           "createUser_Ext": {},
           "shortSubject_Ext": {},
           "isAutogenerated_Ext": {}
         }
       }
     }
   }

6. Konfigurieren Sie die Eigenschaft activityClass_Ext.
   1. Fügen Sie ein Pfad-Attribut hinzu und weisen Sie ihm den Wert Activity.ActivityClass zu.

      Dadurch wird die Ressourceneigenschaft dem ActivityClass-Entitätsfeld zugeordnet.

   2. Fügen Sie ein mapper-Attribut hinzu und weisen Sie ihm den Wert #/mappers/TypeKeyReference zu.

      Jede Eigenschaft, deren Typ durch einen URI-Verweis deklariert wird, muss über eine Zuordnung zu einem URI-Verweis für das zugehörige Zuordnungsschema verfügen.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "mappers": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity",
         "properties": {
           "activityClass_Ext": {
             "path": "Activity.ActivityClass",
             "mapper": "#/mappers/TypeKeyReference"
           },
           . . .
         }
       }
     }
   }

7. Fügen Sie in der Eigenschaft createTime_Ext ein Pfad-Attribut hinzu und weisen Sie ihm den Wert Activity.CreateTime zu.

   Dadurch wird die Ressourceneigenschaft dem CreateTime-Entitätsfeld zugeordnet.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "mappers": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity",
         "properties": {
           . . .
           "createTime_Ext": {
             "path": "Activity.CreateTime"
           },
           . . .
         }
       }
     }
   }

8. Konfigurieren Sie die Eigenschaft createUser_Ext.
   1. Fügen Sie ein path-Attribut hinzu und weisen Sie ihm den Wert Activity.CreateUser zu.

      Dadurch wird die Ressourceneigenschaft dem CreateUser-Entitätsfeld zugeordnet.

   2. Fügen Sie ein mapper-Attribut hinzu und weisen Sie ihm den Wert #/mappers/SimpleReference zu.

      Jede Eigenschaft, deren Typ durch einen URI-Verweis deklariert wird, muss über eine Zuordnung zu einem URI-Verweis für das zugehörige Zuordnungsschema verfügen.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "mappers": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity",
         "properties": {
           . . .
           "createUser_Ext": {
             "path": "Activity.CreateUser",
             "mapper": "#/mappers/SimpleReference"
           },
           . . .
         }
       }
     }
   }

9. Fügen Sie in der Eigenschaft shortSubject_Ext ein Pfad-Attribut hinzu und weisen Sie ihm den Wert Activity.ShortSubject zu.

   Dadurch wird die Ressourceneigenschaft dem ShortSubject-Entitätsfeld zugeordnet.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "mappers": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity",
         "properties": {
           . . .
           "shortSubject_Ext": {
             "path": "Activity.ShortSubject"
           },
           . . .
         }
       }
     }
   }

10. Fügen Sie der Eigenschaft isAutogenerated_Ext ein path-Attribut hinzu und weisen Sie ihm den Wert Activity.IsAutogenerated_Ext zu.

    Dadurch wird die Ressourceneigenschaft dem IsAutogenerated_Ext-Entitätsfeld zugeordnet.

    Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

    {
      . . .
      "mappers": {
        "Activity": {
          "schemaDefinition": "Activity",
          "root": "entity.Activity",
          "properties": {
            . . .
            "isAutogenerated_Ext": {
              "path": "Activity.IsAutogenerated_Ext"
            }
          }
        }
      }
    }

11. Speichern Sie Ihre Änderungen.

Updater erweitern

Dem Updater müssen Sie nur Ressourceneigenschaften hinzufügen, die durch einen POST- oder PATCH-Vorgang aktualisiert werden können. Verfügt eine Ressourcenerweiterung nicht über solchen Eigenschaften, muss keine Updater-Erweiterung erstellt werden.

Um einen Updater zu erstellen, der POST- oder PATCH-Operationen für die Eigenschaften isAutogenerated_Ext unterstützt, führen Sie die folgenden Schritte aus.

1. Öffnen Sie in Studio die mit der Common API verknüpften Erweiterungsdatei des Updaters.

   Diese Datei befindet sich unter Integration > updaters > ext > common > v1 > common_ext-1.0.updater.json.

   Die Basisdatei wird wie folgt angezeigt:

   {
     "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": {}
   }

2. Erstellen Sie im Feld updaters eine Updater-Erweiterung für Activity.

   {
     . . .
     "updaters": {
       "Activity": {}
     }
   }

3. Fügen Sie in der Updater-Erweiterung Activity eine schemaDefinition-Eigenschaft hinzu und weisen Sie ihr den Wert Activity zu.

   Dadurch wird der Updater mit der Activity-Ressource verknüpft.

   {
     . . .
     "updaters": {
       "Activity": {
         "schemaDefinition": "Activity"
       }
     }
   }

4. Fügen Sie eine root-Eigenschaft hinzu und weisen Sie ihr den Wert entity.Activity zu.

   So wird die Activity-Ressource mit der ClaimCenterActivity-Entität verknüpft.

   {
     . . .
     "updaters": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity"
       }
     }
   }

5. Fügen Sie eine properties-Eigenschaft hinzu und erstellen Sie dann ein Feld für jede der unterstützten Eigenschaften, wie in der Schemadefinitionserweiterung definiert.

   {
     . . .
     "updaters": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity",
         "properties": {
           "shortSubject_Ext": {},
           "isAutogenerated_Ext": {}
         }
       }
     }
   }

6. Fügen Sie der Eigenschaft isAutogenerated_Ext ein path-Attribut hinzu und weisen Sie ihm den Wert Activity.IsAutogenerated_Ext zu.

   Dadurch wird die Ressourceneigenschaft dem Entitätsfeld IsAutogenerated_Ext zugeordnet, sodass Eigenschaftsdaten in die InsuranceSuite-Datenbank geschrieben werden können.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "updaters": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity",
         "properties": {
           "isAutogenerated_Ext": {
             "path": "Activity.IsAutogenerated_Ext"
           },
           . . .
         }
       }
     }
   }

7. Fügen Sie in der Eigenschaft shortSubject_Ext ein path-Attribut hinzu und weisen Sie ihm den Wert Activity.ShortSubject zu.

   Dadurch wird die Ressourceneigenschaft dem ShortSubject-Entitätsfeld zugeordnet, sodass Eigenschaftsdaten in die InsuranceSuite-Datenbank geschrieben werden können.

   Der folgende Codeblock zeigt, wie das abgeschlossene Eigenschaftsfeld aussieht:

   {
     . . .
     "updaters": {
       "Activity": {
         "schemaDefinition": "Activity",
         "root": "entity.Activity",
         "properties": {
           . . .
           "shortSubject_Ext": {
             "path": "Activity.ShortSubject"
           }
         }
       }
     }
   }

8. Speichern Sie Ihre Änderungen.

Erweiterte Ressource überprüfen

Nach dem Erstellen der Schemadefinitionserweiterung können Sie die überarbeitete Schemadefinition in der Swagger-Benutzeroberfläche überprüfen.

1. Starten Sie die Swagger-Benutzeroberfläche und laden Sie dann die Common API.

   Details hierzu entnehmen Sie dem Cloud-API-Geschäftsabläufe- und Konfigurationshandbuch.

2. Wählen Sie den Endpunkt GET /common/v1/activities/{activityId} aus.
3. Wählen Sie unter Responses die Ansicht Model aus.
4. Überprüfen Sie im mit dem Abschnitt data.attributes verknüpften Activity-Schema das Vorhandensein der erweiterten Eigenschaften.

Darüber hinaus können Sie die überarbeitete Schemadefinition in Postman mit einigen Beispieldaten testen. In diesem Lernprogramm wird davon ausgegangen, dass Sie Postman in Ihrer Umgebung mit dem korrekten Beispieldatensatz eingerichtet haben. Weitere Informationen finden Sie im Cloud-API-Geschäftsabläufe- und Konfigurationshandbuch.

Zuerst können Sie das Antwortobjekt einer GET-Operation für die Erweiterungen der Ressourceneigenschaft überprüfen.

1. Starten Sie in Postman eine neue Anforderung, indem Sie auf das + rechts neben der Registerkarte Launchpad klicken.
2. Geben Sie als Basic Auth-Autorisierung den Benutzer aapplegate und das Kennwort gw an.
3. Geben Sie den folgenden Aufruf ein und klicken Sie dann auf Senden:

   GET http://localhost:8080/cc/rest/common/v1/activites/cc:201

4. Überprüfen Sie den Textkörper der Antwort. Dieser sieht wie folgt aus:

   {
       "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"
           },
           . . .
           }
       }
   }

Sie können den Updater testen, indem Sie einen PATCH-Vorgang für dieselbe Ressource ausführen:

1. Starten Sie in Postman eine neue Anforderung, indem Sie auf das + rechts neben der Registerkarte Launchpad klicken.
2. Geben Sie als Basic Auth-Autorisierung den Benutzer aapplegate und das Kennwort gw an.
3. Geben Sie den folgenden Aufruf ein, klicken Sie jedoch nicht auf Senden:

   PATCH http://localhost:8080/cc/rest/common/v1/activites/cc:201

4. Geben Sie die Anforderungs-Nutzdaten an.
   1. Klicken Sie in der ersten Zeile der Registerkarten (die mit Params beginnt) auf Body.
   2. Wählen Sie in der Optionsfeldzeile raw aus.
   3. Ändern Sie am Ende der Zeile mit den Optionsfeldern den Wert der Dropdown-Liste von Text in JSON.
   4. Kopieren Sie Folgendes in das Textfeld unter den Optionsfeldern:

      {
      	"data": {
      		"attributes": {
      			"isAutogenerated_Ext": true,
      			"shortSubject_Ext": "shortsub"
      		}
      	}
      }

5. Klicken Sie auf Senden. Die Antwort-Nutzdaten werden unterhalb der Anforderung-Nutzdaten angezeigt.

   {
       "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"
           },
           . . .
       }
   }