You're viewing help content for version:

Introduction

You can use web services in AEM Forms to populate fields of a form. AEM forms supports web services described in Web Services Description Language (WSDL) 1.1 with Document/literal style and that have SOAP endpoints. Consider a scenario where you want to display weekly weather forecast for the ZIP code specified by the user. You can create a rule to use an existing web service to pull the weather forecast data and then render the data in the form.

You can either specify the URL of the service directly while creating a rule or pre-configure a web service in CRX to make the web service available in rule editor as a menu item. This article explains how to pre-configure a web service in CRX with specific input and output parameters to make it available in rule editor. 

To create such a rule in the rule editor, the following are the pre-requisites:

  • An adaptive form with the appropriate form objects - one form object each for input parameters and one form object each for displaying the output parameters (here only one for displaying the weather forecast)
  • Pre-configure the web service in CRX with the input and output parameters

The scenario in this article utilizes the Weather Web Service by www.cdyne.com. For more information about the Weather web service, see the Weather Web Service specifications document.

You can also directly upload the attached Weather_WSDL.zip file to CRX to get this example working. 

Download

Set up a web service in CRX for rule editor

AEM forms supports web services described in Web Services Description Language (WSDL) 1.1 with Document/literal style and that have SOAP endpoints. Use the following steps to pre-configure a web service in CRX for the rule editor:

  1. Go to http://[server]:[port]/[ContextPath]/crx/de and login as Administrator.

  2. In the /apps folder, create a node (here GetCityForecastByZIP).

    Note:

    Create the web service node in the /apps folder. By default, web services can be set up in the apps and libs folders. However, the Admin can configure one or more other locations in the CRX where the Adaptive Forms users can configure the web services. This may be required, as the users may not have access to the apps and libs folders in CRX. For more information, see Configure the web service location in CRX.

    1. Right click apps folder and select Create > Create Node.

    2. Specify a name for the folder (here GetCityForecastByZIP), ensure that the node type is nt:unstructured and click OK.

    3. Click Save All.

  3. Add the following properties to the newly created node (here GetCityForecastByZip) and click Save All:

    Property Type Description Value
    guideComponentType String
    A constant that specifies the configuration identified as a web service fd/af/webServices
    url String URL of the web service that you are setting up http://wsf.cdyne.com/WeatherWS/Weather.asmx?WSDL
    jcr:title String Name of the web service as it appears in the rule editor drop-down Weekly weather of a city
    operation String The operation of the web service that is being set up
    GetCityForecastByZIP
  4. Create the following subnodes of type nt:unstructured under the web service node (here GetCityForecastByZip) and click Save All:

    • input
    • output
  5. Under the node named input, create subnodes for each of the input parameters you want to pre-configure. In the Weather web service scenario, create a node for the user to enter the ZIP code as input.

    Use the following steps to create a node for the input parameter:

    Note:

    If you do not add an input node, the form object and rule are populated with all the input parameters in the web service.

    1. Right click the node named input and select Create > Create Node.

    2. Enter a name for the child node (here ZIP) and click OK.

    3. Add the properties to the child node. In the Weather web service scenario, add the following properties to the child node and click Save All:

       Property Type Description Value
      id String
      Id of the input parameter as in the web service
      ZIP
      jcr:title
      String Name of the input parameter as it will appear to the user ZIP code
      defaultValue String Default Value for the parameter 
      90028
      hide
      Boolean Whether to hide the parameter
      False

      Note:

      If the hide property is set to true, you must specify a value for the defaultValue property, as the user is unable to view the input parameter and provide a value.

  6. Under the node named output, create subnodes for each of the output parameters you want to include in your configuration and displays to the user.

    Use the following steps to create a node (here weather Date) for the output parameter:

    Note:

    If you do not add an output node, the form object and rule are populated with all the output parameters in the web service.

    1. Right click the output node and select Create > Create Node.

    2. Enter a name for the child node (here weather Date) and click OK.

    3. Add the properties to the child node.

      In the Weather web service scenario, add the following properties to the child node and click Save All:

      Property Type Description Value
      id String
      ID of the output parameter as in the web service. ID is case sensitive.

      GetCityForecastByZIPResponse.GetCityForecastByZIPResult.

      ForecastResult.Forecast.Date

      jcr:title
      String Name of the output parameter as displayed to the user Date

      Using the above steps, create a second subnode (here Weather Description) and add the following properties to the subnode:

       

      Property Type Description Value
      id String
      ID of the output parameter as in the web service. ID is case sensitive.

      GetCityForecastByZIPResponse.GetCityForecastByZIPResult.

      ForecastResult.Forecast.Desciption

      jcr:title
      String Name of the output parameter as displayed to the user Description

      Note:

      The value of the id property includes the parameter name as "Desciption" and not "Description." This is as per the WSDL.

After the web service is preconfigured in CRX, create a rule based on the web service in rule editor for an adaptive form. If necessary, create an adaptive form where you could utilize the pre-configured web service.

Configure the web service location in CRX

By default, web services can be set up in apps and libs folders. Optionally, however, the Admin can set up one or more other locations in the CRX where the Adaptive Forms user can configure web services. This may be required, as the users may not have access to the apps and libs folders in CRX.

To configure web services locations in CRX, complete the following steps:

  1. Go to 
    http://[server]:[port_number]/system/console/configMgr and log in as Administrator.

  2. Open the Adaptive Form Configuration Service.

  3. In WSDL Config Search Paths, modify or add the config paths.

    ConfigureWebService
  4. Click Save.

Create an adaptive form for the GetCityForecastByZIP pre-configuration

For writing a rule based on the GetCityForecastByZip pre-configuration, you require an adaptive form that has:

  • A field where the user could enter the ZIP code 
  • A table where you can include the weekly weather for the ZIP code entered. In this scenario, make the row of the table repeatable by setting the maxOccur property to 7. The seven rows are required to render forecast for each day of the week.

The form for creating the weather web service-based rule would look like the following:

AFforWeatherRule

For more information on creating an adaptive form, see Creating an adaptive form.

Create a rule to invoke the web service in the adaptive form

After you have Set up a web service in CRX and have the right adaptive form for creating the rule, you can write a rule to invoke the web service to populate a form object. 

Complete the following steps to create a web service-based rule for a field (here ZIP Code):

  1. Open the appropriate form in authoring mode. Tap the ZIP Code field and tap  . Next, tap Create to launch the rule editor.

    CreateRuleVisualEditor
  2. Tap Select State drop-down and select Is Changed.

    The Is Changed event invokes the rule whenever the value of the field (here ZIP Code) is changed. To create this rule differently, you can use other events and operators in rule editor.

    2_WSWriteRuleVisualEditor_IsChanged
  3. In the Then statement, select Invoke Service from the Select Action drop-down. The Enter Web Service URL drop-down appears. 

    3_WSWriteRuleVisualEditor_Invoke
  4. In the Enter Web Service URL field, tap  and select the name of the web service (here Weekly weather of a city) that you have set up in CRX. The Input and Output placeholders appear.

    To invoke a web service that is not set up in the CRX, you can enter the web service URL directly in the Enter Web Service URL field.

    4_WSWriteRuleVisualEditor_WeatherWeek

    Note:

    In this scenario, while creating the input node in CRX, the default value of the parameter is set to 90028. To display the weather forecast for the default zip code (90028), skip step 5. Or, to use the user-specified value in the Zip Code field as input, proceed with step 5. 

    Note:

    If the Input and Output placeholders do not appear when you select the web service's name, check the ID property of the pertinent output folder in CRX. Make sure that the ID is entered correctly and with the correct case.

  5. To use a user-specified value in the Zip Code field instead of the default value set in CRX, do the following:

    1. In the Input placeholder, delete the default value and choose to enter a component.

      5_WSWriteRuleVisualEditor_Input
    2. Select or drag-drop from the Forms Object tab the ZIP Code field in the Input Drop object.

  6. In the Output placeholder, drag-drop from the Forms Object tab the two Text Box fields of the table to the Drop objects:

    1. Drag-drop the text box pertinent to Date in your table under the GetWeatherInformationResult.WeatherDescription.Date output parameter. 

    2. Drag-drop the text box pertinent to Weather in your table to the GetWeatherInformationResult.WeatherDescription.Description output parameter.

      6_WSWriteRuleVisualEditor_InputOutput
  7. Tap Done to save the rule. 

Populate form objects using the web-service based rule

In the adaptive form in which you have created the web service-based rule, do the following to populate the form objects using the web service:

  • In the ZIP Code field, enter the ZIP code of the city to check the weather. 

    AFforWeatherRule

    When you move the cursor out from the ZIP Code field, the table is populated with day-wise weather for the week. For example, you enter the ZIP code for San Jose, CA (95111) and then tab out/move the cursor out of the ZIP Code field, the table displays the weekly weather as the following:

    WeatherRuleInfo

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy