Introduction

This article will walk you through creating a dynamic form that includes three different types of data sources:

• A static data source that returns a list of temperature units
• A PowerShell data source that fetches current New York weather
• A task data source that fetches current New York weather

These are very simple examples, and production use cases are likely to be more complex. However, this article will get you started on the right foot.

All data sources are created during the process of creating or editing dynamic forms. After they have been created, they are listed in Data Sources - Overview. Each data source is tied to the form element in which it was created, and cannot be reused elsewhere.

Create or edit a form

The first step to get started with data sources is to create a dynamic form. You can accomplish this in two ways:

• By creating a standalone dynamic form in the Forms overview.
• Alternatively, if you are planning to use the form as a template for a delegated form, you can directly create the dynamic form on the delegated form's Form tab.

For this example, we'll create the following standalone dynamic form, named Weather report. All the elements on this form will use data sources, but we'll configure them later. To get started, we just need the following:

• A multistep form with 3 pages
• On page 1, a required Drop Down element named Temperature Unit, with the Key tempUnitDropdown. 
  
  Remove its default Values.
  
• On page 2, a Text element.
  
  
• On page 3, another Text element.
  
  

Create a static data source

Static data sources return the same data every time, without querying an external system. They are particularly useful to populate reusable form elements. The items in a static data source are defined as an array of JSON objects.

We will create a static data source to populate our dropdown form element on page 1.

1. Edit the dropdown element on page 1.
2. Enable the Use Data Source toggle.
   
3. Click Configure Datasource.
4. Enter a data source Name and select a Type. For this example, we'll name it Weather report static datasource and select Static as the Type.
   
5. Click Next.
6. In the JSON editor, replace the default example data with the following JSON and then click Suggest A Model: 

   [
     {
       "tempUnitLabel": "Fahrenheit",
       "tempUnitValue": "fahrenheit"
     },
     {
       "tempUnitLabel": "Celsius",
       "tempUnitValue": "celsius"
     }
   ]

   
7. Click Save. 
8. HelloID takes us back to the Edit Form Field dialog. For the Value Field, select tempUnitValue. For the Text Field, select tempUnitLabel. The Value Field drop down represents the actual data value which will be submitted, whereas the Text Field drop down represents the label that will be shown to the end user.
   
9. Click Update Field.
10. The static data source has been created. Click Save to save the form.

Create a PowerShell data source

PowerShell data sources are directly encapsulate their PowerShell script instead of relying on a separate task, and offer several other potential advantages. For nearly all purposes, we recommend using PowerShell data sources instead of task data sources.

Create the data source

1. Edit the Weather report form.
2. Edit the text element on page 2.
3. Enable the Use Data Source toggle.
   
4. Click Configure Datasource.
5. Enter a data source Name and select a Type. For this example, we'll name it Weather report PowerShell datasource and select PowerShell as the Type.
   
6. Click Next.
7. Create one Required input variable named tempUnit (which we will shortly connect to our Temperature unit dropdown on page 1).
   
8. Click Next.
9. In the script editor, enter the following PowerShell script: 

   $temperatureUnit = $($datasource.tempUnit.tempUnitValue)
   $locationEndpoint = "https://api.open-meteo.com/v1/forecast?latitude=40.71&longitude=-74.01&hourly=temperature_2m&temperature_unit=$temperatureUnit&windspeed_unit=mph&precipitation_unit=inch"
   Write-Information "Looking up New York weather"
   $response = Invoke-RestMethod -uri $locationEndpoint
   Write-Information "Response: $response"
   $result = @{weather = "Current time: $($response.hourly.time[0]); current temperature: $($response.hourly.temperature_2m[0]) degrees $temperatureUnit (PowerShell datasource)"}
   Write-Information "Result: $($result.weather)"
   $($result.weather)

   In your script, you can access variables defined on the Data Source Input page using their Keys. To do so, use the syntax $datasource.<FormElementKey>.<FormElementField>. For example, $($datasource.tempUnit.tempUnitValue) as shown above. You also have access to all variables described in the Service Automation variable reference. The Run On Cloud Agent toggle determines whether the script is executed via your HelloID tenant's cloud Agent (hosted by Tools4ever), or on a local server via a local Agent (hosted by your organization).
10. For the tempUnit input variable, enable the Interpreted As JSON toggle and manually specify the following test value. (In production, this value will come from the dropdown form element on page 1.)

    {
        "tempUnitLabel": "Celsius",
        "tempUnitValue": "celsius"
    }

    
11. Click Execute PowerShell to test the script.
12. Go to the Received Data tab.
13. The current New York weather has been fetched, in degrees Celsius.
    
14. Click Save. HelloID takes us back to the Edit Form Field dialog.
    
15. For the tempUnit input variable, enable the Use Value From Other Field toggle and select the Temperature unit dropdown element.  For the Display Field, select output.
    
16. Click Update Field.
17. The PowerShell data source has been created. Click Save to save the form.

Return results

The last line of your script should return a hash table with the results, either directly or with Write-Output. For this example:

$result = @{weather = "Current time: $($response.hourly.time[0]); current temperature: $($response.hourly.temperature_2m[0]) degrees $temperatureUnit (PowerShell datasource)"}
$($result.weather)

Task logging

See PowerShell data source task logging.

Audit logging

See PowerShell data source audit logging.

Create a task data source

Task data sources rely on custom PowerShell tasks to pull in data from external sources, such as REST APIs.

In this tutorial, we'll replicate the functionality of the PowerShell data source created above, but using a task data source.

Note: You should use PowerShell data sources instead of task data sources unless you have a specific reason to do otherwise. Task data sources are no longer being developed.

Create the task

Before we can create a task data source, we must first create the task that will supply data to it.

Go to Automation > Tasks and create a custom PowerShell task, using either a standalone script or encapsulated script. Name it Data Source: Weather report. Use the following PowerShell code, which fetches current New York weather and reports the temperature (using the unit specified by the end user):

$temperatureUnit = $($formInput.tempUnit.tempUnitValue)
$locationEndpoint = "https://api.open-meteo.com/v1/forecast?latitude=40.71&longitude=-74.01&hourly=temperature_2m&temperature_unit=$temperatureUnit&windspeed_unit=mph&precipitation_unit=inch"
Hid-Write-Summary -Message "Looking up New York weather" -Event Information
$response = Invoke-RestMethod -uri $locationEndpoint
Hid-Write-Summary -Message "Response: $response" -Event Information
$result = @{weather = "Current time: $($response.hourly.time[0]); current temperature: $($response.hourly.temperature_2m[0]) degrees $temperatureUnit (task datasource)"}
Hid-Write-Summary -Message "Result: $result" -Event Information
Hid-Add-TaskResult -ResultValue $result

The $formInput.<FormElementKey>.<FormElementField> syntax represents user-inputted variables that will be defined on the Data Source Input page. They are passed into the task data source, and subsequently into the attached PowerShell task, via the dynamic form. For example, $formInput.tempUnit.tempUnitValue as shown above. You also have access to all variables described in the Service Automation variable reference. Input variables can contain simple text and numbers, or nested JSON objects with their own properties (for example, in the case of a Grid element). Your script should handle empty input by using default values and/or graceful exit conditions.

Create the data source

Now that we have a task that returns data, we can create our data source.

1. Edit the Weather report form.
2. Edit the text element on page 3.
3. Enable the Use Data Source toggle.
   
4. Click Configure Datasource.
5. Enter a data source Name and select a Type. For this example, we'll name it Weather report task datasource and select Task as the Type.
   
6. Click Next.
7. On the Data Source Input page, create one Required input variable named tempUnit (which we will shortly connect to our Temperature unit dropdown on page 1). Notice that this is the same variable name that the PowerShell script in our task expects, via $formInput.tempUnit.
   
8. Click Next.
9. For the Task, select the Data Source: Weather report task we created earlier. For the Model Definition, create one field named weather. (It is not possible to preview this script, because our script requires JSON input, but task data sources cannot accept JSON input in preview. This is a reason why we recommend PowerShell data sources instead.)
   
10. Click Save. HelloID takes us back to the Edit Form Field dialog.
    
11. For the tempUnit input variable, enable the Use Value From Other Field toggle and select the Temperature unit dropdown element.  For the Display Field, select weather.
    
12. Click Update Field.
13. The task data source has been created. Click Save to save the form.

Return results

Use the Hid-Add-TaskResult cmdlet to return the task's results to the task data source.

Task logging

Use HelloID's built-in logging cmdlets to log messages. These messages are displayed in the Received Logs tab during preview. To view them in production, see View data source logs.

Variable reference

See the Service Automation variable reference.

See your data sources in action

1. Create a custom delegated form, and clone the Weather report dynamic form we created above.
   
2. Add it to the appropriate groups (e.g., to test it, the Admins group).
   
3. Launch it from the Servicedesk.
4. On each page of the delegated form, the respective data sources we created (static, task, PowerShell) feed their output into the form elements.