Integrera externa API:er med Visual Rule Editor i Core Component Forms

Visuell regelredigerare i ett adaptivt formulär har stöd för funktionen Anropa tjänst som gör att du kan ansluta till externa API:er via formulärdatamodeller (FDM) som konfigurerats för din instans. Du kan mappa formulärfält direkt till tjänstens indataparametrar och använda händelsens nyttolastalternativ för att mappa utdataparametrarna. Med Visual Rule Editor kan du också definiera regler för hanterare för lyckade och misslyckade åtgärder baserat på tjänstens svar: hanterare för lyckade API-anrop hanterar felhanterare.

På så sätt kan du enkelt skicka API-begäranden från formuläret, bearbeta API-svaren och visa eller använda returnerade data dynamiskt i formuläret. Det säkerställer en sömlös integrering mellan era adaptiva formulär och externa system eller datakällor.

Fördelar med att använda Invoke Service i formulärets regelredigerare

Här är några fördelar med att använda Invoke Service-åtgärden i regelredigeraren för ett tilläggsformulär:

Anropa tjänsthanterare för lyckade och misslyckade åtgärder

Med den visuella regelredigeraren kan du skapa regler för hanterare för lyckade och misslyckade åtgärder för Invoke Service -åtgärder baserat på dess utdataresvar. Nedanstående bild visar Invoke Service i Visual rule editor för ett adaptivt format:

Adding Success Handler and Failure Handler

Klicka på Add Success Handler eller Add Failure Handler om du vill lägga till en hanterare för lyckade eller misslyckade åtgärder.

När du klickar på Add Success Handler visas regelredigeraren Invoke Service Success Handler så att du kan ange regler eller logik för att hantera Invoke Service -utdatasvaret när åtgärden har slutförts. Du kan ange regler även utan att definiera villkor, men du kan lägga till villkor för hanteraren av lyckade åtgärder genom att klicka på alternativet Add Condition.

Du kan lägga till flera regler för att hantera lyckade svar för åtgärden Anropa tjänst:

{width="50%,"}

På samma sätt kan du lägga till regler för att hantera Invoke Service -utdataresvaret när åtgärden inte lyckas. Bilden nedan visar regelredigeraren Invoke Service Failure Handler:

Du kan också lägga till flera regler för att hantera misslyckade svar från åtgärden Anropa tjänst.

Funktionen Aktivera felvalidering på servern tillåter validering som lagts till av författaren när ett adaptivt formulär utformas för att köras på servern också.

Krav för att använda Invoke Service i regelredigeraren

Nedan visas de krav du måste uppfylla innan du kan använda Anropa tjänst i regelredigeraren:

Utforska Invoke Service via olika användningsfall

Med den visuella regelredigerarens Anropa tjänst kan du utföra flera användbara åtgärder. Du kan använda den för att fylla i listrutealternativ, ange repeterbara eller enkla paneler och validera formulärfält, allt baserat på utdatasvaret för Anropa tjänst. Detta gör formulären mer flexibla och interaktiva.

Tabellen nedan beskriver några scenarier där Invoke Service kan användas:

Skapa ett Get Information-formulär som hämtar värden baserat på indata som anges i textrutan Pet ID. Skärmbilden nedan visar det formulär som används i dessa fall:

Formulärfält

Lägg till följande fält i formuläret:

NOTE

I fältet Bindningsreferens i dialogrutan Egenskaper i formulärfälten väljer du och navigerar till den binära egenskap som du har lagt till i formulärdatamodellen (FDM).

Konfigurerar paneler

Ange panelerna som repetitiva med följande begränsningar:

Du kan justera värdena för de upprepade panelerna så att de passar dina behov.

Datakälla

I det här exemplet används API:t Swagger Petstore för att konfigurera en datakälla. Formulärdatamodellen har konfigurerats för tjänsten getPetById, som hämtar information om djur baserat på det angivna ID:t.

Låt oss publicera följande JSON med tjänsten addPet i Swagger Petstore API:

{
        "id": 101,
        "category": {
            "id": 1,
            "name": "Labrador"
        },
        "name": "Lisa",
        "photoUrls": [
            "https://example.com/photos/lisa1.jpg",
            "https://example.com/photos/lisa2.jpg"
        ],
        "tags": [
            {
                "id": 1,
                "name": "vaccinated"
            },
            {
                "id": 2,
                "name": "friendly"
            },
            {
                "id": 3,
                "name": "house-trained"
            }
        ],
        "status": "available"
    }

Regler och logik implementeras med åtgärden Anropa tjänst i regelredigeraren i textrutan Pet ID för att visa de angivna användningsexemplen.

Nu ska vi gå igenom implementeringen av varje användningsfall i detalj.

Användningsfall 1: Fyll i listrutevärden med hjälp av utdata från Invoke Service

Det här användningsexemplet visar hur du fyller i listrutealternativ dynamiskt baserat på utdata för en Invoke Service.

Implementering

För att uppnå detta skapar du en regel i textrutan Pet ID som anropar tjänsten getPetById. I regeln anger du egenskapen enum för listrutan photo-url till photoUrls i Add Success Handler.

Utdata

Ange 101 i textrutan Pet ID för att dynamiskt fylla i listrutealternativen baserat på det angivna värdet.

Alternativen för listrutor kan också fyllas i dynamiskt genom att en tjänst anropas, JSON-svaret tolkas och anpassade funktioner tillämpas. Mer information finns i det här avsnittet.

Användningsfall 2: Ange upprepningsbar panel med utdata från Invoke Service

Det här användningsexemplet visar hur du fyller i repeterbara paneler dynamiskt baserat på utdata från en Invoke Service.

Överväganden

Implementering

Skapa en regel i textrutan Pet ID för att anropa tjänsten getPetById. I Add Success Handler lägger du till ett annat svar från en hanterare. Ange värdet tags för panelen tags i regeln.

Utdata

Ange 101 i textrutan Pet ID om du vill fylla i den repeterbara panelen dynamiskt baserat på indatavärdet.

Användningsfall 3: Ange panel med utdata från Invoke Service

Det här användningsexemplet visar hur du dynamiskt anger värdet för en panel baserat på utdata från en Invoke Service.

Överväganden

Implementering

Skapa en regel i textrutan Pet ID för att anropa tjänsten getPetById. I Add Success Handler lägger du till ett annat svar från en hanterare. Ange värdet categoryname för textrutan category.name i regeln.

Utdata

Ange 101 i textrutan Pet ID för att fylla i panelen dynamiskt baserat på indatavärdet.

Använd fall 4: Använd utdataparametern för Invoke Service för att validera andra fält

Det här användningsexemplet visar hur du använder utdata från en Anropa tjänst för att dynamiskt validera andra formulärfält.

Implementering

Skapa en regel i textrutan Pet ID för att anropa tjänsten getPetById. I Add Failure Handler lägger du till ett felhanterarsvar. Dölj knappen Skicka om en felaktig Pet ID anges.

Utdata

Ange 102 i textrutan Pet ID och knappen Skicka är dold.

Använd fall 5: Använd händelsenyttolast i Navigera till åtgärd i Anropa tjänst

Det här användningsexemplet visar hur du konfigurerar en regel på knappen Skicka som anropar en Invoke Service och sedan dirigerar om användaren till en annan sida med åtgärden Navigera till .

Implementering

Skapa en regel på knappen Skicka för att anropa API-tjänsten redirect-api. Den här tjänsten ansvarar för att dirigera om användaren till formuläret Kontakta oss.

Du kan direkt integrera ett API som API-tjänst för redirect-api i regelredigeraren med JSON-data som anges nedan:

{
  "id": "1",
  "path": "/content/dam/formsanddocuments/contact-detail/jcr:content?wcmmode=disabled"
}

I Add Success Handler konfigurerar du åtgärden Navigera till så att användaren dirigeras om till sidan Kontakta oss med parametern Event Payload. Här kan användaren skicka sin kontaktinformation.

Du kan också konfigurera en felhanterare så att ett felmeddelande visas om anropet till tjänsten misslyckas.

Utdata

När du klickar på knappen Skicka anropas API-tjänsten redirect-api. Användaren omdirigeras till sidan Kontakta oss när åtgärden har slutförts.

Hämta egenskapsvärden från en JSON-array

Det här är en tidig adopter-funktion. Om du är intresserad kan du skicka ett e-postmeddelande från din arbetsadress till mailto:aem-forms-ea@adobe.com och begära åtkomst till funktionen.

Adaptiv Forms stöder anrop av en tjänst, bearbetning av JSON-svar och dynamisk ifyllning av formulärfält. I det här avsnittet beskrivs hur du extraherar egenskapsvärden från en JSON-array och binder dem till formulärfält.

Exempel på JSON-svar

I följande exempel visas USA:s försäljningsregioner och en lista över säljare:

[
  {
    "region": "East",
    "salesPerson": "Emily Carter"
  },
  {
    "region": "South",
    "salesPerson": "Michael Brown"
  },
  {
    "region": "Midwest",
    "salesPerson": "Sophia Martinez"
  },
  {
    "region": "Southwest",
    "salesPerson": "David Johnson"
  },
  {
    "region": "West",
    "salesPerson": "Linda Walker"
  }
]

Egen funktion för att extrahera egenskapsvärden

Använd följande anpassade funktion för att extrahera egenskapsvärden från JSON-arrayen.

/**
 * Returns an array of values for a specific property from an array of objects.
 *
 * @name getPropertyValues
 * @param {Object[]} jsonArray An array of objects
 * @param {string} propertyName The property whose values should be extracted
 * @returns {Array} An array containing the values of the specified property
 *
 */

function getPropertyValues(jsonArray, propertyName)
{
    return jsonArray.map((obj) => obj[propertyName]);

}

Den anpassade funktionen accepterar:

Den anpassade funktionen returnerar en enkel array med värden.

Använda funktionen i Regelredigeraren

Så här hämtar du det specifika värdet från JSON-arrayen:

event.payload.invokeServiceResponse.rawPayloadBody

I följande exempel visas hur du fyller i ett Sales Department-formulär med det här svaret.

Låt oss till exempel skapa ett Sales Department-formulär som innehåller listrutorna Select Region och Select Sales Representative.

Steg 1: Anropa tjänsten vid formulärinitiering

WHEN
    Form is initialized
THEN
    Invoke Service → salesdeptinfo

Steg 2: Fyll i listrutan Region

Lägg till en Success Handler för tjänstanropet och konfigurera följande åtgärd:

Set enum → Region dropdown
getPropertyValues(
    event.payload.invokeServiceResponse.rawPayloadBody,
    "region"
)

Den här regeln läser JSON-arrayen, extraherar egenskapsvärdena för region och tilldelar värdena till listrutan Select Region.

Konfigurera på samma sätt åtgärden för listrutan Select Sales Representative i Success Handler.

När formuläret läser in JSON-data returneras och den anpassade funktionen extraherar egenskapsvärden och listrutan fylls i automatiskt:

Frågor och svar

F: Vad händer om jag har skapat en regel med Invoke Service och sedan uppgraderar till den senaste versionen av kärnkomponenterna?

A: När du uppgraderar till den senaste versionen av kärnkomponenterna uppdateras regeln Anropa tjänst automatiskt till det senaste användargränssnittet eftersom den är bakåtkompatibel.

F: Kan jag lägga till flera regler för att hantera lyckade eller misslyckade svar för Invoke Service-åtgärden?

S: Ja, du kan lägga till flera regler för att hantera slutförda eller misslyckade svar för åtgärden Anropa tjänst.

Relaterade artiklar

Ytterligare resurser