API-Rollendateien

API-Rollen werden in YAML-Dateien mit dem Namen RoleName.role.yaml definiert. Zum Beispiel:

  • Account_Holder.role.yaml
  • Producer.role.yaml
  • Underwriter.role.yaml

Speicherort von API-Rollendateien

API-Rollen werden in Studio im Verzeichnis Integration > roles deklariert. Bei der Suche nach Rollendateien suchen die System-APIs nur in diesem Verzeichnis (und nicht in Unterverzeichnissen des Verzeichnisses roles).

Anmerkung: In den meisten Fällen, wenn ein Versicherer Dateien zu einer Instanz von PolicyCenter hinzufügt, ist das bewährte Verfahren, diese Dateien zu einem nach dem Versicherer benannten Unterverzeichnis hinzuzufügen. Dieses Verfahren ist für Versicherer jedoch mit Rollendateien nicht möglich. Damit eine Rollendatei für die System-APIs verfügbar ist, muss die Datei direkt im Verzeichnis roles deklariert werden. Sie kann nicht in einem Unterverzeichnis deklariert werden.

Struktur von API-Rollendateien

API-Rollen werden in Studio im Verzeichnis Integration > roles deklariert. Jede Datei nennt:

  • den Rollennamen
  • die Endpunkte und Endpunktoperationen für zugehörige Benutzer
  • die Felder, die zugehörige Benutzer anzeigen oder bearbeiten können

Beachten Sie, dass diese Teile in beliebiger Reihenfolge aufgeführt werden können.

API-Rollennamen

Guidewire empfiehlt, für den in der Datei deklarierten Rollennamen und den Rollennamen die gleiche Zeichenfolge zu verwenden, wie sie im Dateinamen angezeigt wird. Wenn ein API-Rollenname aus mehreren Wörtern bestehen muss, empfiehlt Guidewire, im Dateinamen Unterstriche und im Abschnitt Role Name der Datei Leerzeichen zu verwenden.

Beispiel: Wenn eine neue API-Rolle für Betrugsermittler (Fraud Investigators) vorgesehen ist:

  • Nennen Sie die Datei Fraud_Investigator.role.yaml.
  • Deklarieren Sie in der Datei den Namen als name: „Fraud Investigator“.

Für API-Rollen für interne Benutzer:

  • Den entsprechenden Benutzern muss in PolicyCenter eine Benutzerrolle zugewiesen sein.
  • Der Name der API-Rolle und der Name der Benutzerrolle müssen identisch sein.

Für API-Rollen für externe Benutzer:

  • Der IdP muss jeden Benutzer mit dem API-Rollennamen verknüpfen können.
  • Der IdP muss die Rolle mit einer „cc.“- oder „pc.“-Teilzeichenfolge identifizieren, gefolgt vom Rollennamen.
    • Die Zeichenfolge im IdP, die die Rolle identifiziert, muss mit cc./pc. beginnen. Die Teilzeichenfolge nach dem cc./pc. muss mit dem Rollennamen übereinstimmen. Beispiel: „cc.Manager“ wird mit der Rolle „Manager“ verglichen.)

Für API-Rollen für Services:

  • Guidewire empfiehlt, die Rolle insurercode_name (z. B. acme_locationphotos) zu benennen, wobei:
    • insurercode ein Versicherercode ist, z. B. acme.
    • name ein aussagekräftiger Name in Kleinbuchstaben ist.
  • Wenn der Service bei Guidewire Hub registriert ist, muss die Rolle mit vorangestelltem „cc.“ oder „pc.“ benannt werden. Fügen Sie das Präfix jedoch nicht im Namen der API-Rollendatei oder im Abschnitt Role Name ein.

Beachten Sie, dass die Benennungskonventionen für API-Rollen für Services auch für Folgendes verwendet wird:

  • API-Rollen für Guidewire-Services (z. B. die API-Rolle für den Cloud Rating-Service, benannt als gw_cloudrating)
  • API-Rollen für andere Guidewire-Funktionen, die eine Verbindung mit PolicyCenter herstellen (z. B. die API-Rolle für die Cloud Rules Engine, benannt als gw_cloudrulesengine)

API-Rollenendpunkte

Im Abschnitt endpoints werden die Endpunkte angegeben, die ein Empfänger verwenden kann, sowie die Operationen (GET, POST, PATCH oder DELETE), die ein Empfänger für diesen Endpunkt verwenden kann. Dieser Abschnitt dient als Allowlist. Standardmäßig kann ein Aufrufer für keinen Endpunkt eine Operation verwenden. Um die Endpunktverwendung zu aktivieren, müssen alle Endpunkte und Operationen explizit auf die Allowlist gesetzt werden.

Der Abschnitt endpoints enthält eine Liste von Endpunkten in folgendem Muster:

endpoints:
  - endpoint: <endpoint 1>
    methods:
    - <method 1 on endpoint 1>
    - <method 2 on endpoint 1>
  - endpoint: <endpoint 2>
    methods:
    - <method 1 on endpoint 2>
    - <method 2 on endpoint 2>

Platzhalter im Abschnitt endpoints

Sie können den Platzhalter Sternchen (*) im Abschnitt endpoints verwenden.

Ein einzelnes *-Platzhalterzeichen gibt an, dass der Zugriff alles gewährt wird, was sich eine Ebene unterhalb der aktuellen Endpunktebene befindet. Zum Beispiel:

  • /common/v1/activities/* bedeutet „alles eine Ebene unter /activities“.
  • /common/v1/activities/*/notes bedeutet „die Notizen für alles, was eine Ebene unter /activities liegt“.

Ein doppeltes **-Platzhalterzeichen gibt an, dass der Zugriff auf alles gewährt wird, was unter der aktuellen Ebene liegt. Zum Beispiel:

  • /common/v1/activities/** bedeutet „jede Ressource oder jeden Endpunkt, auf die/den über den Pfad /common/v1/activities zugegriffen werden kann“.

Seien Sie vorsichtig, wenn Sie ** verwenden.

Guidewire empfiehlt Versicherern, bei Verwendung des Platzhalters ** Vorsicht walten zu lassen. Der Grund dafür ist, dass spätere Versionen der System-APIs neue Endpunkte hinzufügen können, auf die Benutzer über **-Platzhalter dann unerwartet zugreifen können. Als Beispiel folgende Annahme: In Version 1.0 erstellt ein Versicherer eine API-Rolle, die Zugriff auf common/v1/activities/** bietet. Ab Version 1.0 bietet dies Zugriff auf Folgendes:

  • common/v1/activities/{activityId}
  • common/v1/activities/{activityId}/assignees
  • common/v1/activities/{activityId}/notes

Anschließend fügt Guidewire in Version 2.0 den folgenden Endpunkt hinzu:

  • common/v1/activities/{activityId}/confidentialAnalysis

Die API-Rolle hat dann automatisch Zugriff auf den neuen Endpunkt, auch wenn der Versicherer dies beim Erstellen der API-Rolle für Version 1.0 nicht beabsichtigt hatte.

Für API-Rollen zugängliche Felder

Im Abschnitt accessibleFields werden die Felder jeder Ressource angegeben, die ein Empfänger anzeigen oder bearbeiten kann. Dieser Abschnitt dient als Allowlist. Standardmäßig kann ein Aufrufer keine Felder einer Ressource anzeigen oder bearbeiten. Um Anzeige- und Bearbeitungsfunktionen zu aktivieren, müssen alle Ressourcen, Felder und Berechtigungen explizit auf die Allowlist gesetzt werden.

Der Abschnitt accessibleFields enthält eine Liste mit Ressourcen in folgendem Muster:

accessibleFields:
  <Resource 1>:
    edit:
    - <fields the grantee can edit on resource 1>
    view:
    - <fields the grantee can view on resource 1>
  <Resource 2>:
    edit:
    - <fields the grantee can edit on resource 2>
    view:
    - <fields the grantee can view on resource 2>

Ressourcen auf die Allowlist setzen

Ressourcen können auf verschiedene Weise benannt werden. Sie können die Ressource explizit benennen. Im Folgenden werden beispielsweise Berechtigungen nur für die Activity-Ressource angegeben.

accessibleFields:
  Activity:
    edit:
    - <fields the grantee can edit on this resource>
    view:
    - <fields the grantee can view on this resource>

Sie können auch das „*“-Platzhalterzeichen verwenden. In diesem Zusammenhang bedeutet es „alle Ressourcen, die für die im endpoints-Abschnitt aufgeführten Endpunkte verfügbar sind“. Im Folgenden werden beispielsweise Berechtigungen für alle Ressourcen angegeben, die für die Endpunkte der Rolle verfügbar sind:

accessibleFields:
  "*":
    edit:
    - <fields the grantee can edit on this resource>
    view:
    - <fields the grantee can view on this resource>

Felder auf die Allowlist setzen

Für jede Ressource können Sie zwei Berechtigungen auf Feldebene angeben: edit und view. Wenn eine Berechtigung nicht explizit aufgelistet wird, haben Aufrufer diese Berechtigung für keine Felder der Ressource.

Berechtigungen auf Feldebene können auf verschiedene Weise benannt werden. Sie können das Feld und die Berechtigung explizit benennen. Im Folgenden wird beispielsweise der Bearbeiten-Zugriff auf das Feld subject der Ressource Activity gewährt und der Zugriff auf das Feld field und das Feld subject angezeigt.

accessibleFields:
  Activity:
    edit:
    - "subject"
    view:
    - "priority"
    - "subject"

Sie können auch das „*“-Platzhalterzeichen verwenden. In diesem Zusammenhang bedeutet es „alle Felder“. Im Folgenden wird beispielsweise der Bearbeiten-Zugriff auf das Feld subject der Ressource Activity gewährt und der Anzeigen-Zugriff auf alle Felder gewährt.

accessibleFields:
  Activity:
    edit:
    - "subject"
    view:
    - "*"

Einige Ressourcenschemas kennzeichnen einzelne Felder mit der Sicherheitsebene internal, sensitive oder public. Beim Angeben von Feldberechtigungen können Sie den Ausdruck „*<level>“ verwenden, um „alle Felder der Ressource mit der angegebenen Ebene“ anzugeben. Im folgenden Beispiel wird Zugriff auf Felder der Ressource Job gewährt. Der Empfänger kann alle Felder der Ressource Job bearbeiten und anzeigen, die die Sicherheitsebene „public“ aufweisen, sowie das Feld jobFilter (das vermutlich nicht die Sicherheitsebene „public“ aufweist).

accessibleFields:
  Job:
    edit:
    - "*public"
    - jobFilter
    view:
    - "*public"
    - jobFilter

Weitere Informationen zu den Sicherheitsebenen finden Sie unter Sicherheitsebenen.

Beispiel für eine API-Rolle

Das Folgende ist beispielsweise ein Teil des Inhalts der Datei Underwriter.role.yaml:

name: Underwriter 
endpoints:
  - endpoint: /account/v1/accounts
    methods:
    - GET
    - POST
  - endpoint: "/account/v1/accounts/*"
    methods:
    - GET
    - PATCH
  - endpoint: "/account/v1/accounts/*/activities"
    methods:
    - GET
    - POST
    ...
accessibleFields:
  "*":
    view: "*"
    edit: "*"

Beachten Sie basierend auf diesem Teil Folgendes:

  • Ein Benutzer mit der Rolle „Underwriter“ kann Folgendes verwenden:
    • GET und POST am /account/v1/accounts-Endpunkt
    • GET und PATCH an allen Endpunkten eine Ebene unter /account/v1/accounts
    • GET und POST für Aktivitäten für alle Ressourcen eine Ebene unter /account/v1/accounts
  • Ein Benutzer mit der Rolle „Underwriter“ kann alle Felder der verfügbaren Endpunkte anzeigen und bearbeiten.