Azure Integration built-in role
FHIR Data Converter
Executes the FHIR service `$convert-data` data-plane operation to convert HL7v2, C-CDA, JSON, or FHIR STU3 input into FHIR R4 bundles. It has no control-plane Actions and does not by itself persist the converted bundle into the FHIR repository.
Role-definition permissions are imported from Microsoft Learn. Practical scope, use cases, prerequisites, best practices, security considerations, assignment guidance, and relationships have been reviewed against the official sources below.
Role definition ID: a1705bd2-3a8f-45a5-8683-466fcfd5cc24
Control-plane actions (0)
None — this role grants no control-plane management actions.
Data-plane actions (2)
Microsoft.HealthcareApis/services/fhir/resources/convertData/actionMicrosoft.HealthcareApis/workspaces/fhirservices/resources/convertData/action
Excluded actions (0)
None
Assignable scopes (1)
/
Practical scope
Assign on the individual FHIR service whose conversion endpoint the workload may call. Parent-scope assignments make the conversion operation available on additional inherited FHIR services.
Common use cases (2)
- Convert HL7v2, C-CDA, custom JSON, or FHIR STU3 payloads into FHIR R4 as one step in an approved ETL pipeline.
- Run a controlled conversion workflow before validation, enrichment, deduplication, and persistence to a FHIR service.
Prerequisites (2)
- The FHIR service must exist and the calling identity must authenticate with Microsoft Entra ID.
- Select and validate the Liquid template collection, root template, input format, and downstream validation and persistence steps.
Best practices (3)
- Host and register your own reviewed conversion templates for consistent production behavior instead of depending on unsupported default templates.
- Validate converted bundles against required FHIR profiles before persistence and assign the converter role only on the target service.
- Grant separately documented persistence authorization only to the component that writes or imports the converted output.
Security considerations (3)
- Conversion requests and returned bundles can contain protected health information even though the role does not persist the result by itself.
- Microsoft states that default templates are unsupported, not intended for production, and can change; unreviewed mappings can transform clinical data incorrectly.
- A parent-scope assignment exposes conversion endpoints on every inherited FHIR service.
Assignment guidance
Assign FHIR Data Converter to the ETL conversion identity on the specific FHIR service. Register reviewed templates, validate output, and grant persistence permissions separately to the component that writes or imports the converted bundle.
Common questions
When should I assign the FHIR Data Converter Azure role?
Assign FHIR Data Converter when you need to: Convert HL7v2, C-CDA, custom JSON, or FHIR STU3 payloads into FHIR R4 as one step in an approved ETL pipeline.; and Run a controlled conversion workflow before validation, enrichment, deduplication, and persistence to a FHIR service.. Practical scope: Assign on the individual FHIR service whose conversion endpoint the workload may call. Parent-scope assignments make the conversion operation available on additional inherited FHIR services.
What permissions does the FHIR Data Converter Azure role grant?
The role definition grants 2 combined control-plane and data-plane actions. Representative operations include: Microsoft.HealthcareApis/services/fhir/resources/convertData/action; and Microsoft.HealthcareApis/workspaces/fhirservices/resources/convertData/action. Review the permission sections above for the complete definition and exclusions.
What are the security risks of the FHIR Data Converter Azure role?
Key considerations when assigning FHIR Data Converter: Conversion requests and returned bundles can contain protected health information even though the role does not persist the result by itself.; Microsoft states that default templates are unsupported, not intended for production, and can change; unreviewed mappings can transform clinical data incorrectly.; and A parent-scope assignment exposes conversion endpoints on every inherited FHIR service.. Follow the assignment guidance above and use the narrowest practical scope.
Editorial sources (7)
- Azure built-in roles for Integration - Azure RBAC | Microsoft Learn →
Supports: Description, Security considerations. Retrieved 2026-07-17.
- Understand Azure role definitions →
Supports: Description. Retrieved 2026-07-17.
- Steps to assign an Azure role →
Supports: Assignment guidance. Retrieved 2026-07-17.
- Understand scope for Azure RBAC →
Supports: Practical scope. Retrieved 2026-07-17.
- Best practices for Azure RBAC →
Supports: Best practices. Retrieved 2026-07-17.
- Configure Azure RBAC roles for Azure Health Data Services →
Supports: Practical scope, Assignment guidance. Retrieved 2026-07-17.
- $convert-data in the FHIR service →
Supports: Description, Common use cases, Prerequisites, Best practices, Security considerations, Assignment guidance. Retrieved 2026-07-17.