HSA

Overview of the HSA Pipes valve category and links to its configuration references.

HSA valves call HSA SOAP service contracts through the configured HTTP client and turn response records into pipe items. They are intended for integrations that need to retrieve employee, credential, or administrative credential information, including protected persons.

Prerequisites

Before using HSA valves, configure an HTTP client destination that can reach the HSA endpoint. If the upstream HSA environment requires mTLS, configure the HTTP client destination with the required client certificate and trust settings.

Common configuration

These configuration properties apply to all HSA valves.

Properties
Example

Name	Description	Default
`url`	HSA SOAP endpoint URL.	`""`
`destination`	HTTP client destination to use for the SOAP call.	`"default"`
`logical_address`	Logical addressee sent as the RIVTABP21 `LogicalAddress` SOAP header. The service platform uses this value as ReceiverId for routing.	`""`
`person_hsa_id`	Person HSA ID to look up. Configure either `person_hsa_id` or `personal_identity_number`.	`""`
`personal_identity_number`	Personal identity number to look up. Configure either `person_hsa_id` or `personal_identity_number`.	`""`
`search_base`	Optional HSA search base DN.	`""`
`include_feigned_object`	Optional boolean passed to the HSA request when configured.
`id_parameter`	Response property used as item ID.	Valve specific
`merge_with_current_item`	Merge each response record into the current item instead of creating or updating items by `id_parameter`.	`false`
`item_prefix`	Prefix used for generated item IDs when the response does not contain `id_parameter` or `dn`.	Valve specific
`response_element`	SOAP response element to convert into items.	Valve specific

{
  "name": "GetCredentialsForPersonIncludingProtectedPerson",
  "config": {
    "url": "https://hsa.example.test/service",
    "destination": "hsa",
    "logical_address": "SE165565594230-1000",
    "person_hsa_id": "${request.personHsaId}",
    "search_base": "c=SE"
  }
}

Item handling

Each SOAP response record matching the configured response_element is converted into one or more items depending on the valve. Most HSA valves create one item per response record and use personHsaId as the default item ID. GetCredentialsForPersonIncludingProtectedPerson creates one item per commission and uses commissionHsaId as the default item ID. If the selected ID value is not present, dn is used. If neither value exists, the valve creates an ID using item_prefix.

When merge_with_current_item is true, response properties are written to the current item instead. This is useful when a previous valve already created the item and the HSA lookup should enrich it.

Nested XML elements are flattened using underscores. For example, authorizationScopeProperties containing authorizationScopeCode becomes the item property authorizationScopeProperties_authorizationScopeCode. Repeated response elements become multivalue item properties.

The raw SOAP response is also stored in state.body, HTTP status code in state.status_code, and HTTP response headers in state.headers.

Error handling

HSA valves reject the pipe with a descriptive error message when a problem occurs. The raw response body is logged at DEBUG level alongside the error in all cases.

Situation	Error message
Response contains no matching `response_element` records	`HSA response did not contain expected element: <element>`
Response XML cannot be parsed	`Failed to parse HSA response: <detail>`
HSA service returns a non-OK HTTP status	`HSA service returned <status>: <SOAP faultstring>`

The SOAP faultstring is included in the error message when the upstream service returns a SOAP Fault, making it visible in pipe error logs without needing to inspect the raw body separately.

In this section